Overview

  • index

Resources

  • Scipy.org website

NumPy v1.9 Manual

Welcome! This is the documentation for NumPy 1.9.0, last updated Nov 20, 2014.

Parts of the documentation:

Numpy User Guide
start here

Numpy Reference
reference documentation

F2Py Guide
f2py documentation

Numpy Developer Guide
contributing to NumPy

Indices and tables:

General Index
all functions, classes, terms

Glossary
the most important terms explained

Search page
search this documentation

Complete Table of Contents
lists all sections and subsections

Meta information:

Reporting bugs

About NumPy

Numpy Enhancement Proposals

Release Notes

License of Numpy

Acknowledgements

Large parts of this manual originate from Travis E. Oliphant's book "Guide to Numpy" (which generously entered Public Domain in August 2008). The reference documentation for many of the functions are written by numerous contributors and developers of Numpy, both prior to and during the Numpy Documentation Marathon.

The preferred way to update the documentation is by submitting a pull request on Github (see the Developer Guide. The Numpy Documentation Wiki can also still be used to submit documentation fixes. Please help us to further improve the Numpy documentation!

  • © Copyright 2008-2009, The Scipy community.
  • Last updated on Nov 20, 2014.
  • Created using Sphinx 1.2.3.


NumPy User Guide

  • NumPy v1.9 Manual
  • next
  • previous

Previous topic

Numpy manual contents

Next topic

Introduction

NumPy User Guide

This guide is intended as an introductory overview of NumPy and explains how to install and make use of the most important features of NumPy. For detailed reference documentation of the functions and classes contained in the package, see the NumPy Reference.

Warning

This “User Guide” is still a work in progress; some of the material is not organized, and several aspects of NumPy are not yet covered sufficient detail. We are an open source community continually working to improve the documentation and eagerly encourage interested parties to contribute. For information on how to do so, please visit the NumPy doc wiki.

More documentation for NumPy can be found on the numpy.org website.

Thanks!

  • Introduction
    • What is NumPy?
    • Building and installing NumPy
    • How to find documentation
  • Numpy basics
    • Data types
    • Array creation
    • I/O with Numpy
    • Indexing
    • Broadcasting
    • Byte-swapping
    • Structured arrays (aka “Record arrays”)
    • Subclassing ndarray
  • Performance
  • Miscellaneous
    • IEEE 754 Floating Point Special Values
    • How numpy handles numerical exceptions
    • Examples
    • Interfacing to C
    • Interfacing to Fortran:
    • Interfacing to C++:
    • Methods vs. Functions
  • Using Numpy C-API
    • How to extend NumPy
    • Using Python as glue
    • Writing your own ufunc
    • Beyond the Basics


Introduction

  • NumPy User Guide
  • next
  • previous

Previous topic

NumPy User Guide

Next topic

What is NumPy?

Introduction

  • What is NumPy?
  • Building and installing NumPy
    • Binary installers
      • Windows
      • Linux
      • Mac OS X
    • Building from source
      • Prerequisites
      • FORTRAN ABI mismatch
        • Choosing the fortran compiler
        • How to check the ABI of blas/lapack/atlas
      • Disabling ATLAS and other accelerated libraries
      • Supplying additional compiler flags
      • Building with ATLAS support
        • Ubuntu 8.10 (Intrepid) and 9.04 (Jaunty)
        • Ubuntu 8.04 and lower
  • How to find documentation


What is NumPy?

  • NumPy User Guide
  • Introduction
  • index
  • next
  • previous

Previous topic

Introduction

Next topic

Building and installing NumPy

What is NumPy?

NumPy is the fundamental package for scientific computing in Python. It is a Python library that provides a multidimensional array object, various derived objects (such as masked arrays and matrices), and an assortment of routines for fast operations on arrays, including mathematical, logical, shape manipulation, sorting, selecting, I/O, discrete Fourier transforms, basic linear algebra, basic statistical operations, random simulation and much more.

At the core of the NumPy package, is the ndarray object. This encapsulates n-dimensional arrays of homogeneous data types, with many operations being performed in compiled code for performance. There are several important differences between NumPy arrays and the standard Python sequences:

  • NumPy arrays have a fixed size at creation, unlike Python lists (which can grow dynamically). Changing the size of an ndarray will create a new array and delete the original.
  • The elements in a NumPy array are all required to be of the same data type, and thus will be the same size in memory. The exception: one can have arrays of (Python, including NumPy) objects, thereby allowing for arrays of different sized elements.
  • NumPy arrays facilitate advanced mathematical and other types of operations on large numbers of data. Typically, such operations are executed more efficiently and with less code than is possible using Python’s built-in sequences.
  • A growing plethora of scientific and mathematical Python-based packages are using NumPy arrays; though these typically support Python-sequence input, they convert such input to NumPy arrays prior to processing, and they often output NumPy arrays. In other words, in order to efficiently use much (perhaps even most) of today’s scientific/mathematical Python-based software, just knowing how to use Python’s built-in sequence types is insufficient - one also needs to know how to use NumPy arrays.

The points about sequence size and speed are particularly important in scientific computing. As a simple example, consider the case of multiplying each element in a 1-D sequence with the corresponding element in another sequence of the same length. If the data are stored in two Python lists, a and b, we could iterate over each element:

c = []
for i in range(len(a)):
    c.append(a[i]*b[i])

This produces the correct answer, but if a and b each contain millions of numbers, we will pay the price for the inefficiencies of looping in Python. We could accomplish the same task much more quickly in C by writing (for clarity we neglect variable declarations and initializations, memory allocation, etc.)

for (i = 0; i < rows; i++): {
  c[i] = a[i]*b[i];
}

This saves all the overhead involved in interpreting the Python code and manipulating Python objects, but at the expense of the benefits gained from coding in Python. Furthermore, the coding work required increases with the dimensionality of our data. In the case of a 2-D array, for example, the C code (abridged as before) expands to

for (i = 0; i < rows; i++): {
  for (j = 0; j < columns; j++): {
    c[i][j] = a[i][j]*b[i][j];
  }
}

NumPy gives us the best of both worlds: element-by-element operations are the “default mode” when an ndarray is involved, but the element-by-element operation is speedily executed by pre-compiled C code. In NumPy

c = a * b

does what the earlier examples do, at near-C speeds, but with the code simplicity we expect from something based on Python. Indeed, the NumPy idiom is even simpler! This last example illustrates two of NumPy’s features which are the basis of much of its power: vectorization and broadcasting.

Vectorization describes the absence of any explicit looping, indexing, etc., in the code - these things are taking place, of course, just “behind the scenes” in optimized, pre-compiled C code. Vectorized code has many advantages, among which are:

  • vectorized code is more concise and easier to read
  • fewer lines of code generally means fewer bugs
  • the code more closely resembles standard mathematical notation (making it easier, typically, to correctly code mathematical constructs)
  • vectorization results in more “Pythonic” code. Without vectorization, our code would be littered with inefficient and difficult to read for loops.

Broadcasting is the term used to describe the implicit element-by-element behavior of operations; generally speaking, in NumPy all operations, not just arithmetic operations, but logical, bit-wise, functional, etc., behave in this implicit element-by-element fashion, i.e., they broadcast. Moreover, in the example above, a and b could be multidimensional arrays of the same shape, or a scalar and an array, or even two arrays of with different shapes, provided that the smaller array is “expandable” to the shape of the larger in such a way that the resulting broadcast is unambiguous. For detailed “rules” of broadcasting see numpy.doc.broadcasting.

NumPy fully supports an object-oriented approach, starting, once again, with ndarray. For example, ndarray is a class, possessing numerous methods and attributes. Many of its methods mirror functions in the outer-most NumPy namespace, giving the programmer complete freedom to code in whichever paradigm she prefers and/or which seems most appropriate to the task at hand.


Building and installing NumPy

  • NumPy User Guide
  • Introduction
  • index
  • next
  • previous

Table Of Contents

  • Building and installing NumPy
    • Binary installers
      • Windows
      • Linux
      • Mac OS X
    • Building from source
      • Prerequisites
      • FORTRAN ABI mismatch
        • Choosing the fortran compiler
        • How to check the ABI of blas/lapack/atlas
      • Disabling ATLAS and other accelerated libraries
      • Supplying additional compiler flags
      • Building with ATLAS support
        • Ubuntu 8.10 (Intrepid) and 9.04 (Jaunty)
        • Ubuntu 8.04 and lower

Previous topic

What is NumPy?

Next topic

How to find documentation

Building and installing NumPy

Binary installers

In most use cases the best way to install NumPy on your system is by using an installable binary package for your operating system.

Windows

Good solutions for Windows are, Enthought Canopy (which provides binary installers for Windows, OS X and Linux) and Python (x, y). Both of these packages include Python, NumPy and many additional packages.

A lightweight alternative is to download the Python installer from www.python.org and the NumPy installer for your Python version from the Sourceforge download site

The NumPy installer includes binaries for different CPU’s (without SSE instructions, with SSE2 or with SSE3) and installs the correct one automatically. If needed, this can be bypassed from the command line with

numpy-<1.y.z>-superpack-win32.exe /arch nosse

or ‘sse2’ or ‘sse3’ instead of ‘nosse’.

Linux

Most of the major distributions provide packages for NumPy, but these can lag behind the most recent NumPy release. Pre-built binary packages for Ubuntu are available on the scipy ppa. Redhat binaries are available in the Enthought Canopy.

Mac OS X

A universal binary installer for NumPy is available from the download site. The Enthought Canopy provides NumPy binaries.

Building from source

A general overview of building NumPy from source is given here, with detailed instructions for specific platforms given seperately.

Prerequisites

Building NumPy requires the following software installed:

  1. Python 2.6.x, 2.7.x, 3.2.x or newer

    On Debian and derivatives (Ubuntu): python, python-dev (or python3-dev)

    On Windows: the official python installer at www.python.org is enough

    Make sure that the Python package distutils is installed before continuing. For example, in Debian GNU/Linux, installing python-dev also installs distutils.

    Python must also be compiled with the zlib module enabled. This is practically always the case with pre-packaged Pythons.

  2. Compilers

    To build any extension modules for Python, you’ll need a C compiler. Various NumPy modules use FORTRAN 77 libraries, so you’ll also need a FORTRAN 77 compiler installed.

    Note that NumPy is developed mainly using GNU compilers. Compilers from other vendors such as Intel, Absoft, Sun, NAG, Compaq, Vast, Porland, Lahey, HP, IBM, Microsoft are only supported in the form of community feedback, and may not work out of the box. GCC 3.x (and later) compilers are recommended.

  3. Linear Algebra libraries

    NumPy does not require any external linear algebra libraries to be installed. However, if these are available, NumPy’s setup script can detect them and use them for building. A number of different LAPACK library setups can be used, including optimized LAPACK libraries such as ATLAS, MKL or the Accelerate/vecLib framework on OS X.

FORTRAN ABI mismatch

The two most popular open source fortran compilers are g77 and gfortran. Unfortunately, they are not ABI compatible, which means that concretely you should avoid mixing libraries built with one with another. In particular, if your blas/lapack/atlas is built with g77, you must use g77 when building numpy and scipy; on the contrary, if your atlas is built with gfortran, you must build numpy/scipy with gfortran. This applies for most other cases where different FORTRAN compilers might have been used.

Choosing the fortran compiler

To build with g77:

python setup.py build --fcompiler=gnu

To build with gfortran:

python setup.py build --fcompiler=gnu95

For more information see:

python setup.py build --help-fcompiler

How to check the ABI of blas/lapack/atlas

One relatively simple and reliable way to check for the compiler used to build a library is to use ldd on the library. If libg2c.so is a dependency, this means that g77 has been used. If libgfortran.so is a a dependency, gfortran has been used. If both are dependencies, this means both have been used, which is almost always a very bad idea.

Disabling ATLAS and other accelerated libraries

Usage of ATLAS and other accelerated libraries in Numpy can be disabled via:

BLAS=None LAPACK=None ATLAS=None python setup.py build

Supplying additional compiler flags

Additional compiler flags can be supplied by setting the OPT, FOPT (for Fortran), and CC environment variables.

Building with ATLAS support

Ubuntu 8.10 (Intrepid) and 9.04 (Jaunty)

You can install the necessary packages for optimized ATLAS with this command:

sudo apt-get install libatlas-base-dev

If you have a recent CPU with SIMD suppport (SSE, SSE2, etc...), you should also install the corresponding package for optimal performances. For example, for SSE2:

sudo apt-get install libatlas3gf-sse2

This package is not available on amd64 platforms.

NOTE: Ubuntu changed its default fortran compiler from g77 in Hardy to gfortran in Intrepid. If you are building ATLAS from source and are upgrading from Hardy to Intrepid or later versions, you should rebuild everything from scratch, including lapack.

Ubuntu 8.04 and lower

You can install the necessary packages for optimized ATLAS with this command:

sudo apt-get install atlas3-base-dev

If you have a recent CPU with SIMD suppport (SSE, SSE2, etc...), you should also install the corresponding package for optimal performances. For example, for SSE2:

sudo apt-get install atlas3-sse2


How to find documentation

  • NumPy User Guide
  • Introduction
  • index
  • next
  • previous

Previous topic

Building and installing NumPy

Next topic

Numpy basics

How to find documentation

See also

Numpy-specific help functions

How to find things in NumPy.


Numpy basics

  • NumPy User Guide
  • next
  • previous

Previous topic

How to find documentation

Next topic

Data types

Numpy basics

  • Data types
    • Array types and conversions between types
    • Array Scalars
  • Array creation
    • Introduction
    • Converting Python array_like Objects to Numpy Arrays
    • Intrinsic Numpy Array Creation
    • Reading Arrays From Disk
  • I/O with Numpy
    • Importing data with genfromtxt
  • Indexing
    • Assignment vs referencing
    • Single element indexing
    • Other indexing options
    • Index arrays
    • Indexing Multi-dimensional arrays
    • Boolean or “mask” index arrays
    • Combining index arrays with slices
    • Structural indexing tools
    • Assigning values to indexed arrays
    • Dealing with variable numbers of indices within programs
  • Broadcasting
    • General Broadcasting Rules
  • Byte-swapping
    • Introduction to byte ordering and ndarrays
    • Changing byte ordering
  • Structured arrays (aka “Record arrays”)
    • Structured Arrays (and Record Arrays)
  • Subclassing ndarray
    • Credits
    • Introduction
    • View casting
    • Creating new from template
    • Relationship of view casting and new-from-template
    • Implications for subclassing
    • Simple example - adding an extra attribute to ndarray
    • Slightly more realistic example - attribute added to existing array
    • __array_wrap__ for ufuncs
    • Extra gotchas - custom __del__ methods and ndarray.base


Data types

  • NumPy User Guide
  • Numpy basics
  • index
  • next
  • previous

Table Of Contents

  • Data types
    • Array types and conversions between types
    • Array Scalars

Previous topic

Numpy basics

Next topic

Array creation

Data types

See also

Data type objects

Array types and conversions between types

Numpy supports a much greater variety of numerical types than Python does. This section shows which are available, and how to modify an array’s data-type.

Data type | Description
bool_ | Boolean (True or False) stored as a byte
int_ | Default integer type (same as C long; normally either int64 or int32)
intc | Identical to C int (normally int32 or int64)
intp | Integer used for indexing (same as C ssize_t; normally either int32 or int64)
int8 | Byte (-128 to 127)
int16 | Integer (-32768 to 32767)
int32 | Integer (-2147483648 to 2147483647)
int64 | Integer (-9223372036854775808 to 9223372036854775807)
uint8 | Unsigned integer (0 to 255)
uint16 | Unsigned integer (0 to 65535)
uint32 | Unsigned integer (0 to 4294967295)
uint64 | Unsigned integer (0 to 18446744073709551615)
float_ | Shorthand for float64.
float16 | Half precision float: sign bit, 5 bits exponent, 10 bits mantissa
float32 | Single precision float: sign bit, 8 bits exponent, 23 bits mantissa
float64 | Double precision float: sign bit, 11 bits exponent, 52 bits mantissa
complex_ | Shorthand for complex128.
complex64 | Complex number, represented by two 32-bit floats (real and imaginary components)
complex128 | Complex number, represented by two 64-bit floats (real and imaginary components)

Additionally to intc the platform dependent C integer types short, long, longlong and their unsigned versions are defined.

Numpy numerical types are instances of dtype (data-type) objects, each having unique characteristics. Once you have imported NumPy using

>>> import numpy as np

the dtypes are available as np.bool_, np.float32, etc.

Advanced types, not listed in the table above, are explored in section Structured arrays (aka “Record arrays”).

There are 5 basic numerical types representing booleans (bool), integers (int), unsigned integers (uint) floating point (float) and complex. Those with numbers in their name indicate the bitsize of the type (i.e. how many bits are needed to represent a single value in memory). Some types, such as int and intp, have differing bitsizes, dependent on the platforms (e.g. 32-bit vs. 64-bit machines). This should be taken into account when interfacing with low-level code (such as C or Fortran) where the raw memory is addressed.

Data-types can be used as functions to convert python numbers to array scalars (see the array scalar section for an explanation), python sequences of numbers to arrays of that type, or as arguments to the dtype keyword that many numpy functions or methods accept. Some examples:

>>> import numpy as np
>>> x = np.float32(1.0)
>>> x
1.0
>>> y = np.int_([1,2,4])
>>> y
array([1, 2, 4])
>>> z = np.arange(3, dtype=np.uint8)
>>> z
array([0, 1, 2], dtype=uint8)

Array types can also be referred to by character codes, mostly to retain backward compatibility with older packages such as Numeric. Some documentation may still refer to these, for example:

>>> np.array([1, 2, 3], dtype='f')
array([ 1.,  2.,  3.], dtype=float32)

We recommend using dtype objects instead.

To convert the type of an array, use the .astype() method (preferred) or the type itself as a function. For example:

>>> z.astype(float)
array([  0.,  1.,  2.])
>>> np.int8(z)
array([0, 1, 2], dtype=int8)

Note that, above, we use the Python float object as a dtype. NumPy knows that int refers to np.int_, bool means np.bool_, that float is np.float_ and complex is np.complex_. The other data-types do not have Python equivalents.

To determine the type of an array, look at the dtype attribute:

>>> z.dtype
dtype('uint8')

dtype objects also contain information about the type, such as its bit-width and its byte-order. The data type can also be used indirectly to query properties of the type, such as whether it is an integer:

>>> d = np.dtype(int)
>>> d
dtype('int32')

>>> np.issubdtype(d, int)
True

>>> np.issubdtype(d, float)
False

Array Scalars

Numpy generally returns elements of arrays as array scalars (a scalar with an associated dtype). Array scalars differ from Python scalars, but for the most part they can be used interchangeably (the primary exception is for versions of Python older than v2.x, where integer array scalars cannot act as indices for lists and tuples). There are some exceptions, such as when code requires very specific attributes of a scalar or when it checks specifically whether a value is a Python scalar. Generally, problems are easily fixed by explicitly converting array scalars to Python scalars, using the corresponding Python type function (e.g., int, float, complex, str, unicode).

The primary advantage of using array scalars is that they preserve the array type (Python may not have a matching scalar type available, e.g. int16). Therefore, the use of array scalars ensures 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.


Array creation

  • NumPy User Guide
  • Numpy basics
  • index
  • next
  • previous

Table Of Contents

  • Array creation
    • Introduction
    • Converting Python array_like Objects to Numpy Arrays
    • Intrinsic Numpy Array Creation
    • Reading Arrays From Disk
      • Standard Binary Formats
      • Common ASCII Formats
      • Custom Binary Formats
      • Use of Special Libraries

Previous topic

Data types

Next topic

I/O with Numpy

Array creation

See also

Array creation routines

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.

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 example 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

Examples of formats that cannot be read directly but for which it is not hard to convert are those formats supported by 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. 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.

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 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).


I/O with Numpy

  • NumPy User Guide
  • Numpy basics
  • index
  • next
  • previous

Previous topic

Array creation

Next topic

Importing data with genfromtxt

I/O with Numpy

  • Importing data with genfromtxt
    • Defining the input
    • Splitting the lines into columns
    • Skipping lines and choosing columns
    • Choosing the data type
    • Setting the names
    • Tweaking the conversion
    • Shortcut functions


Importing data with genfromtxt

  • NumPy User Guide
  • Numpy basics
  • I/O with Numpy
  • index
  • next
  • previous

Table Of Contents

  • Importing data with genfromtxt
    • Defining the input
    • Splitting the lines into columns
      • The delimiter argument
      • The autostrip argument
      • The comments argument
    • Skipping lines and choosing columns
      • The skip_header and skip_footer arguments
      • The usecols argument
    • Choosing the data type
    • Setting the names
      • The names argument
      • The defaultfmt argument
      • Validating names
    • Tweaking the conversion
      • The converters argument
      • Using missing and filling values
      • missing_values
      • filling_values
      • usemask
    • Shortcut functions

Previous topic

I/O with Numpy

Next topic

Indexing

Importing data with genfromtxt

Numpy provides several functions to create arrays from tabular data. We focus here on the genfromtxt function.

In a nutshell, genfromtxt runs two main loops. The first loop converts each line of the file in a sequence of strings. The second loop converts each string to the appropriate data type. This mechanism is slower than a single loop, but gives more flexibility. In particular, genfromtxt is able to take missing data into account, when other faster and simpler functions like loadtxt cannot.

Note

When giving examples, we will use the following conventions:

>>> import numpy as np
>>> from StringIO import StringIO

Defining the input

The only mandatory argument of genfromtxt is the source of the data. It can be a string corresponding to the name of a local or remote file, or a file-like object with a read method (such as an actual file or a StringIO.StringIO object). If the argument is the URL of a remote file, this latter is automatically downloaded in the current directory.

The input file can be a text file or an archive. Currently, the function recognizes gzip and bz2 (bzip2) archives. The type of the archive is determined by examining the extension of the file: if the filename ends with '.gz', a gzip archive is expected; if it ends with 'bz2', a bzip2 archive is assumed.

Splitting the lines into columns

The delimiter argument

Once the file is defined and open for reading, genfromtxt splits each non-empty line into a sequence of strings. Empty or commented lines are just skipped. The delimiter keyword is used to define how the splitting should take place.

Quite often, a single character marks the separation between columns. For example, comma-separated files (CSV) use a comma (,) or a semicolon (;) as delimiter:

>>> data = "1, 2, 3\n4, 5, 6"
>>> np.genfromtxt(StringIO(data), delimiter=",")
array([[ 1.,  2.,  3.],
       [ 4.,  5.,  6.]])

Another common separator is "\t", the tabulation character. However, we are not limited to a single character, any string will do. By default, genfromtxt assumes delimiter=None, meaning that the line is split along white spaces (including tabs) and that consecutive white spaces are considered as a single white space.

Alternatively, we may be dealing with a fixed-width file, where columns are defined as a given number of characters. In that case, we need to set delimiter to a single integer (if all the columns have the same size) or to a sequence of integers (if columns can have different sizes):

>>> data = "  1  2  3\n  4  5 67\n890123  4"
>>> np.genfromtxt(StringIO(data), delimiter=3)
array([[   1.,    2.,    3.],
       [   4.,    5.,   67.],
       [ 890.,  123.,    4.]])
>>> data = "123456789\n   4  7 9\n   4567 9"
>>> np.genfromtxt(StringIO(data), delimiter=(4, 3, 2))
array([[ 1234.,   567.,    89.],
       [    4.,     7.,     9.],
       [    4.,   567.,     9.]])

The autostrip argument

By default, when a line is decomposed into a series of strings, the individual entries are not stripped of leading nor trailing white spaces. This behavior can be overwritten by setting the optional argument autostrip to a value of True:

>>> data = "1, abc , 2\n 3, xxx, 4"
>>> # Without autostrip
>>> np.genfromtxt(StringIO(data), dtype="|S5")
array([['1', ' abc ', ' 2'],
       ['3', ' xxx', ' 4']],
      dtype='|S5')
>>> # With autostrip
>>> np.genfromtxt(StringIO(data), dtype="|S5", autostrip=True)
array([['1', 'abc', '2'],
       ['3', 'xxx', '4']],
      dtype='|S5')

The comments argument

The optional argument comments is used to define a character string that marks the beginning of a comment. By default, genfromtxt assumes comments='#'. The comment marker may occur anywhere on the line. Any character present after the comment marker(s) is simply ignored:

>>> data = """#
... # Skip me !
... # Skip me too !
... 1, 2
... 3, 4
... 5, 6 #This is the third line of the data
... 7, 8
... # And here comes the last line
... 9, 0
... """
>>> np.genfromtxt(StringIO(data), comments="#", delimiter=",")
[[ 1.  2.]
 [ 3.  4.]
 [ 5.  6.]
 [ 7.  8.]
 [ 9.  0.]]

Note

There is one notable exception to this behavior: if the optional argument names=True, the first commented line will be examined for names.

Skipping lines and choosing columns

The skip_header and skip_footer arguments

The presence of a header in the file can hinder data processing. In that case, we need to use the skip_header optional argument. The values of this argument must be an integer which corresponds to the number of lines to skip at the beginning of the file, before any other action is performed. Similarly, we can skip the last n lines of the file by using the skip_footer attribute and giving it a value of n:

>>> data = "\n".join(str(i) for i in range(10))
>>> np.genfromtxt(StringIO(data),)
array([ 0.,  1.,  2.,  3.,  4.,  5.,  6.,  7.,  8.,  9.])
>>> np.genfromtxt(StringIO(data),
...               skip_header=3, skip_footer=5)
array([ 3.,  4.])

By default, skip_header=0 and skip_footer=0, meaning that no lines are skipped.

The usecols argument

In some cases, we are not interested in all the columns of the data but only a few of them. We can select which columns to import with the usecols argument. This argument accepts a single integer or a sequence of integers corresponding to the indices of the columns to import. Remember that by convention, the first column has an index of 0. Negative integers behave the same as regular Python negative indexes.

For example, if we want to import only the first and the last columns, we can use usecols=(0, -1):

>>> data = "1 2 3\n4 5 6"
>>> np.genfromtxt(StringIO(data), usecols=(0, -1))
array([[ 1.,  3.],
       [ 4.,  6.]])

If the columns have names, we can also select which columns to import by giving their name to the usecols argument, either as a sequence of strings or a comma-separated string:

>>> data = "1 2 3\n4 5 6"
>>> np.genfromtxt(StringIO(data),
...               names="a, b, c", usecols=("a", "c"))
array([(1.0, 3.0), (4.0, 6.0)],
      dtype=[('a', '<f8'), ('c', '<f8')])
>>> np.genfromtxt(StringIO(data),
...               names="a, b, c", usecols=("a, c"))
    array([(1.0, 3.0), (4.0, 6.0)],
          dtype=[('a', '<f8'), ('c', '<f8')])

Choosing the data type

The main way to control how the sequences of strings we have read from the file are converted to other types is to set the dtype argument. Acceptable values for this argument are:

  • a single type, such as dtype=float. The output will be 2D with the given dtype, unless a name has been associated with each column with the use of the names argument (see below). Note that dtype=float is the default for genfromtxt.
  • a sequence of types, such as dtype=(int, float, float).
  • a comma-separated string, such as dtype="i4,f8,|S3".
  • a dictionary with two keys 'names' and 'formats'.
  • a sequence of tuples (name, type), such as dtype=[('A', int), ('B', float)].
  • an existing numpy.dtype object.
  • the special value None. In that case, the type of the columns will be determined from the data itself (see below).

In all the cases but the first one, the output will be a 1D array with a structured dtype. This dtype has as many fields as items in the sequence. The field names are defined with the names keyword.

When dtype=None, the type of each column is determined iteratively from its data. We start by checking whether a string can be converted to a boolean (that is, if the string matches true or false in lower cases); then whether it can be converted to an integer, then to a float, then to a complex and eventually to a string. This behavior may be changed by modifying the default mapper of the StringConverter class.

The option dtype=None is provided for convenience. However, it is significantly slower than setting the dtype explicitly.

Setting the names

The names argument

A natural approach when dealing with tabular data is to allocate a name to each column. A first possibility is to use an explicit structured dtype, as mentioned previously:

>>> data = StringIO("1 2 3\n 4 5 6")
>>> np.genfromtxt(data, dtype=[(_, int) for _ in "abc"])
array([(1, 2, 3), (4, 5, 6)],
      dtype=[('a', '<i8'), ('b', '<i8'), ('c', '<i8')])

Another simpler possibility is to use the names keyword with a sequence of strings or a comma-separated string:

>>> data = StringIO("1 2 3\n 4 5 6")
>>> np.genfromtxt(data, names="A, B, C")
array([(1.0, 2.0, 3.0), (4.0, 5.0, 6.0)],
      dtype=[('A', '<f8'), ('B', '<f8'), ('C', '<f8')])

In the example above, we used the fact that by default, dtype=float. By giving a sequence of names, we are forcing the output to a structured dtype.

We may sometimes need to define the column names from the data itself. In that case, we must use the names keyword with a value of True. The names will then be read from the first line (after the skip_header ones), even if the line is commented out:

>>> data = StringIO("So it goes\n#a b c\n1 2 3\n 4 5 6")
>>> np.genfromtxt(data, skip_header=1, names=True)
array([(1.0, 2.0, 3.0), (4.0, 5.0, 6.0)],
      dtype=[('a', '<f8'), ('b', '<f8'), ('c', '<f8')])

The default value of names is None. If we give any other value to the keyword, the new names will overwrite the field names we may have defined with the dtype:

>>> data = StringIO("1 2 3\n 4 5 6")
>>> ndtype=[('a',int), ('b', float), ('c', int)]
>>> names = ["A", "B", "C"]
>>> np.genfromtxt(data, names=names, dtype=ndtype)
array([(1, 2.0, 3), (4, 5.0, 6)],
      dtype=[('A', '<i8'), ('B', '<f8'), ('C', '<i8')])

The defaultfmt argument

If names=None but a structured dtype is expected, names are defined with the standard NumPy default of "f%i", yielding names like f0, f1 and so forth:

>>> data = StringIO("1 2 3\n 4 5 6")
>>> np.genfromtxt(data, dtype=(int, float, int))
array([(1, 2.0, 3), (4, 5.0, 6)],
      dtype=[('f0', '<i8'), ('f1', '<f8'), ('f2', '<i8')])

In the same way, if we don’t give enough names to match the length of the dtype, the missing names will be defined with this default template:

>>> data = StringIO("1 2 3\n 4 5 6")
>>> np.genfromtxt(data, dtype=(int, float, int), names="a")
array([(1, 2.0, 3), (4, 5.0, 6)],
      dtype=[('a', '<i8'), ('f0', '<f8'), ('f1', '<i8')])

We can overwrite this default with the defaultfmt argument, that takes any format string:

>>> data = StringIO("1 2 3\n 4 5 6")
>>> np.genfromtxt(data, dtype=(int, float, int), defaultfmt="var_%02i")
array([(1, 2.0, 3), (4, 5.0, 6)],
      dtype=[('var_00', '<i8'), ('var_01', '<f8'), ('var_02', '<i8')])

Note

We need to keep in mind that defaultfmt is used only if some names are expected but not defined.

Validating names

Numpy arrays with a structured dtype can also be viewed as recarray, where a field can be accessed as if it were an attribute. For that reason, we may need to make sure that the field name doesn’t contain any space or invalid character, or that it does not correspond to the name of a standard attribute (like size or shape), which would confuse the interpreter. genfromtxt accepts three optional arguments that provide a finer control on the names:

deletechars
Gives a string combining all the characters that must be deleted from the name. By default, invalid characters are ~!@#$%^&*()-=+~\|]}[{';: /?.>,<.
excludelist
Gives a list of the names to exclude, such as return, file, print... If one of the input name is part of this list, an underscore character ('_') will be appended to it.
case_sensitive
Whether the names should be case-sensitive (case_sensitive=True), converted to upper case (case_sensitive=False or case_sensitive='upper') or to lower case (case_sensitive='lower').

Tweaking the conversion

The converters argument

Usually, defining a dtype is sufficient to define how the sequence of strings must be converted. However, some additional control may sometimes be required. For example, we may want to make sure that a date in a format YYYY/MM/DD is converted to a datetime object, or that a string like xx% is properly converted to a float between 0 and 1. In such cases, we should define conversion functions with the converters arguments.

The value of this argument is typically a dictionary with column indices or column names as keys and a conversion functions as values. These conversion functions can either be actual functions or lambda functions. In any case, they should accept only a string as input and output only a single element of the wanted type.

In the following example, the second column is converted from as string representing a percentage to a float between 0 and 1:

>>> convertfunc = lambda x: float(x.strip("%"))/100.
>>> data = "1, 2.3%, 45.\n6, 78.9%, 0"
>>> names = ("i", "p", "n")
>>> # General case .....
>>> np.genfromtxt(StringIO(data), delimiter=",", names=names)
array([(1.0, nan, 45.0), (6.0, nan, 0.0)],
      dtype=[('i', '<f8'), ('p', '<f8'), ('n', '<f8')])

We need to keep in mind that by default, dtype=float. A float is therefore expected for the second column. However, the strings ' 2.3%' and ' 78.9%' cannot be converted to float and we end up having np.nan instead. Let’s now use a converter:

>>> # Converted case ...
>>> np.genfromtxt(StringIO(data), delimiter=",", names=names,
...               converters={1: convertfunc})
array([(1.0, 0.023, 45.0), (6.0, 0.78900000000000003, 0.0)],
      dtype=[('i', '<f8'), ('p', '<f8'), ('n', '<f8')])

The same results can be obtained by using the name of the second column ("p") as key instead of its index (1):

>>> # Using a name for the converter ...
>>> np.genfromtxt(StringIO(data), delimiter=",", names=names,
...               converters={"p": convertfunc})
array([(1.0, 0.023, 45.0), (6.0, 0.78900000000000003, 0.0)],
      dtype=[('i', '<f8'), ('p', '<f8'), ('n', '<f8')])

Converters can also be used to provide a default for missing entries. In the following example, the converter convert transforms a stripped string into the corresponding float or into -999 if the string is empty. We need to explicitly strip the string from white spaces as it is not done by default:

>>> data = "1, , 3\n 4, 5, 6"
>>> convert = lambda x: float(x.strip() or -999)
>>> np.genfromtxt(StringIO(data), delimiter=",",
...               converter={1: convert})
array([[   1., -999.,    3.],
       [   4.,    5.,    6.]])

Using missing and filling values

Some entries may be missing in the dataset we are trying to import. In a previous example, we used a converter to transform an empty string into a float. However, user-defined converters may rapidly become cumbersome to manage.

The genfromtxt function provides two other complementary mechanisms: the missing_values argument is used to recognize missing data and a second argument, filling_values, is used to process these missing data.

missing_values

By default, any empty string is marked as missing. We can also consider more complex strings, such as "N/A" or "???" to represent missing or invalid data. The missing_values argument accepts three kind of values:

a string or a comma-separated string
This string will be used as the marker for missing data for all the columns
a sequence of strings
In that case, each item is associated to a column, in order.
a dictionary
Values of the dictionary are strings or sequence of strings. The corresponding keys can be column indices (integers) or column names (strings). In addition, the special key None can be used to define a default applicable to all columns.

filling_values

We know how to recognize missing data, but we still need to provide a value for these missing entries. By default, this value is determined from the expected dtype according to this table:

Expected type | Default
bool | False
int | -1
float | np.nan
complex | np.nan+0j
string | '???'

We can get a finer control on the conversion of missing values with the filling_values optional argument. Like missing_values, this argument accepts different kind of values:

a single value
This will be the default for all columns
a sequence of values
Each entry will be the default for the corresponding column
a dictionary
Each key can be a column index or a column name, and the corresponding value should be a single object. We can use the special key None to define a default for all columns.

In the following example, we suppose that the missing values are flagged with "N/A" in the first column and by "???" in the third column. We wish to transform these missing values to 0 if they occur in the first and second column, and to -999 if they occur in the last column:

>>> data = "N/A, 2, 3\n4, ,???"
>>> kwargs = dict(delimiter=",",
...               dtype=int,
...               names="a,b,c",
...               missing_values={0:"N/A", 'b':" ", 2:"???"},
...               filling_values={0:0, 'b':0, 2:-999})
>>> np.genfromtxt(StringIO.StringIO(data), **kwargs)
array([(0, 2, 3), (4, 0, -999)],
      dtype=[('a', '<i8'), ('b', '<i8'), ('c', '<i8')])

usemask

We may also want to keep track of the occurrence of missing data by constructing a boolean mask, with True entries where data was missing and False otherwise. To do that, we just have to set the optional argument usemask to True (the default is False). The output array will then be a MaskedArray.

Shortcut functions

In addition to genfromtxt, the numpy.lib.io module provides several convenience functions derived from genfromtxt. These functions work the same way as the original, but they have different default values.

ndfromtxt
Always set usemask=False. The output is always a standard numpy.ndarray.
mafromtxt
Always set usemask=True. The output is always a MaskedArray
recfromtxt
Returns a standard numpy.recarray (if usemask=False) or a MaskedRecords array (if usemaske=True). The default dtype is dtype=None, meaning that the types of each column will be automatically determined.
recfromcsv
Like recfromtxt, but with a default delimiter=",".


Indexing

  • NumPy User Guide
  • Numpy basics
  • index
  • next
  • previous

Table Of Contents

  • Indexing
    • Assignment vs referencing
    • Single element indexing
    • Other indexing options
    • Index arrays
    • Indexing Multi-dimensional arrays
    • Boolean or “mask” index arrays
    • Combining index arrays with slices
    • Structural indexing tools
    • Assigning values to indexed arrays
    • Dealing with variable numbers of indices within programs

Previous topic

Importing data with genfromtxt

Next topic

Broadcasting

Indexing

See also

Indexing routines

Array indexing refers to any use of the square brackets ([]) to index array values. There are many options to indexing, which give numpy indexing great power, but with power comes some complexity and the potential for confusion. This section is just an overview of the various options and issues related to indexing. Aside from single element indexing, the details on most of these options are to be found in related sections.

Assignment vs referencing

Most of the following examples show the use of indexing when referencing data in an array. The examples work just as well when assigning to an array. See the section at the end for specific examples and explanations on how assignments work.

Single element indexing

Single element indexing for a 1-D array is what one expects. It work exactly like that for other standard Python sequences. It is 0-based, and accepts negative indices for indexing from the end of the array.

>>> x = np.arange(10)
>>> x[2]
2
>>> x[-2]
8

Unlike lists and tuples, numpy arrays support multidimensional indexing for multidimensional arrays. That means that it is not necessary to separate each dimension’s index into its own set of square brackets.

>>> x.shape = (2,5) # now x is 2-dimensional
>>> x[1,3]
8
>>> x[1,-1]
9

Note that if one indexes a multidimensional array with fewer indices than dimensions, one gets a subdimensional array. For example:

>>> x[0]
array([0, 1, 2, 3, 4])

That is, each index specified selects the array corresponding to the rest of the dimensions selected. In the above example, choosing 0 means that remaining dimension of lenth 5 is being left unspecified, and that what is returned is an array of that dimensionality and size. It must be noted that the returned array is not a copy of the original, but points to the same values in memory as does the original array. In this case, the 1-D array at the first position (0) is returned. So using a single index on the returned array, results in a single element being returned. That is:

>>> x[0][2]
2

So note that x[0,2] = x[0][2] though the second case is more inefficient a new temporary array is created after the first index that is subsequently indexed by 2.

Note to those used to IDL or Fortran memory order as it relates to indexing. Numpy uses C-order indexing. That means that the last index usually represents the most rapidly changing memory location, unlike Fortran or IDL, where the first index represents the most rapidly changing location in memory. This difference represents a great potential for confusion.

Other indexing options

It is possible to slice and stride arrays to extract arrays of the same number of dimensions, but of different sizes than the original. The slicing and striding works exactly the same way it does for lists and tuples except that they can be applied to multiple dimensions as well. A few examples illustrates best:

>>> x = np.arange(10)
>>> x[2:5]
array([2, 3, 4])
>>> x[:-7]
array([0, 1, 2])
>>> x[1:7:2]
array([1, 3, 5])
>>> y = np.arange(35).reshape(5,7)
>>> y[1:5:2,::3]
array([[ 7, 10, 13],
       [21, 24, 27]])

Note that slices of arrays do not copy the internal array data but also produce new views of the original data.

It is possible to index arrays with other arrays for the purposes of selecting lists of values out of arrays into new arrays. There are two different ways of accomplishing this. One uses one or more arrays of index values. The other involves giving a boolean array of the proper shape to indicate the values to be selected. Index arrays are a very powerful tool that allow one to avoid looping over individual elements in arrays and thus greatly improve performance.

It is possible to use special features to effectively increase the number of dimensions in an array through indexing so the resulting array aquires the shape needed for use in an expression or with a specific function.

Index arrays

Numpy arrays may be indexed with other arrays (or any other sequence- like object that can be converted to an array, such as lists, with the exception of tuples; see the end of this document for why this is). The use of index arrays ranges from simple, straightforward cases to complex, hard-to-understand cases. For all cases of index arrays, what is returned is a copy of the original data, not a view as one gets for slices.

Index arrays must be of integer type. Each value in the array indicates which value in the array to use in place of the index. To illustrate:

>>> x = np.arange(10,1,-1)
>>> x
array([10,  9,  8,  7,  6,  5,  4,  3,  2])
>>> x[np.array([3, 3, 1, 8])]
array([7, 7, 9, 2])

The index array consisting of the values 3, 3, 1 and 8 correspondingly create an array of length 4 (same as the index array) where each index is replaced by the value the index array has in the array being indexed.

Negative values are permitted and work as they do with single indices or slices:

>>> x[np.array([3,3,-3,8])]
array([7, 7, 4, 2])

It is an error to have index values out of bounds:

>>> x[np.array([3, 3, 20, 8])]
<type 'exceptions.IndexError'>: index 20 out of bounds 0<=index<9

Generally speaking, what is returned when index arrays are used is an array with the same shape as the index array, but with the type and values of the array being indexed. As an example, we can use a multidimensional index array instead:

>>> x[np.array([[1,1],[2,3]])]
array([[9, 9],
       [8, 7]])

Indexing Multi-dimensional arrays

Things become more complex when multidimensional arrays are indexed, particularly with multidimensional index arrays. These tend to be more unusal uses, but theyare permitted, and they are useful for some problems. We’ll start with thesimplest multidimensional case (using the array y from the previous examples):

>>> y[np.array([0,2,4]), np.array([0,1,2])]
array([ 0, 15, 30])

In this case, if the index arrays have a matching shape, and there is an index array for each dimension of the array being indexed, the resultant array has the same shape as the index arrays, and the values correspond to the index set for each position in the index arrays. In this example, the first index value is 0 for both index arrays, and thus the first value of the resultant array is y[0,0]. The next value is y[2,1], and the last is y[4,2].

If the index arrays do not have the same shape, there is an attempt to broadcast them to the same shape. If they cannot be broadcast to the same shape, an exception is raised:

>>> y[np.array([0,2,4]), np.array([0,1])]
<type 'exceptions.ValueError'>: shape mismatch: objects cannot be
broadcast to a single shape

The broadcasting mechanism permits index arrays to be combined with scalars for other indices. The effect is that the scalar value is used for all the corresponding values of the index arrays:

>>> y[np.array([0,2,4]), 1]
array([ 1, 15, 29])

Jumping to the next level of complexity, it is possible to only partially index an array with index arrays. It takes a bit of thought to understand what happens in such cases. For example if we just use one index array with y:

>>> y[np.array([0,2,4])]
array([[ 0,  1,  2,  3,  4,  5,  6],
       [14, 15, 16, 17, 18, 19, 20],
       [28, 29, 30, 31, 32, 33, 34]])

What results is the construction of a new array where each value of the index array selects one row from the array being indexed and the resultant array has the resulting shape (size of row, number index elements).

An example of where this may be useful is for a color lookup table where we want to map the values of an image into RGB triples for display. The lookup table could have a shape (nlookup, 3). Indexing such an array with an image with shape (ny, nx) with dtype=np.uint8 (or any integer type so long as values are with the bounds of the lookup table) will result in an array of shape (ny, nx, 3) where a triple of RGB values is associated with each pixel location.

In general, the shape of the resulant array will be the concatenation of the shape of the index array (or the shape that all the index arrays were broadcast to) with the shape of any unused dimensions (those not indexed) in the array being indexed.

Boolean or “mask” index arrays

Boolean arrays used as indices are treated in a different manner entirely than index arrays. Boolean arrays must be of the same shape as the initial dimensions of the array being indexed. In the most straightforward case, the boolean array has the same shape:

>>> b = y>20
>>> y[b]
array([21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34])

The result is a 1-D array containing all the elements in the indexed array corresponding to all the true elements in the boolean array. As with index arrays, what is returned is a copy of the data, not a view as one gets with slices.

The result will be multidimensional if y has more dimensions than b. For example:

>>> b[:,5] # use a 1-D boolean whose first dim agrees with the first dim of y
array([False, False, False,  True,  True], dtype=bool)
>>> y[b[:,5]]
array([[21, 22, 23, 24, 25, 26, 27],
       [28, 29, 30, 31, 32, 33, 34]])

Here the 4th and 5th rows are selected from the indexed array and combined to make a 2-D array.

In general, when the boolean array has fewer dimensions than the array being indexed, this is equivalent to y[b, ...], which means y is indexed by b followed by as many : as are needed to fill out the rank of y. Thus the shape of the result is one dimension containing the number of True elements of the boolean array, followed by the remaining dimensions of the array being indexed.

For example, using a 2-D boolean array of shape (2,3) with four True elements to select rows from a 3-D array of shape (2,3,5) results in a 2-D result of shape (4,5):

>>> x = np.arange(30).reshape(2,3,5)
>>> x
array([[[ 0,  1,  2,  3,  4],
        [ 5,  6,  7,  8,  9],
        [10, 11, 12, 13, 14]],
       [[15, 16, 17, 18, 19],
        [20, 21, 22, 23, 24],
        [25, 26, 27, 28, 29]]])
>>> b = np.array([[True, True, False], [False, True, True]])
>>> x[b]
array([[ 0,  1,  2,  3,  4],
       [ 5,  6,  7,  8,  9],
       [20, 21, 22, 23, 24],
       [25, 26, 27, 28, 29]])

For further details, consult the numpy reference documentation on array indexing.

Combining index arrays with slices

Index arrays may be combined with slices. For example:

>>> y[np.array([0,2,4]),1:3]
array([[ 1,  2],
       [15, 16],
       [29, 30]])

In effect, the slice is converted to an index array np.array([[1,2]]) (shape (1,2)) that is broadcast with the index array to produce a resultant array of shape (3,2).

Likewise, slicing can be combined with broadcasted boolean indices:

>>> y[b[:,5],1:3]
array([[22, 23],
       [29, 30]])

Structural indexing tools

To facilitate easy matching of array shapes with expressions and in assignments, the np.newaxis object can be used within array indices to add new dimensions with a size of 1. For example:

>>> y.shape
(5, 7)
>>> y[:,np.newaxis,:].shape
(5, 1, 7)

Note that there are no new elements in the array, just that the dimensionality is increased. This can be handy to combine two arrays in a way that otherwise would require explicitly reshaping operations. For example:

>>> x = np.arange(5)
>>> x[:,np.newaxis] + x[np.newaxis,:]
array([[0, 1, 2, 3, 4],
       [1, 2, 3, 4, 5],
       [2, 3, 4, 5, 6],
       [3, 4, 5, 6, 7],
       [4, 5, 6, 7, 8]])

The ellipsis syntax maybe used to indicate selecting in full any remaining unspecified dimensions. For example:

>>> z = np.arange(81).reshape(3,3,3,3)
>>> z[1,...,2]
array([[29, 32, 35],
       [38, 41, 44],
       [47, 50, 53]])

This is equivalent to:

>>> z[1,:,:,2]
array([[29, 32, 35],
       [38, 41, 44],
       [47, 50, 53]])

Assigning values to indexed arrays

As mentioned, one can select a subset of an array to assign to using a single index, slices, and index and mask arrays. The value being assigned to the indexed array must be shape consistent (the same shape or broadcastable to the shape the index produces). For example, it is permitted to assign a constant to a slice:

>>> x = np.arange(10)
>>> x[2:7] = 1

or an array of the right size:

>>> x[2:7] = np.arange(5)

Note that assignments may result in changes if assigning higher types to lower types (like floats to ints) or even exceptions (assigning complex to floats or ints):

>>> x[1] = 1.2
>>> x[1]
1
>>> x[1] = 1.2j
<type 'exceptions.TypeError'>: can't convert complex to long; use
long(abs(z))

Unlike some of the references (such as array and mask indices) assignments are always made to the original data in the array (indeed, nothing else would make sense!). Note though, that some actions may not work as one may naively expect. This particular example is often surprising to people:

>>> x = np.arange(0, 50, 10)
>>> x
array([ 0, 10, 20, 30, 40])
>>> x[np.array([1, 1, 3, 1])] += 1
>>> x
array([ 0, 11, 20, 31, 40])

Where people expect that the 1st location will be incremented by 3. In fact, it will only be incremented by 1. The reason is because a new array is extracted from the original (as a temporary) containing the values at 1, 1, 3, 1, then the value 1 is added to the temporary, and then the temporary is assigned back to the original array. Thus the value of the array at x[1]+1 is assigned to x[1] three times, rather than being incremented 3 times.

Dealing with variable numbers of indices within programs

The index syntax is very powerful but limiting when dealing with a variable number of indices. For example, if you want to write a function that can handle arguments with various numbers of dimensions without having to write special case code for each number of possible dimensions, how can that be done? If one supplies to the index a tuple, the tuple will be interpreted as a list of indices. For example (using the previous definition for the array z):

>>> indices = (1,1,1,1)
>>> z[indices]
40

So one can use code to construct tuples of any number of indices and then use these within an index.

Slices can be specified within programs by using the slice() function in Python. For example:

>>> indices = (1,1,1,slice(0,2)) # same as [1,1,1,0:2]
>>> z[indices]
array([39, 40])

Likewise, ellipsis can be specified by code by using the Ellipsis object:

>>> indices = (1, Ellipsis, 1) # same as [1,...,1]
>>> z[indices]
array([[28, 31, 34],
       [37, 40, 43],
       [46, 49, 52]])

For this reason it is possible to use the output from the np.where() function directly as an index since it always returns a tuple of index arrays.

Because the special treatment of tuples, they are not automatically converted to an array as a list would be. As an example:

>>> z[[1,1,1,1]] # produces a large array
array([[[[27, 28, 29],
         [30, 31, 32], ...
>>> z[(1,1,1,1)] # returns a single value
40


Broadcasting

  • NumPy User Guide
  • Numpy basics
  • index
  • next
  • previous

Table Of Contents

  • Broadcasting
    • General Broadcasting Rules

Previous topic

Indexing

Next topic

Byte-swapping

Broadcasting

See also

numpy.broadcast

The term broadcasting describes how numpy treats arrays with different shapes during arithmetic operations. Subject to certain constraints, the smaller array is “broadcast” across the larger array so that they have compatible shapes. Broadcasting provides a means of vectorizing array operations so that looping occurs in C instead of Python. It does this without making needless copies of data and usually leads to efficient algorithm implementations. There are, however, cases where broadcasting is a bad idea because it leads to inefficient use of memory that slows computation.

NumPy operations are usually done on pairs of arrays on an element-by-element basis. In the simplest case, the two arrays must have exactly the same shape, as in the following example:

>>> a = np.array([1.0, 2.0, 3.0])
>>> b = np.array([2.0, 2.0, 2.0])
>>> a * b
array([ 2.,  4.,  6.])

NumPy’s broadcasting rule relaxes this constraint when the arrays’ shapes meet certain constraints. The simplest broadcasting example occurs when an array and a scalar value are combined in an operation:

>>> a = np.array([1.0, 2.0, 3.0])
>>> b = 2.0
>>> a * b
array([ 2.,  4.,  6.])

The result is equivalent to the previous example where b was an array. We can think of the scalar b being stretched during the arithmetic operation into an array with the same shape as a. The new elements in b are simply copies of the original scalar. The stretching analogy is only conceptual. NumPy is smart enough to use the original scalar value without actually making copies, so that broadcasting operations are as memory and computationally efficient as possible.

The code in the second example is more efficient than that in the first because broadcasting moves less memory around during the multiplication (b is a scalar rather than an array).

General Broadcasting Rules

When operating on two arrays, NumPy compares their shapes element-wise. It starts with the trailing dimensions, and works its way forward. Two dimensions are compatible when

  1. they are equal, or
  2. one of them is 1

If these conditions are not met, a ValueError: frames are not aligned exception is thrown, indicating that the arrays have incompatible shapes. The size of the resulting array is the maximum size along each dimension of the input arrays.

Arrays do not need to have the same number of dimensions. For example, if you have a 256x256x3 array of RGB values, and you want to scale each color in the image by a different value, you can multiply the image by a one-dimensional array with 3 values. Lining up the sizes of the trailing axes of these arrays according to the broadcast rules, shows that they are compatible:

Image  (3d array): 256 x 256 x 3
Scale  (1d array):             3
Result (3d array): 256 x 256 x 3

When either of the dimensions compared is one, the other is used. In other words, dimensions with size 1 are stretched or “copied” to match the other.

In the following example, both the A and B arrays have axes with length one that are expanded to a larger size during the broadcast operation:

A      (4d array):  8 x 1 x 6 x 1
B      (3d array):      7 x 1 x 5
Result (4d array):  8 x 7 x 6 x 5

Here are some more examples:

A      (2d array):  5 x 4
B      (1d array):      1
Result (2d array):  5 x 4

A      (2d array):  5 x 4
B      (1d array):      4
Result (2d array):  5 x 4

A      (3d array):  15 x 3 x 5
B      (3d array):  15 x 1 x 5
Result (3d array):  15 x 3 x 5

A      (3d array):  15 x 3 x 5
B      (2d array):       3 x 5
Result (3d array):  15 x 3 x 5

A      (3d array):  15 x 3 x 5
B      (2d array):       3 x 1
Result (3d array):  15 x 3 x 5

Here are examples of shapes that do not broadcast:

A      (1d array):  3
B      (1d array):  4 # trailing dimensions do not match

A      (2d array):      2 x 1
B      (3d array):  8 x 4 x 3 # second from last dimensions mismatched

An example of broadcasting in practice:

>>> x = np.arange(4)
>>> xx = x.reshape(4,1)
>>> y = np.ones(5)
>>> z = np.ones((3,4))

>>> x.shape
(4,)

>>> y.shape
(5,)

>>> x + y
<type 'exceptions.ValueError'>: shape mismatch: objects cannot be broadcast to a single shape

>>> xx.shape
(4, 1)

>>> y.shape
(5,)

>>> (xx + y).shape
(4, 5)

>>> xx + y
array([[ 1.,  1.,  1.,  1.,  1.],
       [ 2.,  2.,  2.,  2.,  2.],
       [ 3.,  3.,  3.,  3.,  3.],
       [ 4.,  4.,  4.,  4.,  4.]])

>>> x.shape
(4,)

>>> z.shape
(3, 4)

>>> (x + z).shape
(3, 4)

>>> x + z
array([[ 1.,  2.,  3.,  4.],
       [ 1.,  2.,  3.,  4.],
       [ 1.,  2.,  3.,  4.]])

Broadcasting provides a convenient way of taking the outer product (or any other outer operation) of two arrays. The following example shows an outer addition operation of two 1-d arrays:

>>> a = np.array([0.0, 10.0, 20.0, 30.0])
>>> b = np.array([1.0, 2.0, 3.0])
>>> a[:, np.newaxis] + b
array([[  1.,   2.,   3.],
       [ 11.,  12.,  13.],
       [ 21.,  22.,  23.],
       [ 31.,  32.,  33.]])

Here the newaxis index operator inserts a new axis into a, making it a two-dimensional 4x1 array. Combining the 4x1 array with b, which has shape (3,), yields a 4x3 array.

See this article for illustrations of broadcasting concepts.


Byte-swapping

  • NumPy User Guide
  • Numpy basics
  • index
  • next
  • previous

Table Of Contents

  • Byte-swapping
    • Introduction to byte ordering and ndarrays
    • Changing byte ordering
      • Data and dtype endianness don’t match, change dtype to match data
      • Data and type endianness don’t match, change data to match dtype
      • Data and dtype endianness match, swap data and dtype

Previous topic

Broadcasting

Next topic

Structured arrays (aka “Record arrays”)

Byte-swapping

Introduction to byte ordering and ndarrays

The ndarray is an object that provide a python array interface to data in memory.

It often happens that the memory that you want to view with an array is not of the same byte ordering as the computer on which you are running Python.

For example, I might be working on a computer with a little-endian CPU - such as an Intel Pentium, but I have loaded some data from a file written by a computer that is big-endian. Let’s say I have loaded 4 bytes from a file written by a Sun (big-endian) computer. I know that these 4 bytes represent two 16-bit integers. On a big-endian machine, a two-byte integer is stored with the Most Significant Byte (MSB) first, and then the Least Significant Byte (LSB). Thus the bytes are, in memory order:

  1. MSB integer 1
  2. LSB integer 1
  3. MSB integer 2
  4. LSB integer 2

Let’s say the two integers were in fact 1 and 770. Because 770 = 256 * 3 + 2, the 4 bytes in memory would contain respectively: 0, 1, 3, 2. The bytes I have loaded from the file would have these contents:

>>> big_end_str = chr(0) + chr(1) + chr(3) + chr(2)
>>> big_end_str
'\x00\x01\x03\x02'

We might want to use an ndarray to access these integers. In that case, we can create an array around this memory, and tell numpy that there are two integers, and that they are 16 bit and big-endian:

>>> import numpy as np
>>> big_end_arr = np.ndarray(shape=(2,),dtype='>i2', buffer=big_end_str)
>>> big_end_arr[0]
1
>>> big_end_arr[1]
770

Note the array dtype above of >i2. The > means ‘big-endian’ (< is little-endian) and i2 means ‘signed 2-byte integer’. For example, if our data represented a single unsigned 4-byte little-endian integer, the dtype string would be <u4.

In fact, why don’t we try that?

>>> little_end_u4 = np.ndarray(shape=(1,),dtype='<u4', buffer=big_end_str)
>>> little_end_u4[0] == 1 * 256**1 + 3 * 256**2 + 2 * 256**3
True

Returning to our big_end_arr - in this case our underlying data is big-endian (data endianness) and we’ve set the dtype to match (the dtype is also big-endian). However, sometimes you need to flip these around.

Changing byte ordering

As you can imagine from the introduction, there are two ways you can affect the relationship between the byte ordering of the array and the underlying memory it is looking at:

  • Change the byte-ordering information in the array dtype so that it interprets the undelying data as being in a different byte order. This is the role of arr.newbyteorder()
  • Change the byte-ordering of the underlying data, leaving the dtype interpretation as it was. This is what arr.byteswap() does.

The common situations in which you need to change byte ordering are:

  1. Your data and dtype endianess don’t match, and you want to change the dtype so that it matches the data.
  2. Your data and dtype endianess don’t match, and you want to swap the data so that they match the dtype
  3. Your data and dtype endianess match, but you want the data swapped and the dtype to reflect this

Data and dtype endianness don’t match, change dtype to match data

We make something where they don’t match:

>>> wrong_end_dtype_arr = np.ndarray(shape=(2,),dtype='<i2', buffer=big_end_str)
>>> wrong_end_dtype_arr[0]
256

The obvious fix for this situation is to change the dtype so it gives the correct endianness:

>>> fixed_end_dtype_arr = wrong_end_dtype_arr.newbyteorder()
>>> fixed_end_dtype_arr[0]
1

Note the the array has not changed in memory:

>>> fixed_end_dtype_arr.tobytes() == big_end_str
True

Data and type endianness don’t match, change data to match dtype

You might want to do this if you need the data in memory to be a certain ordering. For example you might be writing the memory out to a file that needs a certain byte ordering.

>>> fixed_end_mem_arr = wrong_end_dtype_arr.byteswap()
>>> fixed_end_mem_arr[0]
1

Now the array has changed in memory:

>>> fixed_end_mem_arr.tobytes() == big_end_str
False

Data and dtype endianness match, swap data and dtype

You may have a correctly specified array dtype, but you need the array to have the opposite byte order in memory, and you want the dtype to match so the array values make sense. In this case you just do both of the previous operations:

>>> swapped_end_arr = big_end_arr.byteswap().newbyteorder()
>>> swapped_end_arr[0]
1
>>> swapped_end_arr.tobytes() == big_end_str
False

An easier way of casting the data to a specific dtype and byte ordering can be achieved with the ndarray astype method:

>>> swapped_end_arr = big_end_arr.astype('<i2')
>>> swapped_end_arr[0]
1
>>> swapped_end_arr.tobytes() == big_end_str
False


Structured arrays (aka “Record arrays”)

  • NumPy User Guide
  • Numpy basics
  • index
  • next
  • previous

Table Of Contents

  • Structured arrays (aka “Record arrays”)
    • Structured Arrays (and Record Arrays)
      • Introduction
      • Defining Structured Arrays
      • Accessing and modifying field names
      • Accessing field titles
      • Accessing multiple fields at once
      • Filling structured arrays
      • More information

Previous topic

Byte-swapping

Next topic

Subclassing ndarray

Structured arrays (aka “Record arrays”)

Structured Arrays (and Record Arrays)

Introduction

Numpy provides powerful capabilities to create arrays of structs or records. These arrays permit one to manipulate the data by the structs or by fields of the struct. A simple example will show what is meant.:

>>> x = np.zeros((2,),dtype=('i4,f4,a10'))
>>> x[:] = [(1,2.,'Hello'),(2,3.,"World")]
>>> x
array([(1, 2.0, 'Hello'), (2, 3.0, 'World')],
     dtype=[('f0', '>i4'), ('f1', '>f4'), ('f2', '|S10')])

Here we have created a one-dimensional array of length 2. Each element of this array is a record that contains three items, a 32-bit integer, a 32-bit float, and a string of length 10 or less. If we index this array at the second position we get the second record:

>>> x[1]
(2,3.,"World")

Conveniently, one can access any field of the array by indexing using the string that names that field. In this case the fields have received the default names ‘f0’, ‘f1’ and ‘f2’.

>>> y = x['f1']
>>> y
array([ 2.,  3.], dtype=float32)
>>> y[:] = 2*y
>>> y
array([ 4.,  6.], dtype=float32)
>>> x
array([(1, 4.0, 'Hello'), (2, 6.0, 'World')],
      dtype=[('f0', '>i4'), ('f1', '>f4'), ('f2', '|S10')])

In these examples, y is a simple float array consisting of the 2nd field in the record. But, rather than being a copy of the data in the structured array, it is a view, i.e., it shares exactly the same memory locations. Thus, when we updated this array by doubling its values, the structured array shows the corresponding values as doubled as well. Likewise, if one changes the record, the field view also changes:

>>> x[1] = (-1,-1.,"Master")
>>> x
array([(1, 4.0, 'Hello'), (-1, -1.0, 'Master')],
      dtype=[('f0', '>i4'), ('f1', '>f4'), ('f2', '|S10')])
>>> y
array([ 4., -1.], dtype=float32)

Defining Structured Arrays

One defines a structured array through the dtype object. There are several alternative ways to define the fields of a record. Some of these variants provide backward compatibility with Numeric, numarray, or another module, and should not be used except for such purposes. These will be so noted. One specifies record structure in one of four alternative ways, using an argument (as supplied to a dtype function keyword or a dtype object constructor itself). This argument must be one of the following: 1) string, 2) tuple, 3) list, or 4) dictionary. Each of these is briefly described below.

1) String argument (as used in the above examples). In this case, the constructor expects a comma-separated list of type specifiers, optionally with extra shape information. The type specifiers can take 4 different forms:

a) b1, i1, i2, i4, i8, u1, u2, u4, u8, f2, f4, f8, c8, c16, a<n>
   (representing bytes, ints, unsigned ints, floats, complex and
    fixed length strings of specified byte lengths)
b) int8,...,uint8,...,float16, float32, float64, complex64, complex128
   (this time with bit sizes)
c) older Numeric/numarray type specifications (e.g. Float32).
   Don't use these in new code!
d) Single character type specifiers (e.g H for unsigned short ints).
   Avoid using these unless you must. Details can be found in the
   Numpy book

These different styles can be mixed within the same string (but why would you want to do that?). Furthermore, each type specifier can be prefixed with a repetition number, or a shape. In these cases an array element is created, i.e., an array within a record. That array is still referred to as a single field. An example:

>>> x = np.zeros(3, dtype='3int8, float32, (2,3)float64')
>>> x
array([([0, 0, 0], 0.0, [[0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]),
       ([0, 0, 0], 0.0, [[0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]),
       ([0, 0, 0], 0.0, [[0.0, 0.0, 0.0], [0.0, 0.0, 0.0]])],
      dtype=[('f0', '|i1', 3), ('f1', '>f4'), ('f2', '>f8', (2, 3))])

By using strings to define the record structure, it precludes being able to name the fields in the original definition. The names can be changed as shown later, however.

2) Tuple argument: The only relevant tuple case that applies to record structures is when a structure is mapped to an existing data type. This is done by pairing in a tuple, the existing data type with a matching dtype definition (using any of the variants being described here). As an example (using a definition using a list, so see 3) for further details):

>>> x = np.zeros(3, dtype=('i4',[('r','u1'), ('g','u1'), ('b','u1'), ('a','u1')]))
>>> x
array([0, 0, 0])
>>> x['r']
array([0, 0, 0], dtype=uint8)

In this case, an array is produced that looks and acts like a simple int32 array, but also has definitions for fields that use only one byte of the int32 (a bit like Fortran equivalencing).

3) List argument: In this case the record structure is defined with a list of tuples. Each tuple has 2 or 3 elements specifying: 1) The name of the field (‘’ is permitted), 2) the type of the field, and 3) the shape (optional). For example:

>>> x = np.zeros(3, dtype=[('x','f4'),('y',np.float32),('value','f4',(2,2))])
>>> x
array([(0.0, 0.0, [[0.0, 0.0], [0.0, 0.0]]),
       (0.0, 0.0, [[0.0, 0.0], [0.0, 0.0]]),
       (0.0, 0.0, [[0.0, 0.0], [0.0, 0.0]])],
      dtype=[('x', '>f4'), ('y', '>f4'), ('value', '>f4', (2, 2))])

4) Dictionary argument: two different forms are permitted. The first consists of a dictionary with two required keys (‘names’ and ‘formats’), each having an equal sized list of values. The format list contains any type/shape specifier allowed in other contexts. The names must be strings. There are two optional keys: ‘offsets’ and ‘titles’. Each must be a correspondingly matching list to the required two where offsets contain integer offsets for each field, and titles are objects containing metadata for each field (these do not have to be strings), where the value of None is permitted. As an example:

>>> x = np.zeros(3, dtype={'names':['col1', 'col2'], 'formats':['i4','f4']})
>>> x
array([(0, 0.0), (0, 0.0), (0, 0.0)],
      dtype=[('col1', '>i4'), ('col2', '>f4')])

The other dictionary form permitted is a dictionary of name keys with tuple values specifying type, offset, and an optional title.

>>> x = np.zeros(3, dtype={'col1':('i1',0,'title 1'), 'col2':('f4',1,'title 2')})
>>> x
array([(0, 0.0), (0, 0.0), (0, 0.0)],
      dtype=[(('title 1', 'col1'), '|i1'), (('title 2', 'col2'), '>f4')])

Accessing and modifying field names

The field names are an attribute of the dtype object defining the record structure. For the last example:

>>> x.dtype.names
('col1', 'col2')
>>> x.dtype.names = ('x', 'y')
>>> x
array([(0, 0.0), (0, 0.0), (0, 0.0)],
     dtype=[(('title 1', 'x'), '|i1'), (('title 2', 'y'), '>f4')])
>>> x.dtype.names = ('x', 'y', 'z') # wrong number of names
<type 'exceptions.ValueError'>: must replace all names at once with a sequence of length 2

Accessing field titles

The field titles provide a standard place to put associated info for fields. They do not have to be strings.

>>> x.dtype.fields['x'][2]
'title 1'

Accessing multiple fields at once

You can access multiple fields at once using a list of field names:

>>> x = np.array([(1.5,2.5,(1.0,2.0)),(3.,4.,(4.,5.)),(1.,3.,(2.,6.))],
        dtype=[('x','f4'),('y',np.float32),('value','f4',(2,2))])

Notice that x is created with a list of tuples.

>>> x[['x','y']]
array([(1.5, 2.5), (3.0, 4.0), (1.0, 3.0)],
     dtype=[('x', '<f4'), ('y', '<f4')])
>>> x[['x','value']]
array([(1.5, [[1.0, 2.0], [1.0, 2.0]]), (3.0, [[4.0, 5.0], [4.0, 5.0]]),
      (1.0, [[2.0, 6.0], [2.0, 6.0]])],
     dtype=[('x', '<f4'), ('value', '<f4', (2, 2))])

The fields are returned in the order they are asked for.:

>>> x[['y','x']]
array([(2.5, 1.5), (4.0, 3.0), (3.0, 1.0)],
     dtype=[('y', '<f4'), ('x', '<f4')])

Filling structured arrays

Structured arrays can be filled by field or row by row.

>>> arr = np.zeros((5,), dtype=[('var1','f8'),('var2','f8')])
>>> arr['var1'] = np.arange(5)

If you fill it in row by row, it takes a take a tuple (but not a list or array!):

>>> arr[0] = (10,20)
>>> arr
array([(10.0, 20.0), (1.0, 0.0), (2.0, 0.0), (3.0, 0.0), (4.0, 0.0)],
     dtype=[('var1', '<f8'), ('var2', '<f8')])

More information

You can find some more information on recarrays and structured arrays (including the difference between the two) here.


Subclassing ndarray

  • NumPy User Guide
  • Numpy basics
  • index
  • next
  • previous

Table Of Contents

  • Subclassing ndarray
    • Credits
    • Introduction
      • ndarrays and object creation
    • View casting
    • Creating new from template
    • Relationship of view casting and new-from-template
    • Implications for subclassing
      • A brief Python primer on __new__ and __init__
      • The role of __array_finalize__
    • Simple example - adding an extra attribute to ndarray
    • Slightly more realistic example - attribute added to existing array
    • __array_wrap__ for ufuncs
    • Extra gotchas - custom __del__ methods and ndarray.base

Previous topic

Structured arrays (aka “Record arrays”)

Next topic

Performance

Subclassing ndarray

Credits

This page is based with thanks on the wiki page on subclassing by Pierre Gerard-Marchant - http://www.scipy.org/Subclasses.

Introduction

Subclassing ndarray is relatively simple, but it has some complications compared to other Python objects. On this page we explain the machinery that allows you to subclass ndarray, and the implications for implementing a subclass.

ndarrays and object creation

Subclassing ndarray is complicated by the fact that new instances of ndarray classes can come about in three different ways. These are:

  1. Explicit constructor call - as in MySubClass(params). This is the usual route to Python instance creation.
  2. View casting - casting an existing ndarray as a given subclass
  3. New from template - creating a new instance from a template instance. Examples include returning slices from a subclassed array, creating return types from ufuncs, and copying arrays. See Creating new from template for more details

The last two are characteristics of ndarrays - in order to support things like array slicing. The complications of subclassing ndarray are due to the mechanisms numpy has to support these latter two routes of instance creation.

View casting

View casting is the standard ndarray mechanism by which you take an ndarray of any subclass, and return a view of the array as another (specified) subclass:

>>> import numpy as np
>>> # create a completely useless ndarray subclass
>>> class C(np.ndarray): pass
>>> # create a standard ndarray
>>> arr = np.zeros((3,))
>>> # take a view of it, as our useless subclass
>>> c_arr = arr.view(C)
>>> type(c_arr)
<class 'C'>

Creating new from template

New instances of an ndarray subclass can also come about by a very similar mechanism to View casting, when numpy finds it needs to create a new instance from a template instance. The most obvious place this has to happen is when you are taking slices of subclassed arrays. For example:

>>> v = c_arr[1:]
>>> type(v) # the view is of type 'C'
<class 'C'>
>>> v is c_arr # but it's a new instance
False

The slice is a view onto the original c_arr data. So, when we take a view from the ndarray, we return a new ndarray, of the same class, that points to the data in the original.

There are other points in the use of ndarrays where we need such views, such as copying arrays (c_arr.copy()), creating ufunc output arrays (see also __array_wrap__ for ufuncs), and reducing methods (like c_arr.mean().

Relationship of view casting and new-from-template

These paths both use the same machinery. We make the distinction here, because they result in different input to your methods. Specifically, View casting means you have created a new instance of your array type from any potential subclass of ndarray. Creating new from template means you have created a new instance of your class from a pre-existing instance, allowing you - for example - to copy across attributes that are particular to your subclass.

Implications for subclassing

If we subclass ndarray, we need to deal not only with explicit construction of our array type, but also View casting or Creating new from template. Numpy has the machinery to do this, and this machinery that makes subclassing slightly non-standard.

There are two aspects to the machinery that ndarray uses to support views and new-from-template in subclasses.

The first is the use of the ndarray.__new__ method for the main work of object initialization, rather then the more usual __init__ method. The second is the use of the __array_finalize__ method to allow subclasses to clean up after the creation of views and new instances from templates.

A brief Python primer on __new__ and __init__

__new__ is a standard Python method, and, if present, is called before __init__ when we create a class instance. See the python __new__ documentation for more detail.

For example, consider the following Python code:

class C(object):
    def __new__(cls, *args):
        print 'Cls in __new__:', cls
        print 'Args in __new__:', args
        return object.__new__(cls, *args)

    def __init__(self, *args):
        print 'type(self) in __init__:', type(self)
        print 'Args in __init__:', args

meaning that we get:

>>> c = C('hello')
Cls in __new__: <class 'C'>
Args in __new__: ('hello',)
type(self) in __init__: <class 'C'>
Args in __init__: ('hello',)

When we call C('hello'), the __new__ method gets its own class as first argument, and the passed argument, which is the string 'hello'. After python calls __new__, it usually (see below) calls our __init__ method, with the output of __new__ as the first argument (now a class instance), and the passed arguments following.

As you can see, the object can be initialized in the __new__ method or the __init__ method, or both, and in fact ndarray does not have an __init__ method, because all the initialization is done in the __new__ method.

Why use __new__ rather than just the usual __init__? Because in some cases, as for ndarray, we want to be able to return an object of some other class. Consider the following:

class D(C):
    def __new__(cls, *args):
        print 'D cls is:', cls
        print 'D args in __new__:', args
        return C.__new__(C, *args)

    def __init__(self, *args):
        # we never get here
        print 'In D __init__'

meaning that:

>>> obj = D('hello')
D cls is: <class 'D'>
D args in __new__: ('hello',)
Cls in __new__: <class 'C'>
Args in __new__: ('hello',)
>>> type(obj)
<class 'C'>

The definition of C is the same as before, but for D, the __new__ method returns an instance of class C rather than D. Note that the __init__ method of D does not get called. In general, when the __new__ method returns an object of class other than the class in which it is defined, the __init__ method of that class is not called.

This is how subclasses of the ndarray class are able to return views that preserve the class type. When taking a view, the standard ndarray machinery creates the new ndarray object with something like:

obj = ndarray.__new__(subtype, shape, ...

where subdtype is the subclass. Thus the returned view is of the same class as the subclass, rather than being of class ndarray.

That solves the problem of returning views of the same type, but now we have a new problem. The machinery of ndarray can set the class this way, in its standard methods for taking views, but the ndarray __new__ method knows nothing of what we have done in our own __new__ method in order to set attributes, and so on. (Aside - why not call obj = subdtype.__new__(... then? Because we may not have a __new__ method with the same call signature).

The role of __array_finalize__

__array_finalize__ is the mechanism that numpy provides to allow subclasses to handle the various ways that new instances get created.

Remember that subclass instances can come about in these three ways:

  1. explicit constructor call (obj = MySubClass(params)). This will call the usual sequence of MySubClass.__new__ then (if it exists) MySubClass.__init__.
  2. View casting
  3. Creating new from template

Our MySubClass.__new__ method only gets called in the case of the explicit constructor call, so we can’t rely on MySubClass.__new__ or MySubClass.__init__ to deal with the view casting and new-from-template. It turns out that MySubClass.__array_finalize__ does get called for all three methods of object creation, so this is where our object creation housekeeping usually goes.

  • For the explicit constructor call, our subclass will need to create a new ndarray instance of its own class. In practice this means that we, the authors of the code, will need to make a call to ndarray.__new__(MySubClass,...), or do view casting of an existing array (see below)
  • For view casting and new-from-template, the equivalent of ndarray.__new__(MySubClass,... is called, at the C level.

The arguments that __array_finalize__ recieves differ for the three methods of instance creation above.

The following code allows us to look at the call sequences and arguments:

import numpy as np

class C(np.ndarray):
    def __new__(cls, *args, **kwargs):
        print 'In __new__ with class %s' % cls
        return np.ndarray.__new__(cls, *args, **kwargs)

    def __init__(self, *args, **kwargs):
        # in practice you probably will not need or want an __init__
        # method for your subclass
        print 'In __init__ with class %s' % self.__class__

    def __array_finalize__(self, obj):
        print 'In array_finalize:'
        print '   self type is %s' % type(self)
        print '   obj type is %s' % type(obj)

Now:

>>> # Explicit constructor
>>> c = C((10,))
In __new__ with class <class 'C'>
In array_finalize:
   self type is <class 'C'>
   obj type is <type 'NoneType'>
In __init__ with class <class 'C'>
>>> # View casting
>>> a = np.arange(10)
>>> cast_a = a.view(C)
In array_finalize:
   self type is <class 'C'>
   obj type is <type 'numpy.ndarray'>
>>> # Slicing (example of new-from-template)
>>> cv = c[:1]
In array_finalize:
   self type is <class 'C'>
   obj type is <class 'C'>

The signature of __array_finalize__ is:

def __array_finalize__(self, obj):

ndarray.__new__ passes __array_finalize__ the new object, of our own class (self) as well as the object from which the view has been taken (obj). As you can see from the output above, the self is always a newly created instance of our subclass, and the type of obj differs for the three instance creation methods:

  • When called from the explicit constructor, obj is None
  • When called from view casting, obj can be an instance of any subclass of ndarray, including our own.
  • When called in new-from-template, obj is another instance of our own subclass, that we might use to update the new self instance.

Because __array_finalize__ is the only method that always sees new instances being created, it is the sensible place to fill in instance defaults for new object attributes, among other tasks.

This may be clearer with an example.

Simple example - adding an extra attribute to ndarray

import numpy as np

class InfoArray(np.ndarray):

    def __new__(subtype, shape, dtype=float, buffer=None, offset=0,
          strides=None, order=None, info=None):
        # Create the ndarray instance of our type, given the usual
        # ndarray input arguments.  This will call the standard
        # ndarray constructor, but return an object of our type.
        # It also triggers a call to InfoArray.__array_finalize__
        obj = np.ndarray.__new__(subtype, shape, dtype, buffer, offset, strides,
                         order)
        # set the new 'info' attribute to the value passed
        obj.info = info
        # Finally, we must return the newly created object:
        return obj

    def __array_finalize__(self, obj):
        # ``self`` is a new object resulting from
        # ndarray.__new__(InfoArray, ...), therefore it only has
        # attributes that the ndarray.__new__ constructor gave it -
        # i.e. those of a standard ndarray.
        #
        # We could have got to the ndarray.__new__ call in 3 ways:
        # From an explicit constructor - e.g. InfoArray():
        #    obj is None
        #    (we're in the middle of the InfoArray.__new__
        #    constructor, and self.info will be set when we return to
        #    InfoArray.__new__)
        if obj is None: return
        # From view casting - e.g arr.view(InfoArray):
        #    obj is arr
        #    (type(obj) can be InfoArray)
        # From new-from-template - e.g infoarr[:3]
        #    type(obj) is InfoArray
        #
        # Note that it is here, rather than in the __new__ method,
        # that we set the default value for 'info', because this
        # method sees all creation of default objects - with the
        # InfoArray.__new__ constructor, but also with
        # arr.view(InfoArray).
        self.info = getattr(obj, 'info', None)
        # We do not need to return anything

Using the object looks like this:

>>> obj = InfoArray(shape=(3,)) # explicit constructor
>>> type(obj)
<class 'InfoArray'>
>>> obj.info is None
True
>>> obj = InfoArray(shape=(3,), info='information')
>>> obj.info
'information'
>>> v = obj[1:] # new-from-template - here - slicing
>>> type(v)
<class 'InfoArray'>
>>> v.info
'information'
>>> arr = np.arange(10)
>>> cast_arr = arr.view(InfoArray) # view casting
>>> type(cast_arr)
<class 'InfoArray'>
>>> cast_arr.info is None
True

This class isn’t very useful, because it has the same constructor as the bare ndarray object, including passing in buffers and shapes and so on. We would probably prefer the constructor to be able to take an already formed ndarray from the usual numpy calls to np.array and return an object.

Slightly more realistic example - attribute added to existing array

Here is a class that takes a standard ndarray that already exists, casts as our type, and adds an extra attribute.

import numpy as np

class RealisticInfoArray(np.ndarray):

    def __new__(cls, input_array, info=None):
        # Input array is an already formed ndarray instance
        # We first cast to be our class type
        obj = np.asarray(input_array).view(cls)
        # add the new attribute to the created instance
        obj.info = info
        # Finally, we must return the newly created object:
        return obj

    def __array_finalize__(self, obj):
        # see InfoArray.__array_finalize__ for comments
        if obj is None: return
        self.info = getattr(obj, 'info', None)

So:

>>> arr = np.arange(5)
>>> obj = RealisticInfoArray(arr, info='information')
>>> type(obj)
<class 'RealisticInfoArray'>
>>> obj.info
'information'
>>> v = obj[1:]
>>> type(v)
<class 'RealisticInfoArray'>
>>> v.info
'information'

__array_wrap__ for ufuncs

__array_wrap__ gets called at the end of numpy ufuncs and other numpy functions, to allow a subclass to set the type of the return value and update attributes and metadata. Let’s show how this works with an example. First we make the same subclass as above, but with a different name and some print statements:

import numpy as np

class MySubClass(np.ndarray):

    def __new__(cls, input_array, info=None):
        obj = np.asarray(input_array).view(cls)
        obj.info = info
        return obj

    def __array_finalize__(self, obj):
        print 'In __array_finalize__:'
        print '   self is %s' % repr(self)
        print '   obj is %s' % repr(obj)
        if obj is None: return
        self.info = getattr(obj, 'info', None)

    def __array_wrap__(self, out_arr, context=None):
        print 'In __array_wrap__:'
        print '   self is %s' % repr(self)
        print '   arr is %s' % repr(out_arr)
        # then just call the parent
        return np.ndarray.__array_wrap__(self, out_arr, context)

We run a ufunc on an instance of our new array:

>>> obj = MySubClass(np.arange(5), info='spam')
In __array_finalize__:
   self is MySubClass([0, 1, 2, 3, 4])
   obj is array([0, 1, 2, 3, 4])
>>> arr2 = np.arange(5)+1
>>> ret = np.add(arr2, obj)
In __array_wrap__:
   self is MySubClass([0, 1, 2, 3, 4])
   arr is array([1, 3, 5, 7, 9])
In __array_finalize__:
   self is MySubClass([1, 3, 5, 7, 9])
   obj is MySubClass([0, 1, 2, 3, 4])
>>> ret
MySubClass([1, 3, 5, 7, 9])
>>> ret.info
'spam'

Note that the ufunc (np.add) has called the __array_wrap__ method of the input with the highest __array_priority__ value, in this case MySubClass.__array_wrap__, with arguments self as obj, and out_arr as the (ndarray) result of the addition. In turn, the default __array_wrap__ (ndarray.__array_wrap__) has cast the result to class MySubClass, and called __array_finalize__ - hence the copying of the info attribute. This has all happened at the C level.

But, we could do anything we wanted:

class SillySubClass(np.ndarray):

    def __array_wrap__(self, arr, context=None):
        return 'I lost your data'

>>> arr1 = np.arange(5)
>>> obj = arr1.view(SillySubClass)
>>> arr2 = np.arange(5)
>>> ret = np.multiply(obj, arr2)
>>> ret
'I lost your data'

So, by defining a specific __array_wrap__ method for our subclass, we can tweak the output from ufuncs. The __array_wrap__ method requires self, then an argument - which is the result of the ufunc - and an optional parameter context. This parameter is returned by some ufuncs as a 3-element tuple: (name of the ufunc, argument of the ufunc, domain of the ufunc). __array_wrap__ should return an instance of its containing class. See the masked array subclass for an implementation.

In addition to __array_wrap__, which is called on the way out of the ufunc, there is also an __array_prepare__ method which is called on the way into the ufunc, after the output arrays are created but before any computation has been performed. The default implementation does nothing but pass through the array. __array_prepare__ should not attempt to access the array data or resize the array, it is intended for setting the output array type, updating attributes and metadata, and performing any checks based on the input that may be desired before computation begins. Like __array_wrap__, __array_prepare__ must return an ndarray or subclass thereof or raise an error.

Extra gotchas - custom __del__ methods and ndarray.base

One of the problems that ndarray solves is keeping track of memory ownership of ndarrays and their views. Consider the case where we have created an ndarray, arr and have taken a slice with v = arr[1:]. The two objects are looking at the same memory. Numpy keeps track of where the data came from for a particular array or view, with the base attribute:

>>> # A normal ndarray, that owns its own data
>>> arr = np.zeros((4,))
>>> # In this case, base is None
>>> arr.base is None
True
>>> # We take a view
>>> v1 = arr[1:]
>>> # base now points to the array that it derived from
>>> v1.base is arr
True
>>> # Take a view of a view
>>> v2 = v1[1:]
>>> # base points to the view it derived from
>>> v2.base is v1
True

In general, if the array owns its own memory, as for arr in this case, then arr.base will be None - there are some exceptions to this - see the numpy book for more details.

The base attribute is useful in being able to tell whether we have a view or the original array. This in turn can be useful if we need to know whether or not to do some specific cleanup when the subclassed array is deleted. For example, we may only want to do the cleanup if the original array is deleted, but not the views. For an example of how this can work, have a look at the memmap class in numpy.core.


Performance

  • NumPy User Guide
  • next
  • previous

Previous topic

Subclassing ndarray

Next topic

Miscellaneous

Performance

Placeholder for Improving Performance documentation.


Miscellaneous

  • NumPy User Guide
  • next
  • previous

Table Of Contents

  • Miscellaneous
    • IEEE 754 Floating Point Special Values
    • How numpy handles numerical exceptions
    • Examples
    • Interfacing to C
    • Interfacing to Fortran:
    • Interfacing to C++:
    • Methods vs. Functions

Previous topic

Performance

Next topic

Using Numpy C-API

Miscellaneous

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.:

>>> myarr = np.array([1., 0., np.nan, 3.])
>>> np.where(myarr == np.nan)
>>> np.nan == np.nan  # is always False! Use special numpy functions instead.
False
>>> 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

The default is to 'warn' for invalid, divide, and overflow and 'ignore' for underflow. But this can be changed, and it can be set individually for different kinds of exceptions. The different behaviors are:

  • ‘ignore’ : Take no action when the exception occurs.
  • ‘warn’ : Print a RuntimeWarning (via the Python warnings module).
  • ‘raise’ : Raise a FloatingPointError.
  • ‘call’ : Call a function specified using the seterrcall function.
  • ‘print’ : Print a warning directly to stdout.
  • ‘log’ : Record error in a Log object specified by 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-thread 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)
<function err_handler at 0x...>
>>> 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 of 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. Cython
  • Plusses:
    • avoid learning C API’s
    • no dealing with reference counting
    • can code in pseudo python and generate C code
    • can also interface to existing C code
    • should shield you from changes to Python C api
    • has become the de-facto standard within the scientific Python community
    • fast indexing support for arrays
  • Minuses:
    • Can write code in non-standard form which may become obsolete
    • Not as flexible as manual wrapping
  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. scipy.weave
  • Plusses:
    • 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 very uncertain: it’s the only part of Scipy not ported to Python 3 and is effectively deprecated in favor of Cython.
  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:

The clear choice to wrap Fortran code is f2py.

Pyfort is an older alternative, but not supported any longer. Fwrap is a newer project that looked promising but isn’t being developed any longer.

Interfacing to C++:

  1. Cython
  2. CXX
  3. Boost.python
  4. SWIG
  5. SIP (used mainly in PyQT)

Methods vs. Functions

Placeholder for Methods vs. Functions documentation.


Using Numpy C-API

  • NumPy User Guide
  • next
  • previous

Previous topic

Miscellaneous

Next topic

How to extend NumPy

Using Numpy C-API

  • How to extend NumPy
    • Writing an extension module
    • Required subroutine
    • Defining functions
      • Functions without keyword arguments
      • Functions with keyword arguments
      • Reference counting
    • Dealing with array objects
      • Converting an arbitrary sequence object
      • Creating a brand-new ndarray
      • Getting at ndarray memory and accessing elements of the ndarray
    • Example
  • Using Python as glue
    • Calling other compiled libraries from Python
    • Hand-generated wrappers
    • f2py
      • Creating source for a basic extension module
      • Creating a compiled extension module
      • Improving the basic interface
      • Inserting directives in Fortran source
      • A filtering example
      • Calling f2py from Python
      • Automatic extension module generation
      • Conclusion
    • Cython
      • Complex addition in Cython
      • Image filter in Cython
      • Conclusion
    • ctypes
      • Having a shared library
      • Loading the shared library
      • Converting arguments
      • Calling the function
      • Complete example
      • Conclusion
    • Additional tools you may find useful
      • SWIG
      • SIP
      • Boost Python
      • PyFort
  • Writing your own ufunc
    • Creating a new universal function
    • Example Non-ufunc extension
    • Example Numpy ufunc for one dtype
    • Example Numpy ufunc with multiple dtypes
    • Example Numpy ufunc with multiple arguments/return values
    • Example Numpy ufunc with structured array dtype arguments
    • PyUFunc_FromFuncAndData Specification
  • Beyond the Basics
    • Iterating over elements in the array
      • Basic Iteration
      • Iterating over all but one axis
      • Iterating over multiple arrays
      • Broadcasting over multiple arrays
    • User-defined data-types
      • Adding the new data-type
      • Registering a casting function
      • Registering coercion rules
      • Registering a ufunc loop
    • Subtyping the ndarray in C
      • Creating sub-types
      • Specific features of ndarray sub-typing
        • The __array_finalize__ method
        • The __array_priority__ attribute
        • The __array_wrap__ method


How to extend NumPy

  • NumPy User Guide
  • Using Numpy C-API
  • index
  • next
  • previous

Table Of Contents

  • How to extend NumPy
    • Writing an extension module
    • Required subroutine
    • Defining functions
      • Functions without keyword arguments
      • Functions with keyword arguments
      • Reference counting
    • Dealing with array objects
      • Converting an arbitrary sequence object
      • Creating a brand-new ndarray
      • Getting at ndarray memory and accessing elements of the ndarray
    • Example

Previous topic

Using Numpy C-API

Next topic

Using Python as glue

How to extend NumPy

That which is static and repetitive is boring. That which is dynamic
and random is confusing. In between lies art.
— John A. Locke
Science is a differential equation. Religion is a boundary condition.
— Alan Turing

Writing an extension module

While the ndarray object is designed to allow rapid computation in Python, it is also designed to be general-purpose and satisfy a wide- variety of computational needs. As a result, if absolute speed is essential, there is no replacement for a well-crafted, compiled loop specific to your application and hardware. This is one of the reasons that numpy includes f2py so that an easy-to-use mechanisms for linking (simple) C/C++ and (arbitrary) Fortran code directly into Python are available. You are encouraged to use and improve this mechanism. The purpose of this section is not to document this tool but to document the more basic steps to writing an extension module that this tool depends on.

When an extension module is written, compiled, and installed to somewhere in the Python path (sys.path), the code can then be imported into Python as if it were a standard python file. It will contain objects and methods that have been defined and compiled in C code. The basic steps for doing this in Python are well-documented and you can find more information in the documentation for Python itself available online at www.python.org .

In addition to the Python C-API, there is a full and rich C-API for NumPy allowing sophisticated manipulations on a C-level. However, for most applications, only a few API calls will typically be used. If all you need to do is extract a pointer to memory along with some shape information to pass to another calculation routine, then you will use very different calls, then if you are trying to create a new array- like type or add a new data type for ndarrays. This chapter documents the API calls and macros that are most commonly used.

Required subroutine

There is exactly one function that must be defined in your C-code in order for Python to use it as an extension module. The function must be called init{name} where {name} is the name of the module from Python. This function must be declared so that it is visible to code outside of the routine. Besides adding the methods and constants you desire, this subroutine must also contain calls to import_array() and/or import_ufunc() depending on which C-API is needed. Forgetting to place these commands will show itself as an ugly segmentation fault (crash) as soon as any C-API subroutine is actually called. It is actually possible to have multiple init{name} functions in a single file in which case multiple modules will be defined by that file. However, there are some tricks to get that to work correctly and it is not covered here.

A minimal init{name} method looks like:

PyMODINIT_FUNC
init{name}(void)
{
   (void)Py_InitModule({name}, mymethods);
   import_array();
}

The mymethods must be an array (usually statically declared) of PyMethodDef structures which contain method names, actual C-functions, a variable indicating whether the method uses keyword arguments or not, and docstrings. These are explained in the next section. If you want to add constants to the module, then you store the returned value from Py_InitModule which is a module object. The most general way to add items to the module is to get the module dictionary using PyModule_GetDict(module). With the module dictionary, you can add whatever you like to the module manually. An easier way to add objects to the module is to use one of three additional Python C-API calls that do not require a separate extraction of the module dictionary. These are documented in the Python documentation, but repeated here for convenience:

int PyModule_AddObject( PyObject* module, char* name, PyObject* value)
int PyModule_AddIntConstant( PyObject* module, char* name, long value)
int PyModule_AddStringConstant( PyObject* module, char* name, char* value)

All three of these functions require the module object (the return value of Py_InitModule). The name is a string that labels the value in the module. Depending on which function is called, the value argument is either a general object (PyModule_AddObject steals a reference to it), an integer constant, or a string constant.

Defining functions

The second argument passed in to the Py_InitModule function is a structure that makes it easy to to define functions in the module. In the example given above, the mymethods structure would have been defined earlier in the file (usually right before the init{name} subroutine) to:

static PyMethodDef mymethods[] = {
    { nokeywordfunc,nokeyword_cfunc,
      METH_VARARGS,
      Doc string},
    { keywordfunc, keyword_cfunc,
      METH_VARARGS|METH_KEYWORDS,
      Doc string},
    {NULL, NULL, 0, NULL} /* Sentinel */
}

Each entry in the mymethods array is a PyMethodDef structure containing 1) the Python name, 2) the C-function that implements the function, 3) flags indicating whether or not keywords are accepted for this function, and 4) The docstring for the function. Any number of functions may be defined for a single module by adding more entries to this table. The last entry must be all NULL as shown to act as a sentinel. Python looks for this entry to know that all of the functions for the module have been defined.

The last thing that must be done to finish the extension module is to actually write the code that performs the desired functions. There are two kinds of functions: those that don’t accept keyword arguments, and those that do.

Functions without keyword arguments

Functions that don’t accept keyword arguments should be written as:

static PyObject*
nokeyword_cfunc (PyObject *dummy, PyObject *args)
{
    /* convert Python arguments */
    /* do function */
    /* return something */
}

The dummy argument is not used in this context and can be safely ignored. The args argument contains all of the arguments passed in to the function as a tuple. You can do anything you want at this point, but usually the easiest way to manage the input arguments is to call PyArg_ParseTuple (args, format_string, addresses_to_C_variables...) or PyArg_UnpackTuple (tuple, “name” , min, max, ...). A good description of how to use the first function is contained in the Python C-API reference manual under section 5.5 (Parsing arguments and building values). You should pay particular attention to the “O&” format which uses converter functions to go between the Python object and the C object. All of the other format functions can be (mostly) thought of as special cases of this general rule. There are several converter functions defined in the NumPy C-API that may be of use. In particular, the PyArray_DescrConverter function is very useful to support arbitrary data-type specification. This function transforms any valid data-type Python object into a PyArray_Descr * object. Remember to pass in the address of the C-variables that should be filled in.

There are lots of examples of how to use PyArg_ParseTuple throughout the NumPy source code. The standard usage is like this:

PyObject *input;
PyArray_Descr *dtype;
if (!PyArg_ParseTuple(args, "OO&", &input,
                      PyArray_DescrConverter,
                      &dtype)) return NULL;

It is important to keep in mind that you get a borrowed reference to the object when using the “O” format string. However, the converter functions usually require some form of memory handling. In this example, if the conversion is successful, dtype will hold a new reference to a PyArray_Descr * object, while input will hold a borrowed reference. Therefore, if this conversion were mixed with another conversion (say to an integer) and the data-type conversion was successful but the integer conversion failed, then you would need to release the reference count to the data-type object before returning. A typical way to do this is to set dtype to NULL before calling PyArg_ParseTuple and then use Py_XDECREF on dtype before returning.

After the input arguments are processed, the code that actually does the work is written (likely calling other functions as needed). The final step of the C-function is to return something. If an error is encountered then NULL should be returned (making sure an error has actually been set). If nothing should be returned then increment Py_None and return it. If a single object should be returned then it is returned (ensuring that you own a reference to it first). If multiple objects should be returned then you need to return a tuple. The Py_BuildValue (format_string, c_variables...) function makes it easy to build tuples of Python objects from C variables. Pay special attention to the difference between ‘N’ and ‘O’ in the format string or you can easily create memory leaks. The ‘O’ format string increments the reference count of the PyObject * C-variable it corresponds to, while the ‘N’ format string steals a reference to the corresponding PyObject * C-variable. You should use ‘N’ if you have already created a reference for the object and just want to give that reference to the tuple. You should use ‘O’ if you only have a borrowed reference to an object and need to create one to provide for the tuple.

Functions with keyword arguments

These functions are very similar to functions without keyword arguments. The only difference is that the function signature is:

static PyObject*
keyword_cfunc (PyObject *dummy, PyObject *args, PyObject *kwds)
{
...
}

The kwds argument holds a Python dictionary whose keys are the names of the keyword arguments and whose values are the corresponding keyword-argument values. This dictionary can be processed however you see fit. The easiest way to handle it, however, is to replace the PyArg_ParseTuple (args, format_string, addresses...) function with a call to PyArg_ParseTupleAndKeywords (args, kwds, format_string, char *kwlist[], addresses...). The kwlist parameter to this function is a NULL -terminated array of strings providing the expected keyword arguments. There should be one string for each entry in the format_string. Using this function will raise a TypeError if invalid keyword arguments are passed in.

For more help on this function please see section 1.8 (Keyword Paramters for Extension Functions) of the Extending and Embedding tutorial in the Python documentation.

Reference counting

The biggest difficulty when writing extension modules is reference counting. It is an important reason for the popularity of f2py, weave, Cython, ctypes, etc.... If you mis-handle reference counts you can get problems from memory-leaks to segmentation faults. The only strategy I know of to handle reference counts correctly is blood, sweat, and tears. First, you force it into your head that every Python variable has a reference count. Then, you understand exactly what each function does to the reference count of your objects, so that you can properly use DECREF and INCREF when you need them. Reference counting can really test the amount of patience and diligence you have towards your programming craft. Despite the grim depiction, most cases of reference counting are quite straightforward with the most common difficulty being not using DECREF on objects before exiting early from a routine due to some error. In second place, is the common error of not owning the reference on an object that is passed to a function or macro that is going to steal the reference ( e.g. PyTuple_SET_ITEM, and most functions that take PyArray_Descr objects).

Typically you get a new reference to a variable when it is created or is the return value of some function (there are some prominent exceptions, however — such as getting an item out of a tuple or a dictionary). When you own the reference, you are responsible to make sure that Py_DECREF (var) is called when the variable is no longer necessary (and no other function has “stolen” its reference). Also, if you are passing a Python object to a function that will “steal” the reference, then you need to make sure you own it (or use Py_INCREF to get your own reference). You will also encounter the notion of borrowing a reference. A function that borrows a reference does not alter the reference count of the object and does not expect to “hold on “to the reference. It’s just going to use the object temporarily. When you use PyArg_ParseTuple or PyArg_UnpackTuple you receive a borrowed reference to the objects in the tuple and should not alter their reference count inside your function. With practice, you can learn to get reference counting right, but it can be frustrating at first.

One common source of reference-count errors is the Py_BuildValue function. Pay careful attention to the difference between the ‘N’ format character and the ‘O’ format character. If you create a new object in your subroutine (such as an output array), and you are passing it back in a tuple of return values, then you should most- likely use the ‘N’ format character in Py_BuildValue. The ‘O’ character will increase the reference count by one. This will leave the caller with two reference counts for a brand-new array. When the variable is deleted and the reference count decremented by one, there will still be that extra reference count, and the array will never be deallocated. You will have a reference-counting induced memory leak. Using the ‘N’ character will avoid this situation as it will return to the caller an object (inside the tuple) with a single reference count.

Dealing with array objects

Most extension modules for NumPy will need to access the memory for an ndarray object (or one of it’s sub-classes). The easiest way to do this doesn’t require you to know much about the internals of NumPy. The method is to

  1. Ensure you are dealing with a well-behaved array (aligned, in machine byte-order and single-segment) of the correct type and number of dimensions.

    1. By converting it from some Python object using PyArray_FromAny or a macro built on it.
    2. By constructing a new ndarray of your desired shape and type using PyArray_NewFromDescr or a simpler macro or function based on it.

  2. Get the shape of the array and a pointer to its actual data.

  3. Pass the data and shape information on to a subroutine or other section of code that actually performs the computation.

  4. If you are writing the algorithm, then I recommend that you use the stride information contained in the array to access the elements of the array (the PyArray_GETPTR macros make this painless). Then, you can relax your requirements so as not to force a single-segment array and the data-copying that might result.

Each of these sub-topics is covered in the following sub-sections.

Converting an arbitrary sequence object

The main routine for obtaining an array from any Python object that can be converted to an array is PyArray_FromAny. This function is very flexible with many input arguments. Several macros make it easier to use the basic function. PyArray_FROM_OTF is arguably the most useful of these macros for the most common uses. It allows you to convert an arbitrary Python object to an array of a specific builtin data-type ( e.g. float), while specifying a particular set of requirements ( e.g. contiguous, aligned, and writeable). The syntax is

PyObject *PyArray_FROM_OTF( PyObject* obj, int typenum, int requirements)

Return an ndarray from any Python object, obj, that can be converted to an array. The number of dimensions in the returned array is determined by the object. The desired data-type of the returned array is provided in typenum which should be one of the enumerated types. The requirements for the returned array can be any combination of standard array flags. Each of these arguments is explained in more detail below. You receive a new reference to the array on success. On failure, NULL is returned and an exception is set.

obj

The object can be any Python object convertable to an ndarray. If the object is already (a subclass of) the ndarray that satisfies the requirements then a new reference is returned. Otherwise, a new array is constructed. The contents of obj are copied to the new array unless the array interface is used so that data does not have to be copied. Objects that can be converted to an array include: 1) any nested sequence object, 2) any object exposing the array interface, 3) any object with an __array__ method (which should return an ndarray), and 4) any scalar object (becomes a zero-dimensional array). Sub-classes of the ndarray that otherwise fit the requirements will be passed through. If you want to ensure a base-class ndarray, then use NPY_ENSUREARRAY in the requirements flag. A copy is made only if necessary. If you want to guarantee a copy, then pass in NPY_ENSURECOPY to the requirements flag.

typenum

One of the enumerated types or NPY_NOTYPE if the data-type should be determined from the object itself. The C-based names can be used:

NPY_BOOL, NPY_BYTE, NPY_UBYTE, NPY_SHORT, NPY_USHORT, NPY_INT, NPY_UINT, NPY_LONG, NPY_ULONG, NPY_LONGLONG, NPY_ULONGLONG, NPY_DOUBLE, NPY_LONGDOUBLE, NPY_CFLOAT, NPY_CDOUBLE, NPY_CLONGDOUBLE, NPY_OBJECT.

Alternatively, the bit-width names can be used as supported on the platform. For example:

NPY_INT8, NPY_INT16, NPY_INT32, NPY_INT64, NPY_UINT8, NPY_UINT16, NPY_UINT32, NPY_UINT64, NPY_FLOAT32, NPY_FLOAT64, NPY_COMPLEX64, NPY_COMPLEX128.

The object will be converted to the desired type only if it can be done without losing precision. Otherwise NULL will be returned and an error raised. Use NPY_FORCECAST in the requirements flag to override this behavior.

requirements

The memory model for an ndarray admits arbitrary strides in each dimension to advance to the next element of the array. Often, however, you need to interface with code that expects a C-contiguous or a Fortran-contiguous memory layout. In addition, an ndarray can be misaligned (the address of an element is not at an integral multiple of the size of the element) which can cause your program to crash (or at least work more slowly) if you try and dereference a pointer into the array data. Both of these problems can be solved by converting the Python object into an array that is more “well-behaved” for your specific usage.

The requirements flag allows specification of what kind of array is acceptable. If the object passed in does not satisfy this requirements then a copy is made so that thre returned object will satisfy the requirements. these ndarray can use a very generic pointer to memory. This flag allows specification of the desired properties of the returned array object. All of the flags are explained in the detailed API chapter. The flags most commonly needed are NPY_ARRAY_IN_ARRAY, NPY_OUT_ARRAY, and NPY_ARRAY_INOUT_ARRAY:

NPY_ARRAY_IN_ARRAY

Equivalent to NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED. This combination of flags is useful for arrays that must be in C-contiguous order and aligned. These kinds of arrays are usually input arrays for some algorithm.

NPY_ARRAY_OUT_ARRAY

Equivalent to NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE. This combination of flags is useful to specify an array that is in C-contiguous order, is aligned, and can be written to as well. Such an array is usually returned as output (although normally such output arrays are created from scratch).

NPY_ARRAY_INOUT_ARRAY

Equivalent to NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE | NPY_ARRAY_UPDATEIFCOPY. This combination of flags is useful to specify an array that will be used for both input and output. If a copy is needed, then when the temporary is deleted (by your use of Py_DECREF at the end of the interface routine), the temporary array will be copied back into the original array passed in. Use of the NPY_ARRAY_UPDATEIFCOPY flag requires that the input object is already an array (because other objects cannot be automatically updated in this fashion). If an error occurs use PyArray_DECREF_ERR (obj) on an array with the NPY_ARRAY_UPDATEIFCOPY flag set. This will delete the array without causing the contents to be copied back into the original array.

Other useful flags that can be OR’d as additional requirements are:

NPY_ARRAY_FORCECAST

Cast to the desired type, even if it can’t be done without losing information.

NPY_ARRAY_ENSURECOPY

Make sure the resulting array is a copy of the original.

NPY_ARRAY_ENSUREARRAY

Make sure the resulting object is an actual ndarray and not a sub- class.

Note

Whether or not an array is byte-swapped is determined by the data-type of the array. Native byte-order arrays are always requested by PyArray_FROM_OTF and so there is no need for a NPY_ARRAY_NOTSWAPPED flag in the requirements argument. There is also no way to get a byte-swapped array from this routine.

Creating a brand-new ndarray

Quite often new arrays must be created from within extension-module code. Perhaps an output array is needed and you don’t want the caller to have to supply it. Perhaps only a temporary array is needed to hold an intermediate calculation. Whatever the need there are simple ways to get an ndarray object of whatever data-type is needed. The most general function for doing this is PyArray_NewFromDescr. All array creation functions go through this heavily re-used code. Because of its flexibility, it can be somewhat confusing to use. As a result, simpler forms exist that are easier to use.

PyObject *PyArray_SimpleNew(int nd, npy_intp* dims, int typenum)

This function allocates new memory and places it in an ndarray with nd dimensions whose shape is determined by the array of at least nd items pointed to by dims. The memory for the array is uninitialized (unless typenum is NPY_OBJECT in which case each element in the array is set to NULL). The typenum argument allows specification of any of the builtin data-types such as NPY_FLOAT or NPY_LONG. The memory for the array can be set to zero if desired using PyArray_FILLWBYTE (return_object, 0).

PyObject *PyArray_SimpleNewFromData(int nd, npy_intp* dims, int typenum, void* data)

Sometimes, you want to wrap memory allocated elsewhere into an ndarray object for downstream use. This routine makes it straightforward to do that. The first three arguments are the same as in PyArray_SimpleNew, the final argument is a pointer to a block of contiguous memory that the ndarray should use as it’s data-buffer which will be interpreted in C-style contiguous fashion. A new reference to an ndarray is returned, but the ndarray will not own its data. When this ndarray is deallocated, the pointer will not be freed.

You should ensure that the provided memory is not freed while the returned array is in existence. The easiest way to handle this is if data comes from another reference-counted Python object. The reference count on this object should be increased after the pointer is passed in, and the base member of the returned ndarray should point to the Python object that owns the data. Then, when the ndarray is deallocated, the base-member will be DECREF’d appropriately. If you want the memory to be freed as soon as the ndarray is deallocated then simply set the OWNDATA flag on the returned ndarray.

Getting at ndarray memory and accessing elements of the ndarray

If obj is an ndarray (PyArrayObject *), then the data-area of the ndarray is pointed to by the void* pointer PyArray_DATA (obj) or the char* pointer PyArray_BYTES (obj). Remember that (in general) this data-area may not be aligned according to the data-type, it may represent byte-swapped data, and/or it may not be writeable. If the data area is aligned and in native byte-order, then how to get at a specific element of the array is determined only by the array of npy_intp variables, PyArray_STRIDES (obj). In particular, this c-array of integers shows how many bytes must be added to the current element pointer to get to the next element in each dimension. For arrays less than 4-dimensions there are PyArray_GETPTR{k} (obj, ...) macros where {k} is the integer 1, 2, 3, or 4 that make using the array strides easier. The arguments .... represent {k} non- negative integer indices into the array. For example, suppose E is a 3-dimensional ndarray. A (void*) pointer to the element E[i,j,k] is obtained as PyArray_GETPTR3 (E, i, j, k).

As explained previously, C-style contiguous arrays and Fortran-style contiguous arrays have particular striding patterns. Two array flags (NPY_C_CONTIGUOUS and :cdata`NPY_F_CONTIGUOUS`) indicate whether or not the striding pattern of a particular array matches the C-style contiguous or Fortran-style contiguous or neither. Whether or not the striding pattern matches a standard C or Fortran one can be tested Using PyArray_ISCONTIGUOUS (obj) and PyArray_ISFORTRAN (obj) respectively. Most third-party libraries expect contiguous arrays. But, often it is not difficult to support general-purpose striding. I encourage you to use the striding information in your own code whenever possible, and reserve single-segment requirements for wrapping third-party code. Using the striding information provided with the ndarray rather than requiring a contiguous striding reduces copying that otherwise must be made.

Example

The following example shows how you might write a wrapper that accepts two input arguments (that will be converted to an array) and an output argument (that must be an array). The function returns None and updates the output array.

static PyObject *
example_wrapper(PyObject *dummy, PyObject *args)
{
    PyObject *arg1=NULL, *arg2=NULL, *out=NULL;
    PyObject *arr1=NULL, *arr2=NULL, *oarr=NULL;

    if (!PyArg_ParseTuple(args, "OOO!", &arg1, &arg2,
        &PyArray_Type, &out)) return NULL;

    arr1 = PyArray_FROM_OTF(arg1, NPY_DOUBLE, NPY_IN_ARRAY);
    if (arr1 == NULL) return NULL;
    arr2 = PyArray_FROM_OTF(arg2, NPY_DOUBLE, NPY_IN_ARRAY);
    if (arr2 == NULL) goto fail;
    oarr = PyArray_FROM_OTF(out, NPY_DOUBLE, NPY_INOUT_ARRAY);
    if (oarr == NULL) goto fail;

    /* code that makes use of arguments */
    /* You will probably need at least
       nd = PyArray_NDIM(<..>)    -- number of dimensions
       dims = PyArray_DIMS(<..>)  -- npy_intp array of length nd
                                     showing length in each dim.
       dptr = (double *)PyArray_DATA(<..>) -- pointer to data.

       If an error occurs goto fail.
     */

    Py_DECREF(arr1);
    Py_DECREF(arr2);
    Py_DECREF(oarr);
    Py_INCREF(Py_None);
    return Py_None;

 fail:
    Py_XDECREF(arr1);
    Py_XDECREF(arr2);
    PyArray_XDECREF_ERR(oarr);
    return NULL;
}


Using Python as glue

  • NumPy User Guide
  • Using Numpy C-API
  • index
  • next
  • previous

Table Of Contents

  • Using Python as glue
    • Calling other compiled libraries from Python
    • Hand-generated wrappers
    • f2py
      • Creating source for a basic extension module
      • Creating a compiled extension module
      • Improving the basic interface
      • Inserting directives in Fortran source
      • A filtering example
      • Calling f2py from Python
      • Automatic extension module generation
      • Conclusion
    • Cython
      • Complex addition in Cython
      • Image filter in Cython
      • Conclusion
    • ctypes
      • Having a shared library
      • Loading the shared library
      • Converting arguments
      • Calling the function
      • Complete example
      • Conclusion
    • Additional tools you may find useful
      • SWIG
      • SIP
      • Boost Python
      • PyFort

Previous topic

How to extend NumPy

Next topic

Writing your own ufunc

Using Python as glue

There is no conversation more boring than the one where everybody
agrees.
— Michel de Montaigne
Duct tape is like the force. It has a light side, and a dark side, and
it holds the universe together.
— Carl Zwanzig

Many people like to say that Python is a fantastic glue language. Hopefully, this Chapter will convince you that this is true. The first adopters of Python for science were typically people who used it to glue together large application codes running on super-computers. Not only was it much nicer to code in Python than in a shell script or Perl, in addition, the ability to easily extend Python made it relatively easy to create new classes and types specifically adapted to the problems being solved. From the interactions of these early contributors, Numeric emerged as an array-like object that could be used to pass data between these applications.

As Numeric has matured and developed into NumPy, people have been able to write more code directly in NumPy. Often this code is fast-enough for production use, but there are still times that there is a need to access compiled code. Either to get that last bit of efficiency out of the algorithm or to make it easier to access widely-available codes written in C/C++ or Fortran.

This chapter will review many of the tools that are available for the purpose of accessing code written in other compiled languages. There are many resources available for learning to call other compiled libraries from Python and the purpose of this Chapter is not to make you an expert. The main goal is to make you aware of some of the possibilities so that you will know what to “Google” in order to learn more.

The http://www.scipy.org website also contains a great deal of useful information about many of these tools. For example, there is a nice description of using several of the tools explained in this chapter at http://www.scipy.org/PerformancePython. This link provides several ways to solve the same problem showing how to use and connect with compiled code to get the best performance. In the process you can get a taste for several of the approaches that will be discussed in this chapter.

Calling other compiled libraries from Python

While Python is a great language and a pleasure to code in, its dynamic nature results in overhead that can cause some code ( i.e. raw computations inside of for loops) to be up 10-100 times slower than equivalent code written in a static compiled language. In addition, it can cause memory usage to be larger than necessary as temporary arrays are created and destroyed during computation. For many types of computing needs the extra slow-down and memory consumption can often not be spared (at least for time- or memory- critical portions of your code). Therefore one of the most common needs is to call out from Python code to a fast, machine-code routine (e.g. compiled using C/C++ or Fortran). The fact that this is relatively easy to do is a big reason why Python is such an excellent high-level language for scientific and engineering programming.

Their are two basic approaches to calling compiled code: writing an extension module that is then imported to Python using the import command, or calling a shared-library subroutine directly from Python using the ctypes module (included in the standard distribution since Python 2.5). The first method is the most common (but with the inclusion of ctypes into Python 2.5 this status may change).

Warning

Calling C-code from Python can result in Python crashes if you are not careful. None of the approaches in this chapter are immune. You have to know something about the way data is handled by both NumPy and by the third-party library being used.

Hand-generated wrappers

Extension modules were discussed in Chapter 1 . The most basic way to interface with compiled code is to write an extension module and construct a module method that calls the compiled code. For improved readability, your method should take advantage of the PyArg_ParseTuple call to convert between Python objects and C data-types. For standard C data-types there is probably already a built-in converter. For others you may need to write your own converter and use the “O&” format string which allows you to specify a function that will be used to perform the conversion from the Python object to whatever C-structures are needed.

Once the conversions to the appropriate C-structures and C data-types have been performed, the next step in the wrapper is to call the underlying function. This is straightforward if the underlying function is in C or C++. However, in order to call Fortran code you must be familiar with how Fortran subroutines are called from C/C++ using your compiler and platform. This can vary somewhat platforms and compilers (which is another reason f2py makes life much simpler for interfacing Fortran code) but generally involves underscore mangling of the name and the fact that all variables are passed by reference (i.e. all arguments are pointers).

The advantage of the hand-generated wrapper is that you have complete control over how the C-library gets used and called which can lead to a lean and tight interface with minimal over-head. The disadvantage is that you have to write, debug, and maintain C-code, although most of it can be adapted using the time-honored technique of “cutting-pasting-and-modifying” from other extension modules. Because, the procedure of calling out to additional C-code is fairly regimented, code-generation procedures have been developed to make this process easier. One of these code- generation techniques is distributed with NumPy and allows easy integration with Fortran and (simple) C code. This package, f2py, will be covered briefly in the next session.

f2py

F2py allows you to automatically construct an extension module that interfaces to routines in Fortran 77/90/95 code. It has the ability to parse Fortran 77/90/95 code and automatically generate Python signatures for the subroutines it encounters, or you can guide how the subroutine interfaces with Python by constructing an interface-definition-file (or modifying the f2py-produced one).

Creating source for a basic extension module

Probably the easiest way to introduce f2py is to offer a simple example. Here is one of the subroutines contained in a file named add.f:

C
      SUBROUTINE ZADD(A,B,C,N)
C
      DOUBLE COMPLEX A(*)
      DOUBLE COMPLEX B(*)
      DOUBLE COMPLEX C(*)
      INTEGER N
      DO 20 J = 1, N
         C(J) = A(J)+B(J)
 20   CONTINUE
      END

This routine simply adds the elements in two contiguous arrays and places the result in a third. The memory for all three arrays must be provided by the calling routine. A very basic interface to this routine can be automatically generated by f2py:

f2py -m add add.f

You should be able to run this command assuming your search-path is set-up properly. This command will produce an extension module named addmodule.c in the current directory. This extension module can now be compiled and used from Python just like any other extension module.

Creating a compiled extension module

You can also get f2py to compile add.f and also compile its produced extension module leaving only a shared-library extension file that can be imported from Python:

f2py -c -m add add.f

This command leaves a file named add.{ext} in the current directory (where {ext} is the appropriate extension for a python extension module on your platform — so, pyd, etc. ). This module may then be imported from Python. It will contain a method for each subroutine in add (zadd, cadd, dadd, sadd). The docstring of each method contains information about how the module method may be called:

>>> import add
>>> print add.zadd.__doc__
zadd - Function signature:
  zadd(a,b,c,n)
Required arguments:
  a : input rank-1 array('D') with bounds (*)
  b : input rank-1 array('D') with bounds (*)
  c : input rank-1 array('D') with bounds (*)
  n : input int

Improving the basic interface

The default interface is a very literal translation of the fortran code into Python. The Fortran array arguments must now be NumPy arrays and the integer argument should be an integer. The interface will attempt to convert all arguments to their required types (and shapes) and issue an error if unsuccessful. However, because it knows nothing about the semantics of the arguments (such that C is an output and n should really match the array sizes), it is possible to abuse this function in ways that can cause Python to crash. For example:

>>> add.zadd([1,2,3],[1,2],[3,4],1000)

will cause a program crash on most systems. Under the covers, the lists are being converted to proper arrays but then the underlying add loop is told to cycle way beyond the borders of the allocated memory.

In order to improve the interface, directives should be provided. This is accomplished by constructing an interface definition file. It is usually best to start from the interface file that f2py can produce (where it gets its default behavior from). To get f2py to generate the interface file use the -h option:

f2py -h add.pyf -m add add.f

This command leaves the file add.pyf in the current directory. The section of this file corresponding to zadd is:

subroutine zadd(a,b,c,n) ! in :add:add.f
   double complex dimension(*) :: a
   double complex dimension(*) :: b
   double complex dimension(*) :: c
   integer :: n
end subroutine zadd

By placing intent directives and checking code, the interface can be cleaned up quite a bit until the Python module method is both easier to use and more robust.

subroutine zadd(a,b,c,n) ! in :add:add.f
   double complex dimension(n) :: a
   double complex dimension(n) :: b
   double complex intent(out),dimension(n) :: c
   integer intent(hide),depend(a) :: n=len(a)
end subroutine zadd

The intent directive, intent(out) is used to tell f2py that c is an output variable and should be created by the interface before being passed to the underlying code. The intent(hide) directive tells f2py to not allow the user to specify the variable, n, but instead to get it from the size of a. The depend( a ) directive is necessary to tell f2py that the value of n depends on the input a (so that it won’t try to create the variable n until the variable a is created).

After modifying add.pyf, the new python module file can be generated by compiling both add.f95 and add.pyf:

f2py -c add.pyf add.f95

The new interface has docstring:

>>> import add
>>> print add.zadd.__doc__
zadd - Function signature:
  c = zadd(a,b)
Required arguments:
  a : input rank-1 array('D') with bounds (n)
  b : input rank-1 array('D') with bounds (n)
Return objects:
  c : rank-1 array('D') with bounds (n)

Now, the function can be called in a much more robust way:

>>> add.zadd([1,2,3],[4,5,6])
array([ 5.+0.j,  7.+0.j,  9.+0.j])

Notice the automatic conversion to the correct format that occurred.

Inserting directives in Fortran source

The nice interface can also be generated automatically by placing the variable directives as special comments in the original fortran code. Thus, if I modify the source code to contain:

C
      SUBROUTINE ZADD(A,B,C,N)
C
CF2PY INTENT(OUT) :: C
CF2PY INTENT(HIDE) :: N
CF2PY DOUBLE COMPLEX :: A(N)
CF2PY DOUBLE COMPLEX :: B(N)
CF2PY DOUBLE COMPLEX :: C(N)
      DOUBLE COMPLEX A(*)
      DOUBLE COMPLEX B(*)
      DOUBLE COMPLEX C(*)
      INTEGER N
      DO 20 J = 1, N
         C(J) = A(J) + B(J)
 20   CONTINUE
      END

Then, I can compile the extension module using:

f2py -c -m add add.f

The resulting signature for the function add.zadd is exactly the same one that was created previously. If the original source code had contained A(N) instead of A(*) and so forth with B and C, then I could obtain (nearly) the same interface simply by placing the INTENT(OUT) :: C comment line in the source code. The only difference is that N would be an optional input that would default to the length of A.

A filtering example

For comparison with the other methods to be discussed. Here is another example of a function that filters a two-dimensional array of double precision floating-point numbers using a fixed averaging filter. The advantage of using Fortran to index into multi-dimensional arrays should be clear from this example.

      SUBROUTINE DFILTER2D(A,B,M,N)
C
      DOUBLE PRECISION A(M,N)
      DOUBLE PRECISION B(M,N)
      INTEGER N, M
CF2PY INTENT(OUT) :: B
CF2PY INTENT(HIDE) :: N
CF2PY INTENT(HIDE) :: M
      DO 20 I = 2,M-1
         DO 40 J=2,N-1
            B(I,J) = A(I,J) +
     $           (A(I-1,J)+A(I+1,J) +
     $            A(I,J-1)+A(I,J+1) )*0.5D0 +
     $           (A(I-1,J-1) + A(I-1,J+1) +
     $            A(I+1,J-1) + A(I+1,J+1))*0.25D0
 40      CONTINUE
 20   CONTINUE
      END

This code can be compiled and linked into an extension module named filter using:

f2py -c -m filter filter.f

This will produce an extension module named filter.so in the current directory with a method named dfilter2d that returns a filtered version of the input.

Calling f2py from Python

The f2py program is written in Python and can be run from inside your code to compile Fortran code at runtime, as follows:

from numpy import f2py
with open("add.f") as sourcefile:
    sourcecode = sourcefile.read()
f2py.compile(sourcecode, modulename='add')
import add

The source string can be any valid Fortran code. If you want to save the extension-module source code then a suitable file-name can be provided by the source_fn keyword to the compile function.

Automatic extension module generation

If you want to distribute your f2py extension module, then you only need to include the .pyf file and the Fortran code. The distutils extensions in NumPy allow you to define an extension module entirely in terms of this interface file. A valid setup.py file allowing distribution of the add.f module (as part of the package f2py_examples so that it would be loaded as f2py_examples.add) is:

def configuration(parent_package='', top_path=None)
    from numpy.distutils.misc_util import Configuration
    config = Configuration('f2py_examples',parent_package, top_path)
    config.add_extension('add', sources=['add.pyf','add.f'])
    return config

if __name__ == '__main__':
    from numpy.distutils.core import setup
    setup(**configuration(top_path='').todict())

Installation of the new package is easy using:

python setup.py install

assuming you have the proper permissions to write to the main site- packages directory for the version of Python you are using. For the resulting package to work, you need to create a file named __init__.py (in the same directory as add.pyf). Notice the extension module is defined entirely in terms of the “add.pyf” and “add.f” files. The conversion of the .pyf file to a .c file is handled by numpy.disutils.

Conclusion

The interface definition file (.pyf) is how you can fine-tune the interface between Python and Fortran. There is decent documentation for f2py found in the numpy/f2py/docs directory where-ever NumPy is installed on your system (usually under site-packages). There is also more information on using f2py (including how to use it to wrap C codes) at http://www.scipy.org/Cookbook under the “Using NumPy with Other Languages” heading.

The f2py method of linking compiled code is currently the most sophisticated and integrated approach. It allows clean separation of Python with compiled code while still allowing for separate distribution of the extension module. The only draw-back is that it requires the existence of a Fortran compiler in order for a user to install the code. However, with the existence of the free-compilers g77, gfortran, and g95, as well as high-quality commerical compilers, this restriction is not particularly onerous. In my opinion, Fortran is still the easiest way to write fast and clear code for scientific computing. It handles complex numbers, and multi-dimensional indexing in the most straightforward way. Be aware, however, that some Fortran compilers will not be able to optimize code as well as good hand- written C-code.

Cython

Cython is a compiler for a Python dialect that adds (optional) static typing for speed, and allows mixing C or C++ code into your modules. It produces C or C++ extensions that can be compiled and imported in Python code.

If you are writing an extension module that will include quite a bit of your own algorithmic code as well, then Cython is a good match. Among its features is the ability to easily and quickly work with multidimensional arrays.

Notice that Cython is an extension-module generator only. Unlike f2py, it includes no automatic facility for compiling and linking the extension module (which must be done in the usual fashion). It does provide a modified distutils class called build_ext which lets you build an extension module from a .pyx source. Thus, you could write in a setup.py file:

from Cython.Distutils import build_ext
from distutils.extension import Extension
from distutils.core import setup
import numpy

setup(name='mine', description='Nothing',
      ext_modules=[Extension('filter', ['filter.pyx'],
                             include_dirs=[numpy.get_include()])],
      cmdclass = {'build_ext':build_ext})

Adding the NumPy include directory is, of course, only necessary if you are using NumPy arrays in the extension module (which is what we assume you are using Cython for). The distutils extensions in NumPy also include support for automatically producing the extension-module and linking it from a .pyx file. It works so that if the user does not have Cython installed, then it looks for a file with the same file-name but a .c extension which it then uses instead of trying to produce the .c file again.

If you just use Cython to compile a standard Python module, then you will get a C extension module that typically runs a bit faster than the equivalent Python module. Further speed increases can be gained by using the cdef keyword to statically define C variables.

Let’s look at two examples we’ve seen before to see how they might be implemented using Cython. These examples were compiled into extension modules using Cython 0.21.1.

Complex addition in Cython

Here is part of a Cython module named add.pyx which implements the complex addition functions we previously implemented using f2py:

cimport cython
cimport numpy as np
import numpy as np

# We need to initialize NumPy.
np.import_array()

#@cython.boundscheck(False)
def zadd(in1, in2):
    cdef double complex[:] a = in1.ravel()
    cdef double complex[:] b = in2.ravel()

    out = np.empty(a.shape[0], np.complex64)
    cdef double complex[:] c = out.ravel()

    for i in range(c.shape[0]):
        c[i].real = a[i].real + b[i].real
        c[i].imag = a[i].imag + b[i].imag

    return out

This module shows use of the cimport statement to load the definitions from the numpy.pxd header that ships with Cython. It looks like NumPy is imported twice; cimport only makes the NumPy C-API available, while the regular import causes a Python-style import at runtime and makes it possible to call into the familiar NumPy Python API.

The example also demonstrates Cython’s “typed memoryviews”, which are like NumPy arrays at the C level, in the sense that they are shaped and strided arrays that know their own extent (unlike a C array addressed through a bare pointer). The syntax double complex[:] denotes a one-dimensional array (vector) of doubles, with arbitrary strides. A contiguous array of ints would be int[::1], while a matrix of floats would be float[:, :].

Shown commented is the cython.boundscheck decorator, which turns bounds-checking for memory view accesses on or off on a per-function basis. We can use this to further speed up our code, at the expense of safety (or a manual check prior to entering the loop).

Other than the view syntax, the function is immediately readable to a Python programmer. Static typing of the variable i is implicit. Instead of the view syntax, we could also have used Cython’s special NumPy array syntax, but the view syntax is preferred.

Image filter in Cython

The two-dimensional example we created using Fortran is just as easy to write in Cython:

cimport numpy as np
import numpy as np

np.import_array()

def filter(img):
    cdef double[:, :] a = np.asarray(img, dtype=np.double)
    out = np.zeros(img.shape, dtype=np.double)
    cdef double[:, ::1] b = out

    cdef np.npy_intp i, j

    for i in range(1, a.shape[0] - 1):
        for j in range(1, a.shape[1] - 1):
            b[i, j] = (a[i, j]
                       + .5 * (  a[i-1, j] + a[i+1, j]
                               + a[i, j-1] + a[i, j+1])
                       + .25 * (  a[i-1, j-1] + a[i-1, j+1]
                                + a[i+1, j-1] + a[i+1, j+1]))

    return out

This 2-d averaging filter runs quickly because the loop is in C and the pointer computations are done only as needed. If the code above is compiled as a module image, then a 2-d image, img, can be filtered using this code very quickly using:

import image
out = image.filter(img)

Regarding the code, two things are of note: firstly, it is impossible to return a memory view to Python. Instead, a NumPy array out is first created, and then a view b onto this array is used for the computation. Secondly, the view b is typed double[:, ::1]. This means 2-d array with contiguous rows, i.e., C matrix order. Specifying the order explicitly can speed up some algorithms since they can skip stride computations.

Conclusion

Cython is the extension mechanism of choice for several scientific Python libraries, including Pandas, SAGE, scikit-image and scikit-learn, as well as the XML processing library LXML. The language and compiler are well-maintained.

There are several disadvantages of using Cython:

  1. When coding custom algorithms, and sometimes when wrapping existing C libraries, some familiarity with C is required. In particular, when using C memory management (malloc and friends), it’s easy to introduce memory leaks. However, just compiling a Python module renamed to .pyx can already speed it up, and adding a few type declarations can give dramatic speedups in some code.
  2. It is easy to lose a clean separation between Python and C which makes re-using your C-code for other non-Python-related projects more difficult.
  3. The C-code generated by Cython is hard to read and modify (and typically compiles with annoying but harmless warnings).

One big advantage of Cython-generated extension modules is that they are easy to distribute. In summary, Cython is a very capable tool for either gluing C code or generating an extension module quickly and should not be over-looked. It is especially useful for people that can’t or won’t write C or Fortran code.

ctypes

Ctypes is a Python extension module, included in the stdlib, that allows you to call an arbitrary function in a shared library directly from Python. This approach allows you to interface with C-code directly from Python. This opens up an enormous number of libraries for use from Python. The drawback, however, is that coding mistakes can lead to ugly program crashes very easily (just as can happen in C) because there is little type or bounds checking done on the parameters. This is especially true when array data is passed in as a pointer to a raw memory location. The responsibility is then on you that the subroutine will not access memory outside the actual array area. But, if you don’t mind living a little dangerously ctypes can be an effective tool for quickly taking advantage of a large shared library (or writing extended functionality in your own shared library).

Because the ctypes approach exposes a raw interface to the compiled code it is not always tolerant of user mistakes. Robust use of the ctypes module typically involves an additional layer of Python code in order to check the data types and array bounds of objects passed to the underlying subroutine. This additional layer of checking (not to mention the conversion from ctypes objects to C-data-types that ctypes itself performs), will make the interface slower than a hand-written extension-module interface. However, this overhead should be neglible if the C-routine being called is doing any significant amount of work. If you are a great Python programmer with weak C-skills, ctypes is an easy way to write a useful interface to a (shared) library of compiled code.

To use c-types you must

  1. Have a shared library.
  2. Load the shared library.
  3. Convert the python objects to ctypes-understood arguments.
  4. Call the function from the library with the ctypes arguments.

Having a shared library

There are several requirements for a shared library that can be used with c-types that are platform specific. This guide assumes you have some familiarity with making a shared library on your system (or simply have a shared library available to you). Items to remember are:

  • A shared library must be compiled in a special way ( e.g. using the -shared flag with gcc).

  • On some platforms (e.g. Windows) , a shared library requires a .def file that specifies the functions to be exported. For example a mylib.def file might contain.

    LIBRARY mylib.dll
EXPORTS
cool_function1
cool_function2

    Alternatively, you may be able to use the storage-class specifier __declspec(dllexport) in the C-definition of the function to avoid the need for this .def file.

There is no standard way in Python distutils to create a standard shared library (an extension module is a “special” shared library Python understands) in a cross-platform manner. Thus, a big disadvantage of ctypes at the time of writing this book is that it is difficult to distribute in a cross-platform manner a Python extension that uses c-types and includes your own code which should be compiled as a shared library on the users system.

Loading the shared library

A simple, but robust way to load the shared library is to get the absolute path name and load it using the cdll object of ctypes.:

lib = ctypes.cdll[<full_path_name>]

However, on Windows accessing an attribute of the cdll method will load the first DLL by that name found in the current directory or on the PATH. Loading the absolute path name requires a little finesse for cross-platform work since the extension of shared libraries varies. There is a ctypes.util.find_library utility available that can simplify the process of finding the library to load but it is not foolproof. Complicating matters, different platforms have different default extensions used by shared libraries (e.g. .dll – Windows, .so – Linux, .dylib – Mac OS X). This must also be taken into account if you are using c-types to wrap code that needs to work on several platforms.

NumPy provides a convenience function called ctypeslib.load_library (name, path). This function takes the name of the shared library (including any prefix like ‘lib’ but excluding the extension) and a path where the shared library can be located. It returns a ctypes library object or raises an OSError if the library cannot be found or raises an ImportError if the ctypes module is not available. (Windows users: the ctypes library object loaded using load_library is always loaded assuming cdecl calling convention. See the ctypes documentation under ctypes.windll and/or ctypes.oledll for ways to load libraries under other calling conventions).

The functions in the shared library are available as attributes of the ctypes library object (returned from ctypeslib.load_library) or as items using lib['func_name'] syntax. The latter method for retrieving a function name is particularly useful if the function name contains characters that are not allowable in Python variable names.

Converting arguments

Python ints/longs, strings, and unicode objects are automatically converted as needed to equivalent c-types arguments The None object is also converted automatically to a NULL pointer. All other Python objects must be converted to ctypes-specific types. There are two ways around this restriction that allow c-types to integrate with other objects.

  1. Don’t set the argtypes attribute of the function object and define an _as_parameter_ method for the object you want to pass in. The _as_parameter_ method must return a Python int which will be passed directly to the function.
  2. Set the argtypes attribute to a list whose entries contain objects with a classmethod named from_param that knows how to convert your object to an object that ctypes can understand (an int/long, string, unicode, or object with the _as_parameter_ attribute).

NumPy uses both methods with a preference for the second method because it can be safer. The ctypes attribute of the ndarray returns an object that has an _as_parameter_ attribute which returns an integer representing the address of the ndarray to which it is associated. As a result, one can pass this ctypes attribute object directly to a function expecting a pointer to the data in your ndarray. The caller must be sure that the ndarray object is of the correct type, shape, and has the correct flags set or risk nasty crashes if the data-pointer to inappropriate arrays are passsed in.

To implement the second method, NumPy provides the class-factory function ndpointer in the ctypeslib module. This class-factory function produces an appropriate class that can be placed in an argtypes attribute entry of a ctypes function. The class will contain a from_param method which ctypes will use to convert any ndarray passed in to the function to a ctypes-recognized object. In the process, the conversion will perform checking on any properties of the ndarray that were specified by the user in the call to ndpointer. Aspects of the ndarray that can be checked include the data-type, the number-of-dimensions, the shape, and/or the state of the flags on any array passed. The return value of the from_param method is the ctypes attribute of the array which (because it contains the _as_parameter_ attribute pointing to the array data area) can be used by ctypes directly.

The ctypes attribute of an ndarray is also endowed with additional attributes that may be convenient when passing additional information about the array into a ctypes function. The attributes data, shape, and strides can provide c-types compatible types corresponding to the data-area, the shape, and the strides of the array. The data attribute reutrns a c_void_p representing a pointer to the data area. The shape and strides attributes each return an array of ctypes integers (or None representing a NULL pointer, if a 0-d array). The base ctype of the array is a ctype integer of the same size as a pointer on the platform. There are also methods data_as({ctype}), shape_as(<base ctype>), and strides_as(<base ctype>). These return the data as a ctype object of your choice and the shape/strides arrays using an underlying base type of your choice. For convenience, the ctypeslib module also contains c_intp as a ctypes integer data-type whose size is the same as the size of c_void_p on the platform (it’s value is None if ctypes is not installed).

Calling the function

The function is accessed as an attribute of or an item from the loaded shared-library. Thus, if ”./mylib.so” has a function named “cool_function1” , I could access this function either as:

lib = numpy.ctypeslib.load_library('mylib','.')
func1 = lib.cool_function1 # or equivalently
func1 = lib['cool_function1']

In ctypes, the return-value of a function is set to be ‘int’ by default. This behavior can be changed by setting the restype attribute of the function. Use None for the restype if the function has no return value (‘void’):

func1.restype = None

As previously discussed, you can also set the argtypes attribute of the function in order to have ctypes check the types of the input arguments when the function is called. Use the ndpointer factory function to generate a ready-made class for data-type, shape, and flags checking on your new function. The ndpointer function has the signature

ndpointer(dtype=None, ndim=None, shape=None, flags=None)

Keyword arguments with the value None are not checked. Specifying a keyword enforces checking of that aspect of the ndarray on conversion to a ctypes-compatible object. The dtype keyword can be any object understood as a data-type object. The ndim keyword should be an integer, and the shape keyword should be an integer or a sequence of integers. The flags keyword specifies the minimal flags that are required on any array passed in. This can be specified as a string of comma separated requirements, an integer indicating the requirement bits OR’d together, or a flags object returned from the flags attribute of an array with the necessary requirements.

Using an ndpointer class in the argtypes method can make it significantly safer to call a C-function using ctypes and the data- area of an ndarray. You may still want to wrap the function in an additional Python wrapper to make it user-friendly (hiding some obvious arguments and making some arguments output arguments). In this process, the requires function in NumPy may be useful to return the right kind of array from a given input.

Complete example

In this example, I will show how the addition function and the filter function implemented previously using the other approaches can be implemented using ctypes. First, the C-code which implements the algorithms contains the functions zadd, dadd, sadd, cadd, and dfilter2d. The zadd function is:

/* Add arrays of contiguous data */
typedef struct {double real; double imag;} cdouble;
typedef struct {float real; float imag;} cfloat;
void zadd(cdouble *a, cdouble *b, cdouble *c, long n)
{
    while (n--) {
        c->real = a->real + b->real;
        c->imag = a->imag + b->imag;
        a++; b++; c++;
    }
}

with similar code for cadd, dadd, and sadd that handles complex float, double, and float data-types, respectively:

void cadd(cfloat *a, cfloat *b, cfloat *c, long n)
{
        while (n--) {
                c->real = a->real + b->real;
                c->imag = a->imag + b->imag;
                a++; b++; c++;
        }
}
void dadd(double *a, double *b, double *c, long n)
{
        while (n--) {
                *c++ = *a++ + *b++;
        }
}
void sadd(float *a, float *b, float *c, long n)
{
        while (n--) {
                *c++ = *a++ + *b++;
        }
}

The code.c file also contains the function dfilter2d:

/* Assumes b is contiguous and
   a has strides that are multiples of sizeof(double)
*/
void
dfilter2d(double *a, double *b, int *astrides, int *dims)
{
    int i, j, M, N, S0, S1;
    int r, c, rm1, rp1, cp1, cm1;

    M = dims[0]; N = dims[1];
    S0 = astrides[0]/sizeof(double);
    S1=astrides[1]/sizeof(double);
    for (i=1; i<M-1; i++) {
        r = i*S0; rp1 = r+S0; rm1 = r-S0;
        for (j=1; j<N-1; j++) {
            c = j*S1; cp1 = j+S1; cm1 = j-S1;
            b[i*N+j] = a[r+c] +                 \
                (a[rp1+c] + a[rm1+c] +          \
                 a[r+cp1] + a[r+cm1])*0.5 +     \
                (a[rp1+cp1] + a[rp1+cm1] +      \
                 a[rm1+cp1] + a[rm1+cp1])*0.25;
        }
    }
}

A possible advantage this code has over the Fortran-equivalent code is that it takes arbitrarily strided (i.e. non-contiguous arrays) and may also run faster depending on the optimization capability of your compiler. But, it is a obviously more complicated than the simple code in filter.f. This code must be compiled into a shared library. On my Linux system this is accomplished using:

gcc -o code.so -shared code.c

Which creates a shared_library named code.so in the current directory. On Windows don’t forget to either add __declspec(dllexport) in front of void on the line preceeding each function definition, or write a code.def file that lists the names of the functions to be exported.

A suitable Python interface to this shared library should be constructed. To do this create a file named interface.py with the following lines at the top:

__all__ = ['add', 'filter2d']

import numpy as N
import os

_path = os.path.dirname('__file__')
lib = N.ctypeslib.load_library('code', _path)
_typedict = {'zadd' : complex, 'sadd' : N.single,
             'cadd' : N.csingle, 'dadd' : float}
for name in _typedict.keys():
    val = getattr(lib, name)
    val.restype = None
    _type = _typedict[name]
    val.argtypes = [N.ctypeslib.ndpointer(_type,
                      flags='aligned, contiguous'),
                    N.ctypeslib.ndpointer(_type,
                      flags='aligned, contiguous'),
                    N.ctypeslib.ndpointer(_type,
                      flags='aligned, contiguous,'\
                            'writeable'),
                    N.ctypeslib.c_intp]

This code loads the shared library named code.{ext} located in the same path as this file. It then adds a return type of void to the functions contained in the library. It also adds argument checking to the functions in the library so that ndarrays can be passed as the first three arguments along with an integer (large enough to hold a pointer on the platform) as the fourth argument.

Setting up the filtering function is similar and allows the filtering function to be called with ndarray arguments as the first two arguments and with pointers to integers (large enough to handle the strides and shape of an ndarray) as the last two arguments.:

lib.dfilter2d.restype=None
lib.dfilter2d.argtypes = [N.ctypeslib.ndpointer(float, ndim=2,
                                       flags='aligned'),
                          N.ctypeslib.ndpointer(float, ndim=2,
                                 flags='aligned, contiguous,'\
                                       'writeable'),
                          ctypes.POINTER(N.ctypeslib.c_intp),
                          ctypes.POINTER(N.ctypeslib.c_intp)]

Next, define a simple selection function that chooses which addition function to call in the shared library based on the data-type:

def select(dtype):
    if dtype.char in ['?bBhHf']:
        return lib.sadd, single
    elif dtype.char in ['F']:
        return lib.cadd, csingle
    elif dtype.char in ['DG']:
        return lib.zadd, complex
    else:
        return lib.dadd, float
    return func, ntype

Finally, the two functions to be exported by the interface can be written simply as:

def add(a, b):
    requires = ['CONTIGUOUS', 'ALIGNED']
    a = N.asanyarray(a)
    func, dtype = select(a.dtype)
    a = N.require(a, dtype, requires)
    b = N.require(b, dtype, requires)
    c = N.empty_like(a)
    func(a,b,c,a.size)
    return c

and:

def filter2d(a):
    a = N.require(a, float, ['ALIGNED'])
    b = N.zeros_like(a)
    lib.dfilter2d(a, b, a.ctypes.strides, a.ctypes.shape)
    return b

Conclusion

Using ctypes is a powerful way to connect Python with arbitrary C-code. It’s advantages for extending Python include

  • clean separation of C-code from Python code

    • no need to learn a new syntax except Python and C
    • allows re-use of C-code
    • functionality in shared libraries written for other purposes can be obtained with a simple Python wrapper and search for the library.

  • easy integration with NumPy through the ctypes attribute

  • full argument checking with the ndpointer class factory

It’s disadvantages include

  • It is difficult to distribute an extension module made using ctypes because of a lack of support for building shared libraries in distutils (but I suspect this will change in time).
  • You must have shared-libraries of your code (no static libraries).
  • Very little support for C++ code and it’s different library-calling conventions. You will probably need a C-wrapper around C++ code to use with ctypes (or just use Boost.Python instead).

Because of the difficulty in distributing an extension module made using ctypes, f2py is still the easiest way to extend Python for package creation. However, ctypes is a close second and will probably be growing in popularity now that it is part of the Python distribution. This should bring more features to ctypes that should eliminate the difficulty in extending Python and distributing the extension using ctypes.

Additional tools you may find useful

These tools have been found useful by others using Python and so are included here. They are discussed separately because they are either older ways to do things now handled by f2py, Cython, or ctypes (SWIG, PyFort) or because I don’t know much about them (SIP, Boost). I have not added links to these methods because my experience is that you can find the most relevant link faster using Google or some other search engine, and any links provided here would be quickly dated. Do not assume that just because it is included in this list, I don’t think the package deserves your attention. I’m including information about these packages because many people have found them useful and I’d like to give you as many options as possible for tackling the problem of easily integrating your code.

SWIG

Simplified Wrapper and Interface Generator (SWIG) is an old and fairly stable method for wrapping C/C++-libraries to a large variety of other languages. It does not specifically understand NumPy arrays but can be made useable with NumPy through the use of typemaps. There are some sample typemaps in the numpy/tools/swig directory under numpy.i together with an example module that makes use of them. SWIG excels at wrapping large C/C++ libraries because it can (almost) parse their headers and auto-produce an interface. Technically, you need to generate a .i file that defines the interface. Often, however, this .i file can be parts of the header itself. The interface usually needs a bit of tweaking to be very useful. This ability to parse C/C++ headers and auto-generate the interface still makes SWIG a useful approach to adding functionalilty from C/C++ into Python, despite the other methods that have emerged that are more targeted to Python. SWIG can actually target extensions for several languages, but the typemaps usually have to be language-specific. Nonetheless, with modifications to the Python-specific typemaps, SWIG can be used to interface a library with other languages such as Perl, Tcl, and Ruby.

My experience with SWIG has been generally positive in that it is relatively easy to use and quite powerful. I used to use it quite often before becoming more proficient at writing C-extensions. However, I struggled writing custom interfaces with SWIG because it must be done using the concept of typemaps which are not Python specific and are written in a C-like syntax. Therefore, I tend to prefer other gluing strategies and would only attempt to use SWIG to wrap a very-large C/C++ library. Nonetheless, there are others who use SWIG quite happily.

SIP

SIP is another tool for wrapping C/C++ libraries that is Python specific and appears to have very good support for C++. Riverbank Computing developed SIP in order to create Python bindings to the QT library. An interface file must be written to generate the binding, but the interface file looks a lot like a C/C++ header file. While SIP is not a full C++ parser, it understands quite a bit of C++ syntax as well as its own special directives that allow modification of how the Python binding is accomplished. It also allows the user to define mappings between Python types and C/C++ structrues and classes.

Boost Python

Boost is a repository of C++ libraries and Boost.Python is one of those libraries which provides a concise interface for binding C++ classes and functions to Python. The amazing part of the Boost.Python approach is that it works entirely in pure C++ without introducing a new syntax. Many users of C++ report that Boost.Python makes it possible to combine the best of both worlds in a seamless fashion. I have not used Boost.Python because I am not a big user of C++ and using Boost to wrap simple C-subroutines is usually over-kill. It’s primary purpose is to make C++ classes available in Python. So, if you have a set of C++ classes that need to be integrated cleanly into Python, consider learning about and using Boost.Python.

PyFort

PyFort is a nice tool for wrapping Fortran and Fortran-like C-code into Python with support for Numeric arrays. It was written by Paul Dubois, a distinguished computer scientist and the very first maintainer of Numeric (now retired). It is worth mentioning in the hopes that somebody will update PyFort to work with NumPy arrays as well which now support either Fortran or C-style contiguous arrays.


Writing your own ufunc

  • NumPy User Guide
  • Using Numpy C-API
  • index
  • next
  • previous

Table Of Contents

  • Writing your own ufunc
    • Creating a new universal function
    • Example Non-ufunc extension
    • Example Numpy ufunc for one dtype
    • Example Numpy ufunc with multiple dtypes
    • Example Numpy ufunc with multiple arguments/return values
    • Example Numpy ufunc with structured array dtype arguments
    • PyUFunc_FromFuncAndData Specification

Previous topic

Using Python as glue

Next topic

Beyond the Basics

Writing your own ufunc

I have the Power!
— He-Man

Creating a new universal function

Before reading this, it may help to familiarize yourself with the basics of C extensions for Python by reading/skimming the tutorials in Section 1 of Extending and Embedding the Python Interpreter and in How to extend Numpy

The umath module is a computer-generated C-module that creates many ufuncs. It provides a great many examples of how to create a universal function. Creating your own ufunc that will make use of the ufunc machinery is not difficult either. Suppose you have a function that you want to operate element-by-element over its inputs. By creating a new ufunc you will obtain a function that handles

  • broadcasting
  • N-dimensional looping
  • automatic type-conversions with minimal memory usage
  • optional output arrays

It is not difficult to create your own ufunc. All that is required is a 1-d loop for each data-type you want to support. Each 1-d loop must have a specific signature, and only ufuncs for fixed-size data-types can be used. The function call used to create a new ufunc to work on built-in data-types is given below. A different mechanism is used to register ufuncs for user-defined data-types.

In the next several sections we give example code that can be easily modified to create your own ufuncs. The examples are successively more complete or complicated versions of the logit function, a common function in statistical modeling. Logit is also interesting because, due to the magic of IEEE standards (specifically IEEE 754), all of the logit functions created below automatically have the following behavior.

>>> logit(0)
-inf
>>> logit(1)
inf
>>> logit(2)
nan
>>> logit(-2)
nan

This is wonderful because the function writer doesn’t have to manually propagate infs or nans.

Example Non-ufunc extension

For comparison and general edificaiton of the reader we provide a simple implementation of a C extension of logit that uses no numpy.

To do this we need two files. The first is the C file which contains the actual code, and the second is the setup.py file used to create the module.

#include <Python.h>
#include <math.h>

/*
 * spammodule.c
 * This is the C code for a non-numpy Python extension to
 * define the logit function, where logit(p) = log(p/(1-p)).
 * This function will not work on numpy arrays automatically.
 * numpy.vectorize must be called in python to generate
 * a numpy-friendly function.
 *
 * Details explaining the Python-C API can be found under
 * 'Extending and Embedding' and 'Python/C API' at
 * docs.python.org .
 */

/* This declares the logit function */
static PyObject* spam_logit(PyObject *self, PyObject *args);

/*
 * This tells Python what methods this module has.
 * See the Python-C API for more information.
 */
static PyMethodDef SpamMethods[] = {
    {"logit",
        spam_logit,
        METH_VARARGS, "compute logit"},
    {NULL, NULL, 0, NULL}
};

/*
 * This actually defines the logit function for
 * input args from Python.
 */

static PyObject* spam_logit(PyObject *self, PyObject *args)
{
    double p;

    /* This parses the Python argument into a double */
    if(!PyArg_ParseTuple(args, "d", &p)) {
        return NULL;
    }

    /* THE ACTUAL LOGIT FUNCTION */
    p = p/(1-p);
    p = log(p);

    /*This builds the answer back into a python object */
    return Py_BuildValue("d", p);
}

/* This initiates the module using the above definitions. */
#if PY_VERSION_HEX >= 0x03000000
static struct PyModuleDef moduledef = {
    PyModuleDef_HEAD_INIT,
    "spam",
    NULL,
    -1,
    SpamMethods,
    NULL,
    NULL,
    NULL,
    NULL
};

PyMODINIT_FUNC PyInit_spam(void)
{
    PyObject *m;
    m = PyModule_Create(&moduledef);
    if (!m) {
        return NULL;
    }
    return m;
}
#else
PyMODINIT_FUNC initspam(void)
{
    PyObject *m;

    m = Py_InitModule("spam", SpamMethods);
    if (m == NULL) {
        return;
    }
}
#endif

To use the setup.py file, place setup.py and spammodule.c in the same folder. Then python setup.py build will build the module to import, or setup.py install will install the module to your site-packages directory.

'''
    setup.py file for spammodule.c

    Calling
    $python setup.py build_ext --inplace
    will build the extension library in the current file.

    Calling
    $python setup.py build
    will build a file that looks like ./build/lib*, where
    lib* is a file that begins with lib. The library will
    be in this file and end with a C library extension,
    such as .so

    Calling
    $python setup.py install
    will install the module in your site-packages file.

    See the distutils section of
    'Extending and Embedding the Python Interpreter'
    at docs.python.org for more information.
'''

from distutils.core import setup, Extension

module1 = Extension('spam', sources=['spammodule.c'],
                        include_dirs=['/usr/local/lib'])

setup(name = 'spam',
        version='1.0',
        description='This is my spam package',
        ext_modules = [module1])

Once the spam module is imported into python, you can call logit via spam.logit. Note that the function used above cannot be applied as-is to numpy arrays. To do so we must call numpy.vectorize on it. For example, if a python interpreter is opened in the file containing the spam library or spam has been installed, one can perform the following commands:

>>> import numpy as np
>>> import spam
>>> spam.logit(0)
-inf
>>> spam.logit(1)
inf
>>> spam.logit(0.5)
0.0
>>> x = np.linspace(0,1,10)
>>> spam.logit(x)
TypeError: only length-1 arrays can be converted to Python scalars
>>> f = np.vectorize(spam.logit)
>>> f(x)
array([       -inf, -2.07944154, -1.25276297, -0.69314718, -0.22314355,
    0.22314355,  0.69314718,  1.25276297,  2.07944154,         inf])

THE RESULTING LOGIT FUNCTION IS NOT FAST! numpy.vectorize simply loops over spam.logit. The loop is done at the C level, but the numpy array is constantly being parsed and build back up. This is expensive. When the author compared numpy.vectorize(spam.logit) against the logit ufuncs constructed below, the logit ufuncs were almost exactly 4 times faster. Larger or smaller speedups are, of course, possible depending on the nature of the function.

Example Numpy ufunc for one dtype

For simplicity we give a ufunc for a single dtype, the ‘f8’ double. As in the previous section, we first give the .c file and then the setup.py file used to create the module containing the ufunc.

The place in the code corresponding to the actual computations for the ufunc are marked with /*BEGIN main ufunc computation*/ and /*END main ufunc computation*/. The code in between those lines is the primary thing that must be changed to create your own ufunc.

#include "Python.h"
#include "math.h"
#include "numpy/ndarraytypes.h"
#include "numpy/ufuncobject.h"
#include "numpy/npy_3kcompat.h"

/*
 * single_type_logit.c
 * This is the C code for creating your own
 * Numpy ufunc for a logit function.
 *
 * In this code we only define the ufunc for
 * a single dtype. The computations that must
 * be replaced to create a ufunc for
 * a different funciton are marked with BEGIN
 * and END.
 *
 * Details explaining the Python-C API can be found under
 * 'Extending and Embedding' and 'Python/C API' at
 * docs.python.org .
 */

static PyMethodDef LogitMethods[] = {
        {NULL, NULL, 0, NULL}
};

/* The loop definition must precede the PyMODINIT_FUNC. */

static void double_logit(char **args, npy_intp *dimensions,
                            npy_intp* steps, void* data)
{
    npy_intp i;
    npy_intp n = dimensions[0];
    char *in = args[0], *out = args[1];
    npy_intp in_step = steps[0], out_step = steps[1];

    double tmp;

    for (i = 0; i < n; i++) {
        /*BEGIN main ufunc computation*/
        tmp = *(double *)in;
        tmp /= 1-tmp;
        *((double *)out) = log(tmp);
        /*END main ufunc computation*/

        in += in_step;
        out += out_step;
    }
}

/*This a pointer to the above function*/
PyUFuncGenericFunction funcs[1] = {&double_logit};

/* These are the input and return dtypes of logit.*/
static char types[2] = {NPY_DOUBLE, NPY_DOUBLE};

static void *data[1] = {NULL};

#if PY_VERSION_HEX >= 0x03000000
static struct PyModuleDef moduledef = {
    PyModuleDef_HEAD_INIT,
    "npufunc",
    NULL,
    -1,
    LogitMethods,
    NULL,
    NULL,
    NULL,
    NULL
};

PyMODINIT_FUNC PyInit_npufunc(void)
{
    PyObject *m, *logit, *d;
    m = PyModule_Create(&moduledef);
    if (!m) {
        return NULL;
    }

    import_array();
    import_umath();

    logit = PyUFunc_FromFuncAndData(funcs, data, types, 1, 1, 1,
                                    PyUFunc_None, "logit",
                                    "logit_docstring", 0);

    d = PyModule_GetDict(m);

    PyDict_SetItemString(d, "logit", logit);
    Py_DECREF(logit);

    return m;
}
#else
PyMODINIT_FUNC initnpufunc(void)
{
    PyObject *m, *logit, *d;

    m = Py_InitModule("npufunc", LogitMethods);
    if (m == NULL) {
        return;
    }

    import_array();
    import_umath();

    logit = PyUFunc_FromFuncAndData(funcs, data, types, 1, 1, 1,
                                    PyUFunc_None, "logit",
                                    "logit_docstring", 0);

    d = PyModule_GetDict(m);

    PyDict_SetItemString(d, "logit", logit);
    Py_DECREF(logit);
}
#endif

This is a setup.py file for the above code. As before, the module can be build via calling python setup.py build at the command prompt, or installed to site-packages via python setup.py install.

'''
    setup.py file for logit.c
    Note that since this is a numpy extension
    we use numpy.distutils instead of
    distutils from the python standard library.

    Calling
    $python setup.py build_ext --inplace
    will build the extension library in the current file.

    Calling
    $python setup.py build
    will build a file that looks like ./build/lib*, where
    lib* is a file that begins with lib. The library will
    be in this file and end with a C library extension,
    such as .so

    Calling
    $python setup.py install
    will install the module in your site-packages file.

    See the distutils section of
    'Extending and Embedding the Python Interpreter'
    at docs.python.org  and the documentation
    on numpy.distutils for more information.
'''

def configuration(parent_package='', top_path=None):
    import numpy
    from numpy.distutils.misc_util import Configuration

    config = Configuration('npufunc_directory',
                           parent_package,
                           top_path)
    config.add_extension('npufunc', ['single_type_logit.c'])

    return config

if __name__ == "__main__":
    from numpy.distutils.core import setup
    setup(configuration=configuration)

After the above has been installed, it can be imported and used as follows.

>>> import numpy as np
>>> import npufunc
>>> npufunc.logit(0.5)
0.0
>>> a = np.linspace(0,1,5)
>>> npufunc.logit(a)
array([       -inf, -1.09861229,  0.        ,  1.09861229,         inf])

Example Numpy ufunc with multiple dtypes

We finally give an example of a full ufunc, with inner loops for half-floats, floats, doubles, and long doubles. As in the previous sections we first give the .c file and then the corresponding setup.py file.

The places in the code corresponding to the actual computations for the ufunc are marked with /*BEGIN main ufunc computation*/ and /*END main ufunc computation*/. The code in between those lines is the primary thing that must be changed to create your own ufunc.

#include "Python.h"
#include "math.h"
#include "numpy/ndarraytypes.h"
#include "numpy/ufuncobject.h"
#include "numpy/halffloat.h"

/*
 * multi_type_logit.c
 * This is the C code for creating your own
 * Numpy ufunc for a logit function.
 *
 * Each function of the form type_logit defines the
 * logit function for a different numpy dtype. Each
 * of these functions must be modified when you
 * create your own ufunc. The computations that must
 * be replaced to create a ufunc for
 * a different funciton are marked with BEGIN
 * and END.
 *
 * Details explaining the Python-C API can be found under
 * 'Extending and Embedding' and 'Python/C API' at
 * docs.python.org .
 *
 */

static PyMethodDef LogitMethods[] = {
        {NULL, NULL, 0, NULL}
};

/* The loop definitions must precede the PyMODINIT_FUNC. */

static void long_double_logit(char **args, npy_intp *dimensions,
                              npy_intp* steps, void* data)
{
    npy_intp i;
    npy_intp n = dimensions[0];
    char *in = args[0], *out=args[1];
    npy_intp in_step = steps[0], out_step = steps[1];

    long double tmp;

    for (i = 0; i < n; i++) {
        /*BEGIN main ufunc computation*/
        tmp = *(long double *)in;
        tmp /= 1-tmp;
        *((long double *)out) = logl(tmp);
        /*END main ufunc computation*/

        in += in_step;
        out += out_step;
    }
}

static void double_logit(char **args, npy_intp *dimensions,
                         npy_intp* steps, void* data)
{
    npy_intp i;
    npy_intp n = dimensions[0];
    char *in = args[0], *out = args[1];
    npy_intp in_step = steps[0], out_step = steps[1];

    double tmp;

    for (i = 0; i < n; i++) {
        /*BEGIN main ufunc computation*/
        tmp = *(double *)in;
        tmp /= 1-tmp;
        *((double *)out) = log(tmp);
        /*END main ufunc computation*/

        in += in_step;
        out += out_step;
    }
}

static void float_logit(char **args, npy_intp *dimensions,
                        npy_intp* steps, void* data)
{
    npy_intp i;
    npy_intp n = dimensions[0];
    char *in=args[0], *out = args[1];
    npy_intp in_step = steps[0], out_step = steps[1];

    float tmp;

    for (i = 0; i < n; i++) {
        /*BEGIN main ufunc computation*/
        tmp = *(float *)in;
        tmp /= 1-tmp;
        *((float *)out) = logf(tmp);
        /*END main ufunc computation*/

        in += in_step;
        out += out_step;
    }
}

static void half_float_logit(char **args, npy_intp *dimensions,
                             npy_intp* steps, void* data)
{
    npy_intp i;
    npy_intp n = dimensions[0];
    char *in = args[0], *out = args[1];
    npy_intp in_step = steps[0], out_step = steps[1];

    float tmp;

    for (i = 0; i < n; i++) {

        /*BEGIN main ufunc computation*/
        tmp = *(npy_half *)in;
        tmp = npy_half_to_float(tmp);
        tmp /= 1-tmp;
        tmp = logf(tmp);
        *((npy_half *)out) = npy_float_to_half(tmp);
        /*END main ufunc computation*/

        in += in_step;
        out += out_step;
    }
}

/*This gives pointers to the above functions*/
PyUFuncGenericFunction funcs[4] = {&half_float_logit,
                                   &float_logit,
                                   &double_logit,
                                   &long_double_logit};

static char types[8] = {NPY_HALF, NPY_HALF,
                NPY_FLOAT, NPY_FLOAT,
                NPY_DOUBLE,NPY_DOUBLE,
                NPY_LONGDOUBLE, NPY_LONGDOUBLE};
static void *data[4] = {NULL, NULL, NULL, NULL};

#if PY_VERSION_HEX >= 0x03000000
static struct PyModuleDef moduledef = {
    PyModuleDef_HEAD_INIT,
    "npufunc",
    NULL,
    -1,
    LogitMethods,
    NULL,
    NULL,
    NULL,
    NULL
};

PyMODINIT_FUNC PyInit_npufunc(void)
{
    PyObject *m, *logit, *d;
    m = PyModule_Create(&moduledef);
    if (!m) {
        return NULL;
    }

    import_array();
    import_umath();

    logit = PyUFunc_FromFuncAndData(funcs, data, types, 4, 1, 1,
                                    PyUFunc_None, "logit",
                                    "logit_docstring", 0);

    d = PyModule_GetDict(m);

    PyDict_SetItemString(d, "logit", logit);
    Py_DECREF(logit);

    return m;
}
#else
PyMODINIT_FUNC initnpufunc(void)
{
    PyObject *m, *logit, *d;

    m = Py_InitModule("npufunc", LogitMethods);
    if (m == NULL) {
        return;
    }

    import_array();
    import_umath();

    logit = PyUFunc_FromFuncAndData(funcs, data, types, 4, 1, 1,
                                    PyUFunc_None, "logit",
                                    "logit_docstring", 0);

    d = PyModule_GetDict(m);

    PyDict_SetItemString(d, "logit", logit);
    Py_DECREF(logit);
}
#endif

This is a setup.py file for the above code. As before, the module can be build via calling python setup.py build at the command prompt, or installed to site-packages via python setup.py install.

'''
    setup.py file for logit.c
    Note that since this is a numpy extension
    we use numpy.distutils instead of
    distutils from the python standard library.

    Calling
    $python setup.py build_ext --inplace
    will build the extension library in the current file.

    Calling
    $python setup.py build
    will build a file that looks like ./build/lib*, where
    lib* is a file that begins with lib. The library will
    be in this file and end with a C library extension,
    such as .so

    Calling
    $python setup.py install
    will install the module in your site-packages file.

    See the distutils section of
    'Extending and Embedding the Python Interpreter'
    at docs.python.org  and the documentation
    on numpy.distutils for more information.
'''

def configuration(parent_package='', top_path=None):
    import numpy
    from numpy.distutils.misc_util import Configuration
    from numpy.distutils.misc_util import get_info

    #Necessary for the half-float d-type.
    info = get_info('npymath')

    config = Configuration('npufunc_directory',
                            parent_package,
                            top_path)
    config.add_extension('npufunc',
                            ['multi_type_logit.c'],
                            extra_info=info)

    return config

if __name__ == "__main__":
    from numpy.distutils.core import setup
    setup(configuration=configuration)

After the above has been installed, it can be imported and used as follows.

>>> import numpy as np
>>> import npufunc
>>> npufunc.logit(0.5)
0.0
>>> a = np.linspace(0,1,5)
>>> npufunc.logit(a)
array([       -inf, -1.09861229,  0.        ,  1.09861229,         inf])

Example Numpy ufunc with multiple arguments/return values

Our final example is a ufunc with multiple arguments. It is a modification of the code for a logit ufunc for data with a single dtype. We compute (A*B, logit(A*B)).

We only give the C code as the setup.py file is exactly the same as the setup.py file in Example Numpy ufunc for one dtype, except that the line

config.add_extension('npufunc', ['single_type_logit.c'])

is replaced with

config.add_extension('npufunc', ['multi_arg_logit.c'])

The C file is given below. The ufunc generated takes two arguments A and B. It returns a tuple whose first element is A*B and whose second element is logit(A*B). Note that it automatically supports broadcasting, as well as all other properties of a ufunc.

#include "Python.h"
#include "math.h"
#include "numpy/ndarraytypes.h"
#include "numpy/ufuncobject.h"
#include "numpy/halffloat.h"

/*
 * multi_arg_logit.c
 * This is the C code for creating your own
 * Numpy ufunc for a multiple argument, multiple
 * return value ufunc. The places where the
 * ufunc computation is carried out are marked
 * with comments.
 *
 * Details explaining the Python-C API can be found under
 * 'Extending and Embedding' and 'Python/C API' at
 * docs.python.org .
 *
 */

static PyMethodDef LogitMethods[] = {
        {NULL, NULL, 0, NULL}
};

/* The loop definition must precede the PyMODINIT_FUNC. */

static void double_logitprod(char **args, npy_intp *dimensions,
                            npy_intp* steps, void* data)
{
    npy_intp i;
    npy_intp n = dimensions[0];
    char *in1 = args[0], *in2 = args[1];
    char *out1 = args[2], *out2 = args[3];
    npy_intp in1_step = steps[0], in2_step = steps[1];
    npy_intp out1_step = steps[2], out2_step = steps[3];

    double tmp;

    for (i = 0; i < n; i++) {
        /*BEGIN main ufunc computation*/
        tmp = *(double *)in1;
        tmp *= *(double *)in2;
        *((double *)out1) = tmp;
        *((double *)out2) = log(tmp/(1-tmp));
        /*END main ufunc computation*/

        in1 += in1_step;
        in2 += in2_step;
        out1 += out1_step;
        out2 += out2_step;
    }
}

/*This a pointer to the above function*/
PyUFuncGenericFunction funcs[1] = {&double_logitprod};

/* These are the input and return dtypes of logit.*/

static char types[4] = {NPY_DOUBLE, NPY_DOUBLE,
                        NPY_DOUBLE, NPY_DOUBLE};

static void *data[1] = {NULL};

#if PY_VERSION_HEX >= 0x03000000
static struct PyModuleDef moduledef = {
    PyModuleDef_HEAD_INIT,
    "npufunc",
    NULL,
    -1,
    LogitMethods,
    NULL,
    NULL,
    NULL,
    NULL
};

PyMODINIT_FUNC PyInit_npufunc(void)
{
    PyObject *m, *logit, *d;
    m = PyModule_Create(&moduledef);
    if (!m) {
        return NULL;
    }

    import_array();
    import_umath();

    logit = PyUFunc_FromFuncAndData(funcs, data, types, 1, 2, 2,
                                    PyUFunc_None, "logit",
                                    "logit_docstring", 0);

    d = PyModule_GetDict(m);

    PyDict_SetItemString(d, "logit", logit);
    Py_DECREF(logit);

    return m;
}
#else
PyMODINIT_FUNC initnpufunc(void)
{
    PyObject *m, *logit, *d;

    m = Py_InitModule("npufunc", LogitMethods);
    if (m == NULL) {
        return;
    }

    import_array();
    import_umath();

    logit = PyUFunc_FromFuncAndData(funcs, data, types, 1, 2, 2,
                                    PyUFunc_None, "logit",
                                    "logit_docstring", 0);

    d = PyModule_GetDict(m);

    PyDict_SetItemString(d, "logit", logit);
    Py_DECREF(logit);
}
#endif

Example Numpy ufunc with structured array dtype arguments

This example shows how to create a ufunc for a structured array dtype. For the example we show a trivial ufunc for adding two arrays with dtype ‘u8,u8,u8’. The process is a bit different from the other examples since a call to PyUFunc_FromFuncAndData doesn’t fully register ufuncs for custom dtypes and structured array dtypes. We need to also call PyUFunc_RegisterLoopForDescr to finish setting up the ufunc.

We only give the C code as the setup.py file is exactly the same as the setup.py file in Example Numpy ufunc for one dtype, except that the line

config.add_extension('npufunc', ['single_type_logit.c'])

is replaced with

config.add_extension('npufunc', ['add_triplet.c'])

The C file is given below.

#include "Python.h"
#include "math.h"
#include "numpy/ndarraytypes.h"
#include "numpy/ufuncobject.h"
#include "numpy/npy_3kcompat.h"

/*
 * add_triplet.c
 * This is the C code for creating your own
 * Numpy ufunc for a structured array dtype.
 *
 * Details explaining the Python-C API can be found under
 * 'Extending and Embedding' and 'Python/C API' at
 * docs.python.org .
 */

static PyMethodDef StructUfuncTestMethods[] = {
    {NULL, NULL, 0, NULL}
};

/* The loop definition must precede the PyMODINIT_FUNC. */

static void add_uint64_triplet(char **args, npy_intp *dimensions,
                            npy_intp* steps, void* data)
{
    npy_intp i;
    npy_intp is1=steps[0];
    npy_intp is2=steps[1];
    npy_intp os=steps[2];
    npy_intp n=dimensions[0];
    uint64_t *x, *y, *z;

    char *i1=args[0];
    char *i2=args[1];
    char *op=args[2];

    for (i = 0; i < n; i++) {

        x = (uint64_t*)i1;
        y = (uint64_t*)i2;
        z = (uint64_t*)op;

        z[0] = x[0] + y[0];
        z[1] = x[1] + y[1];
        z[2] = x[2] + y[2];

        i1 += is1;
        i2 += is2;
        op += os;
    }
}

/* This a pointer to the above function */
PyUFuncGenericFunction funcs[1] = {&add_uint64_triplet};

/* These are the input and return dtypes of add_uint64_triplet. */
static char types[3] = {NPY_UINT64, NPY_UINT64, NPY_UINT64};

static void *data[1] = {NULL};

#if defined(NPY_PY3K)
static struct PyModuleDef moduledef = {
    PyModuleDef_HEAD_INIT,
    "struct_ufunc_test",
    NULL,
    -1,
    StructUfuncTestMethods,
    NULL,
    NULL,
    NULL,
    NULL
};
#endif

#if defined(NPY_PY3K)
PyMODINIT_FUNC PyInit_struct_ufunc_test(void)
#else
PyMODINIT_FUNC initstruct_ufunc_test(void)
#endif
{
    PyObject *m, *add_triplet, *d;
    PyObject *dtype_dict;
    PyArray_Descr *dtype;
    PyArray_Descr *dtypes[3];

#if defined(NPY_PY3K)
    m = PyModule_Create(&moduledef);
#else
    m = Py_InitModule("struct_ufunc_test", StructUfuncTestMethods);
#endif

    if (m == NULL) {
#if defined(NPY_PY3K)
        return NULL;
#else
        return;
#endif
    }

    import_array();
    import_umath();

    /* Create a new ufunc object */
    add_triplet = PyUFunc_FromFuncAndData(NULL, NULL, NULL, 0, 2, 1,
                                    PyUFunc_None, "add_triplet",
                                    "add_triplet_docstring", 0);

    dtype_dict = Py_BuildValue("[(s, s), (s, s), (s, s)]",
        "f0", "u8", "f1", "u8", "f2", "u8");
    PyArray_DescrConverter(dtype_dict, &dtype);
    Py_DECREF(dtype_dict);

    dtypes[0] = dtype;
    dtypes[1] = dtype;
    dtypes[2] = dtype;

    /* Register ufunc for structured dtype */
    PyUFunc_RegisterLoopForDescr(add_triplet,
                                dtype,
                                &add_uint64_triplet,
                                dtypes,
                                NULL);

    d = PyModule_GetDict(m);

    PyDict_SetItemString(d, "add_triplet", add_triplet);
    Py_DECREF(add_triplet);
#if defined(NPY_PY3K)
    return m;
#endif
}

PyUFunc_FromFuncAndData Specification

What follows is the full specification of PyUFunc_FromFuncAndData, which automatically generates a ufunc from a C function with the correct signature.

PyObject *PyUFunc_FromFuncAndData( PyUFuncGenericFunction* func,
void** data, char* types, int ntypes, int nin, int nout, int identity,
char* name, char* doc, int check_return)

func

A pointer to an array of 1-d functions to use. This array must be at least ntypes long. Each entry in the array must be a PyUFuncGenericFunction function. This function has the following signature. An example of a valid 1d loop function is also given.

void loop1d(char** args, npy_intp* dimensions,
npy_intp* steps, void* data)

args

An array of pointers to the actual data for the input and output arrays. The input arguments are given first followed by the output arguments.

dimensions

A pointer to the size of the dimension over which this function is looping.

steps

A pointer to the number of bytes to jump to get to the next element in this dimension for each of the input and output arguments.

data

Arbitrary data (extra arguments, function names, etc. ) that can be stored with the ufunc and will be passed in when it is called.
static void
double_add(char *args, npy_intp *dimensions, npy_intp *steps,
   void *extra)
{
    npy_intp i;
    npy_intp is1 = steps[0], is2 = steps[1];
    npy_intp os = steps[2], n = dimensions[0];
    char *i1 = args[0], *i2 = args[1], *op = args[2];
    for (i = 0; i < n; i++) {
        *((double *)op) = *((double *)i1) +
                          *((double *)i2);
        i1 += is1;
        i2 += is2;
        op += os;
     }
}

data

An array of data. There should be ntypes entries (or NULL) — one for every loop function defined for this ufunc. This data will be passed in to the 1-d loop. One common use of this data variable is to pass in an actual function to call to compute the result when a generic 1-d loop (e.g. PyUFunc_d_d) is being used.

types

An array of type-number signatures (type char ). This array should be of size (nin+nout)*ntypes and contain the data-types for the corresponding 1-d loop. The inputs should be first followed by the outputs. For example, suppose I have a ufunc that supports 1 integer and 1 double 1-d loop (length-2 func and data arrays) that takes 2 inputs and returns 1 output that is always a complex double, then the types array would be

static char types[3] = {NPY_INT, NPY_DOUBLE, NPY_CDOUBLE}

The bit-width names can also be used (e.g. NPY_INT32, NPY_COMPLEX128 ) if desired.

ntypes

The number of data-types supported. This is equal to the number of 1-d loops provided.

nin

The number of input arguments.

nout

The number of output arguments.

identity

Either PyUFunc_One, PyUFunc_Zero, PyUFunc_None. This specifies what should be returned when an empty array is passed to the reduce method of the ufunc.

name

A NULL -terminated string providing the name of this ufunc (should be the Python name it will be called).

doc

A documentation string for this ufunc (will be used in generating the response to {ufunc_name}.__doc__). Do not include the function signature or the name as this is generated automatically.

check_return

Not presently used, but this integer value does get set in the structure-member of similar name.

The returned ufunc object is a callable Python object. It should be placed in a (module) dictionary under the same name as was used in the name argument to the ufunc-creation routine. The following example is adapted from the umath module

static PyUFuncGenericFunction atan2_functions[] = {
                      PyUFunc_ff_f, PyUFunc_dd_d,
                      PyUFunc_gg_g, PyUFunc_OO_O_method};
static void* atan2_data[] = {
                      (void *)atan2f,(void *) atan2,
                      (void *)atan2l,(void *)"arctan2"};
static char atan2_signatures[] = {
              NPY_FLOAT, NPY_FLOAT, NPY_FLOAT,
              NPY_DOUBLE, NPY_DOUBLE, NPY_DOUBLE,
              NPY_LONGDOUBLE, NPY_LONGDOUBLE, NPY_LONGDOUBLE
              NPY_OBJECT, NPY_OBJECT, NPY_OBJECT};
...
/* in the module initialization code */
PyObject *f, *dict, *module;
...
dict = PyModule_GetDict(module);
...
f = PyUFunc_FromFuncAndData(atan2_functions,
    atan2_data, atan2_signatures, 4, 2, 1,
    PyUFunc_None, "arctan2",
    "a safe and correct arctan(x1/x2)", 0);
PyDict_SetItemString(dict, "arctan2", f);
Py_DECREF(f);
...


Beyond the Basics

  • NumPy User Guide
  • Using Numpy C-API
  • index
  • next
  • previous

Table Of Contents

  • Beyond the Basics
    • Iterating over elements in the array
      • Basic Iteration
      • Iterating over all but one axis
      • Iterating over multiple arrays
      • Broadcasting over multiple arrays
    • User-defined data-types
      • Adding the new data-type
      • Registering a casting function
      • Registering coercion rules
      • Registering a ufunc loop
    • Subtyping the ndarray in C
      • Creating sub-types
      • Specific features of ndarray sub-typing
        • The __array_finalize__ method
        • The __array_priority__ attribute
        • The __array_wrap__ method

Previous topic

Writing your own ufunc

Next topic

NumPy Reference

Beyond the Basics

The voyage of discovery is not in seeking new landscapes but in having
new eyes.
— Marcel Proust
Discovery is seeing what everyone else has seen and thinking what no
one else has thought.
— Albert Szent-Gyorgi

Iterating over elements in the array

Basic Iteration

One common algorithmic requirement is to be able to walk over all elements in a multidimensional array. The array iterator object makes this easy to do in a generic way that works for arrays of any dimension. Naturally, if you know the number of dimensions you will be using, then you can always write nested for loops to accomplish the iteration. If, however, you want to write code that works with any number of dimensions, then you can make use of the array iterator. An array iterator object is returned when accessing the .flat attribute of an array.

Basic usage is to call PyArray_IterNew ( array ) where array is an ndarray object (or one of its sub-classes). The returned object is an array-iterator object (the same object returned by the .flat attribute of the ndarray). This object is usually cast to PyArrayIterObject* so that its members can be accessed. The only members that are needed are iter->size which contains the total size of the array, iter->index, which contains the current 1-d index into the array, and iter->dataptr which is a pointer to the data for the current element of the array. Sometimes it is also useful to access iter->ao which is a pointer to the underlying ndarray object.

After processing data at the current element of the array, the next element of the array can be obtained using the macro PyArray_ITER_NEXT ( iter ). The iteration always proceeds in a C-style contiguous fashion (last index varying the fastest). The PyArray_ITER_GOTO ( iter, destination ) can be used to jump to a particular point in the array, where destination is an array of npy_intp data-type with space to handle at least the number of dimensions in the underlying array. Occasionally it is useful to use PyArray_ITER_GOTO1D ( iter, index ) which will jump to the 1-d index given by the value of index. The most common usage, however, is given in the following example.

PyObject *obj; /* assumed to be some ndarray object */
PyArrayIterObject *iter;
...
iter = (PyArrayIterObject *)PyArray_IterNew(obj);
if (iter == NULL) goto fail;   /* Assume fail has clean-up code */
while (iter->index < iter->size) {
    /* do something with the data at it->dataptr */
    PyArray_ITER_NEXT(it);
}
...

You can also use PyArrayIter_Check ( obj ) to ensure you have an iterator object and PyArray_ITER_RESET ( iter ) to reset an iterator object back to the beginning of the array.

It should be emphasized at this point that you may not need the array iterator if your array is already contiguous (using an array iterator will work but will be slower than the fastest code you could write). The major purpose of array iterators is to encapsulate iteration over N-dimensional arrays with arbitrary strides. They are used in many, many places in the NumPy source code itself. If you already know your array is contiguous (Fortran or C), then simply adding the element- size to a running pointer variable will step you through the array very efficiently. In other words, code like this will probably be faster for you in the contiguous case (assuming doubles).

npy_intp size;
double *dptr;  /* could make this any variable type */
size = PyArray_SIZE(obj);
dptr = PyArray_DATA(obj);
while(size--) {
   /* do something with the data at dptr */
   dptr++;
}

Iterating over all but one axis

A common algorithm is to loop over all elements of an array and perform some function with each element by issuing a function call. As function calls can be time consuming, one way to speed up this kind of algorithm is to write the function so it takes a vector of data and then write the iteration so the function call is performed for an entire dimension of data at a time. This increases the amount of work done per function call, thereby reducing the function-call over-head to a small(er) fraction of the total time. Even if the interior of the loop is performed without a function call it can be advantageous to perform the inner loop over the dimension with the highest number of elements to take advantage of speed enhancements available on micro- processors that use pipelining to enhance fundmental operations.

The PyArray_IterAllButAxis ( array, &dim ) constructs an iterator object that is modified so that it will not iterate over the dimension indicated by dim. The only restriction on this iterator object, is that the PyArray_Iter_GOTO1D ( it, ind ) macro cannot be used (thus flat indexing won’t work either if you pass this object back to Python — so you shouldn’t do this). Note that the returned object from this routine is still usually cast to PyArrayIterObject *. All that’s been done is to modify the strides and dimensions of the returned iterator to simulate iterating over array[...,0,...] where 0 is placed on the [image] dimension. If dim is negative, then the dimension with the largest axis is found and used.

Iterating over multiple arrays

Very often, it is desireable to iterate over several arrays at the same time. The universal functions are an example of this kind of behavior. If all you want to do is iterate over arrays with the same shape, then simply creating several iterator objects is the standard procedure. For example, the following code iterates over two arrays assumed to be the same shape and size (actually obj1 just has to have at least as many total elements as does obj2):

/* It is already assumed that obj1 and obj2
   are ndarrays of the same shape and size.
*/
iter1 = (PyArrayIterObject *)PyArray_IterNew(obj1);
if (iter1 == NULL) goto fail;
iter2 = (PyArrayIterObject *)PyArray_IterNew(obj2);
if (iter2 == NULL) goto fail;  /* assume iter1 is DECREF'd at fail */
while (iter2->index < iter2->size)  {
    /* process with iter1->dataptr and iter2->dataptr */
    PyArray_ITER_NEXT(iter1);
    PyArray_ITER_NEXT(iter2);
}

Broadcasting over multiple arrays

When multiple arrays are involved in an operation, you may want to use the same broadcasting rules that the math operations (i.e. the ufuncs) use. This can be done easily using the PyArrayMultiIterObject. This is the object returned from the Python command numpy.broadcast and it is almost as easy to use from C. The function PyArray_MultiIterNew ( n, ... ) is used (with n input objects in place of ... ). The input objects can be arrays or anything that can be converted into an array. A pointer to a PyArrayMultiIterObject is returned. Broadcasting has already been accomplished which adjusts the iterators so that all that needs to be done to advance to the next element in each array is for PyArray_ITER_NEXT to be called for each of the inputs. This incrementing is automatically performed by PyArray_MultiIter_NEXT ( obj ) macro (which can handle a multiterator obj as either a PyArrayMultiObject * or a PyObject *). The data from input number i is available using PyArray_MultiIter_DATA ( obj, i ) and the total (broadcasted) size as PyArray_MultiIter_SIZE ( obj). An example of using this feature follows.

mobj = PyArray_MultiIterNew(2, obj1, obj2);
size = PyArray_MultiIter_SIZE(obj);
while(size--) {
    ptr1 = PyArray_MultiIter_DATA(mobj, 0);
    ptr2 = PyArray_MultiIter_DATA(mobj, 1);
    /* code using contents of ptr1 and ptr2 */
    PyArray_MultiIter_NEXT(mobj);
}

The function PyArray_RemoveSmallest ( multi ) can be used to take a multi-iterator object and adjust all the iterators so that iteration does not take place over the largest dimension (it makes that dimension of size 1). The code being looped over that makes use of the pointers will very-likely also need the strides data for each of the iterators. This information is stored in multi->iters[i]->strides.

There are several examples of using the multi-iterator in the NumPy source code as it makes N-dimensional broadcasting-code very simple to write. Browse the source for more examples.

User-defined data-types

NumPy comes with 24 builtin data-types. While this covers a large majority of possible use cases, it is conceivable that a user may have a need for an additional data-type. There is some support for adding an additional data-type into the NumPy system. This additional data- type will behave much like a regular data-type except ufuncs must have 1-d loops registered to handle it separately. Also checking for whether or not other data-types can be cast “safely” to and from this new type or not will always return “can cast” unless you also register which types your new data-type can be cast to and from. Adding data-types is one of the less well-tested areas for NumPy 1.0, so there may be bugs remaining in the approach. Only add a new data-type if you can’t do what you want to do using the OBJECT or VOID data-types that are already available. As an example of what I consider a useful application of the ability to add data-types is the possibility of adding a data-type of arbitrary precision floats to NumPy.

Adding the new data-type

To begin to make use of the new data-type, you need to first define a new Python type to hold the scalars of your new data-type. It should be acceptable to inherit from one of the array scalars if your new type has a binary compatible layout. This will allow your new data type to have the methods and attributes of array scalars. New data- types must have a fixed memory size (if you want to define a data-type that needs a flexible representation, like a variable-precision number, then use a pointer to the object as the data-type). The memory layout of the object structure for the new Python type must be PyObject_HEAD followed by the fixed-size memory needed for the data- type. For example, a suitable structure for the new Python type is:

typedef struct {
   PyObject_HEAD;
   some_data_type obval;
   /* the name can be whatever you want */
} PySomeDataTypeObject;

After you have defined a new Python type object, you must then define a new PyArray_Descr structure whose typeobject member will contain a pointer to the data-type you’ve just defined. In addition, the required functions in the ”.f” member must be defined: nonzero, copyswap, copyswapn, setitem, getitem, and cast. The more functions in the ”.f” member you define, however, the more useful the new data-type will be. It is very important to intialize unused functions to NULL. This can be achieved using PyArray_InitArrFuncs (f).

Once a new PyArray_Descr structure is created and filled with the needed information and useful functions you call PyArray_RegisterDataType (new_descr). The return value from this call is an integer providing you with a unique type_number that specifies your data-type. This type number should be stored and made available by your module so that other modules can use it to recognize your data-type (the other mechanism for finding a user-defined data-type number is to search based on the name of the type-object associated with the data-type using PyArray_TypeNumFromName ).

Registering a casting function

You may want to allow builtin (and other user-defined) data-types to be cast automatically to your data-type. In order to make this possible, you must register a casting function with the data-type you want to be able to cast from. This requires writing low-level casting functions for each conversion you want to support and then registering these functions with the data-type descriptor. A low-level casting function has the signature.

void castfunc( void* from, void* to, npy_intp n, void* fromarr,
void* toarr)

Cast n elements from one type to another. The data to cast from is in a contiguous, correctly-swapped and aligned chunk of memory pointed to by from. The buffer to cast to is also contiguous, correctly-swapped and aligned. The fromarr and toarr arguments should only be used for flexible-element-sized arrays (string, unicode, void).

An example castfunc is:

static void
double_to_float(double *from, float* to, npy_intp n,
       void* ig1, void* ig2);
while (n--) {
      (*to++) = (double) *(from++);
}

This could then be registered to convert doubles to floats using the code:

doub = PyArray_DescrFromType(NPY_DOUBLE);
PyArray_RegisterCastFunc(doub, NPY_FLOAT,
     (PyArray_VectorUnaryFunc *)double_to_float);
Py_DECREF(doub);

Registering coercion rules

By default, all user-defined data-types are not presumed to be safely castable to any builtin data-types. In addition builtin data-types are not presumed to be safely castable to user-defined data-types. This situation limits the ability of user-defined data-types to participate in the coercion system used by ufuncs and other times when automatic coercion takes place in NumPy. This can be changed by registering data-types as safely castable from a particlar data-type object. The function PyArray_RegisterCanCast (from_descr, totype_number, scalarkind) should be used to specify that the data-type object from_descr can be cast to the data-type with type number totype_number. If you are not trying to alter scalar coercion rules, then use NPY_NOSCALAR for the scalarkind argument.

If you want to allow your new data-type to also be able to share in the scalar coercion rules, then you need to specify the scalarkind function in the data-type object’s ”.f” member to return the kind of scalar the new data-type should be seen as (the value of the scalar is available to that function). Then, you can register data-types that can be cast to separately for each scalar kind that may be returned from your user-defined data-type. If you don’t register scalar coercion handling, then all of your user-defined data-types will be seen as NPY_NOSCALAR.

Registering a ufunc loop

You may also want to register low-level ufunc loops for your data-type so that an ndarray of your data-type can have math applied to it seamlessly. Registering a new loop with exactly the same arg_types signature, silently replaces any previously registered loops for that data-type.

Before you can register a 1-d loop for a ufunc, the ufunc must be previously created. Then you call PyUFunc_RegisterLoopForType (...) with the information needed for the loop. The return value of this function is 0 if the process was successful and -1 with an error condition set if it was not successful.

int PyUFunc_RegisterLoopForType( PyUFuncObject* ufunc,
int usertype, PyUFuncGenericFunction function, int* arg_types, void* data)

ufunc

The ufunc to attach this loop to.

usertype

The user-defined type this loop should be indexed under. This number must be a user-defined type or an error occurs.

function

The ufunc inner 1-d loop. This function must have the signature as explained in Section 3 .

arg_types

(optional) If given, this should contain an array of integers of at least size ufunc.nargs containing the data-types expected by the loop function. The data will be copied into a NumPy-managed structure so the memory for this argument should be deleted after calling this function. If this is NULL, then it will be assumed that all data-types are of type usertype.

data

(optional) Specify any optional data needed by the function which will be passed when the function is called.

Subtyping the ndarray in C

One of the lesser-used features that has been lurking in Python since 2.2 is the ability to sub-class types in C. This facility is one of the important reasons for basing NumPy off of the Numeric code-base which was already in C. A sub-type in C allows much more flexibility with regards to memory management. Sub-typing in C is not difficult even if you have only a rudimentary understanding of how to create new types for Python. While it is easiest to sub-type from a single parent type, sub-typing from multiple parent types is also possible. Multiple inheritence in C is generally less useful than it is in Python because a restriction on Python sub-types is that they have a binary compatible memory layout. Perhaps for this reason, it is somewhat easier to sub-type from a single parent type.

All C-structures corresponding to Python objects must begin with PyObject_HEAD (or PyObject_VAR_HEAD). In the same way, any sub-type must have a C-structure that begins with exactly the same memory layout as the parent type (or all of the parent types in the case of multiple-inheritance). The reason for this is that Python may attempt to access a member of the sub-type structure as if it had the parent structure ( i.e. it will cast a given pointer to a pointer to the parent structure and then dereference one of it’s members). If the memory layouts are not compatible, then this attempt will cause unpredictable behavior (eventually leading to a memory violation and program crash).

One of the elements in PyObject_HEAD is a pointer to a type-object structure. A new Python type is created by creating a new type-object structure and populating it with functions and pointers to describe the desired behavior of the type. Typically, a new C-structure is also created to contain the instance-specific information needed for each object of the type as well. For example, &PyArray_Type is a pointer to the type-object table for the ndarray while a PyArrayObject * variable is a pointer to a particular instance of an ndarray (one of the members of the ndarray structure is, in turn, a pointer to the type- object table &PyArray_Type). Finally PyType_Ready (<pointer_to_type_object>) must be called for every new Python type.

Creating sub-types

To create a sub-type, a similar proceedure must be followed except only behaviors that are different require new entries in the type- object structure. All other entires can be NULL and will be filled in by PyType_Ready with appropriate functions from the parent type(s). In particular, to create a sub-type in C follow these steps:

  1. If needed create a new C-structure to handle each instance of your type. A typical C-structure would be:

    typedef _new_struct {
    PyArrayObject base;
    /* new things here */
} NewArrayObject;

    Notice that the full PyArrayObject is used as the first entry in order to ensure that the binary layout of instances of the new type is identical to the PyArrayObject.

  2. Fill in a new Python type-object structure with pointers to new functions that will over-ride the default behavior while leaving any function that should remain the same unfilled (or NULL). The tp_name element should be different.

  3. Fill in the tp_base member of the new type-object structure with a pointer to the (main) parent type object. For multiple-inheritance, also fill in the tp_bases member with a tuple containing all of the parent objects in the order they should be used to define inheritance. Remember, all parent-types must have the same C-structure for multiple inheritance to work properly.

  4. Call PyType_Ready (<pointer_to_new_type>). If this function returns a negative number, a failure occurred and the type is not initialized. Otherwise, the type is ready to be used. It is generally important to place a reference to the new type into the module dictionary so it can be accessed from Python.

More information on creating sub-types in C can be learned by reading PEP 253 (available at http://www.python.org/dev/peps/pep-0253).

Specific features of ndarray sub-typing

Some special methods and attributes are used by arrays in order to facilitate the interoperation of sub-types with the base ndarray type.

The __array_finalize__ method

ndarray.__array_finalize__

Several array-creation functions of the ndarray allow specification of a particular sub-type to be created. This allows sub-types to be handled seamlessly in many routines. When a sub-type is created in such a fashion, however, neither the __new__ method nor the __init__ method gets called. Instead, the sub-type is allocated and the appropriate instance-structure members are filled in. Finally, the __array_finalize__ attribute is looked-up in the object dictionary. If it is present and not None, then it can be either a CObject containing a pointer to a PyArray_FinalizeFunc or it can be a method taking a single argument (which could be None).

If the __array_finalize__ attribute is a CObject, then the pointer must be a pointer to a function with the signature:

(int) (PyArrayObject *, PyObject *)

The first argument is the newly created sub-type. The second argument (if not NULL) is the “parent” array (if the array was created using slicing or some other operation where a clearly-distinguishable parent is present). This routine can do anything it wants to. It should return a -1 on error and 0 otherwise.

If the __array_finalize__ attribute is not None nor a CObject, then it must be a Python method that takes the parent array as an argument (which could be None if there is no parent), and returns nothing. Errors in this method will be caught and handled.

The __array_priority__ attribute

ndarray.__array_priority__

This attribute allows simple but flexible determination of which sub- type should be considered “primary” when an operation involving two or more sub-types arises. In operations where different sub-types are being used, the sub-type with the largest __array_priority__ attribute will determine the sub-type of the output(s). If two sub- types have the same __array_priority__ then the sub-type of the first argument determines the output. The default __array_priority__ attribute returns a value of 0.0 for the base ndarray type and 1.0 for a sub-type. This attribute can also be defined by objects that are not sub-types of the ndarray and can be used to determine which __array_wrap__ method should be called for the return output.

The __array_wrap__ method

ndarray.__array_wrap__

Any class or type can define this method which should take an ndarray argument and return an instance of the type. It can be seen as the opposite of the __array__ method. This method is used by the ufuncs (and other NumPy functions) to allow other objects to pass through. For Python >2.4, it can also be used to write a decorator that converts a function that works only with ndarrays to one that works with any type with __array__ and __array_wrap__ methods.


NumPy Reference

  • next
  • previous

Table Of Contents

  • NumPy Reference
    • Acknowledgements

Previous topic

Beyond the Basics

Next topic

Array objects

NumPy Reference

Release: | 1.9
Date: | November 20, 2014

This reference manual details functions, modules, and objects included in Numpy, describing what they are and what they do. For learning how to use NumPy, see also NumPy User Guide.

  • Array objects
    • The N-dimensional array (ndarray)
    • Scalars
    • Data type objects (dtype)
    • Indexing
    • Iterating Over Arrays
    • Standard array subclasses
    • Masked arrays
    • The Array Interface
    • Datetimes and Timedeltas
  • Universal functions (ufunc)
    • Broadcasting
    • Output type determination
    • Use of internal buffers
    • Error handling
    • Casting Rules
    • Overriding Ufunc behavior
    • ufunc
    • Available ufuncs
  • Routines
    • Array creation routines
    • Array manipulation routines
    • Binary operations
    • String operations
    • C-Types Foreign Function Interface (numpy.ctypeslib)
    • Datetime Support Functions
    • Data type routines
    • Optionally Scipy-accelerated routines (numpy.dual)
    • Mathematical functions with automatic domain (numpy.emath)
    • Floating point error handling
    • Discrete Fourier Transform (numpy.fft)
    • Financial functions
    • Functional programming
    • Numpy-specific help functions
    • Indexing routines
    • Input and output
    • Linear algebra (numpy.linalg)
    • Logic functions
    • Masked array operations
    • Mathematical functions
    • Matrix library (numpy.matlib)
    • Miscellaneous routines
    • Padding Arrays
    • Polynomials
    • Random sampling (numpy.random)
    • Set routines
    • Sorting, searching, and counting
    • Statistics
    • Test Support (numpy.testing)
    • Window functions
  • Packaging (numpy.distutils)
    • Modules in numpy.distutils
    • Building Installable C libraries
    • Conversion of .src files
  • Numpy C-API
    • Python Types and C-Structures
    • System configuration
    • Data Type API
    • Array API
    • Array Iterator API
    • UFunc API
    • Generalized Universal Function API
    • Numpy core libraries
    • C API Deprecations
  • Numpy internals
    • Numpy C Code Explanations
    • Internal organization of numpy arrays
    • Multidimensional Array Indexing Order Issues
  • Numpy and SWIG
    • Numpy.i: a SWIG Interface File for NumPy
    • Testing the numpy.i Typemaps

Acknowledgements

Large parts of this manual originate from Travis E. Oliphant’s book Guide to Numpy (which generously entered Public Domain in August 2008). The reference documentation for many of the functions are written by numerous contributors and developers of Numpy, both prior to and during the Numpy Documentation Marathon.

Please help to improve NumPy’s documentation! Instructions on how to join the ongoing documentation marathon can be found on the scipy.org website


Array objects

  • NumPy Reference
  • next
  • previous

Previous topic

NumPy Reference

Next topic

The N-dimensional array (ndarray)

Array objects

NumPy provides an N-dimensional array type, the ndarray, which describes a collection of “items” of the same type. The items can be indexed using for example N integers.

All ndarrays are homogenous: every item takes up the same size block of memory, and all blocks are interpreted in exactly the same way. How each item in the array is to be interpreted is specified by a separate data-type object, one of which is associated with every array. In addition to basic types (integers, floats, etc.), the data type objects can also represent data structures.

An item extracted from an array, e.g., by indexing, is represented by a Python object whose type is one of the array scalar types built in Numpy. The array scalars allow easy manipulation of also more complicated arrangements of data.

Figure Conceptual diagram showing the relationship between the three fundamental objects used to describe the data in an array: 1) the ndarray itself, 2) the data-type object that describes the layout of a single fixed-size element of the array, 3) the array-scalar Python object that is returned when a single element of the array is accessed.

  • The N-dimensional array (ndarray)
    • Constructing arrays
    • Indexing arrays
    • Internal memory layout of an ndarray
    • Array attributes
    • Array methods
    • Arithmetic and comparison operations
    • Special methods
  • Scalars
    • Built-in scalar types
    • Attributes
    • Indexing
    • Methods
    • Defining new types
  • Data type objects (dtype)
    • Specifying and constructing data types
    • dtype
  • Indexing
    • Basic Slicing and Indexing
    • Advanced Indexing
    • Detailed notes
    • Record Access
    • Flat Iterator indexing
  • Iterating Over Arrays
    • Single Array Iteration
    • Broadcasting Array Iteration
    • Putting the Inner Loop in Cython
  • Standard array subclasses
    • Special attributes and methods
    • Matrix objects
    • Memory-mapped file arrays
    • Character arrays (numpy.char)
    • Record arrays (numpy.rec)
    • Masked arrays (numpy.ma)
    • Standard container class
    • Array Iterators
  • Masked arrays
    • The numpy.ma module
    • Using numpy.ma
    • Examples
    • Constants of the numpy.ma module
    • The MaskedArray class
    • MaskedArray methods
    • Masked array operations
  • The Array Interface
    • Python side
    • C-struct access
    • Type description examples
    • Differences with Array interface (Version 2)
  • Datetimes and Timedeltas
    • Basic Datetimes
    • Datetime and Timedelta Arithmetic
    • Datetime Units
    • Business Day Functionality
    • Differences Between 1.6 and 1.7 Datetimes


The N-dimensional array (ndarray)

  • Array objects
  • next
  • previous

Table Of Contents

  • The N-dimensional array (ndarray)
    • Constructing arrays
    • Indexing arrays
    • Internal memory layout of an ndarray
    • Array attributes
      • Memory layout
      • Data type
      • Other attributes
      • Array interface
      • ctypes foreign function interface
    • Array methods
      • Array conversion
      • Shape manipulation
      • Item selection and manipulation
      • Calculation
    • Arithmetic and comparison operations
    • Special methods

Previous topic

Array objects

Next topic

numpy.ndarray

The N-dimensional array (ndarray)

An ndarray is a (usually fixed-size) multidimensional container of items of the same type and size. The number of dimensions and items in an array is defined by its shape, which is a tuple of N positive integers that specify the sizes of each dimension. The type of items in the array is specified by a separate data-type object (dtype), one of which is associated with each ndarray.

As with other container objects in Python, the contents of an ndarray can be accessed and modified by indexing or slicing the array (using, for example, N integers), and via the methods and attributes of the ndarray.

Different ndarrays can share the same data, so that changes made in one ndarray may be visible in another. That is, an ndarray can be a “view” to another ndarray, and the data it is referring to is taken care of by the “base” ndarray. ndarrays can also be views to memory owned by Python strings or objects implementing the buffer or array interfaces.

Example

A 2-dimensional array of size 2 x 3, composed of 4-byte integer elements:

>>> x = np.array([[1, 2, 3], [4, 5, 6]], np.int32)
>>> type(x)
<type 'numpy.ndarray'>
>>> x.shape
(2, 3)
>>> x.dtype
dtype('int32')

The array can be indexed using Python container-like syntax:

>>> x[1,2] # i.e., the element of x in the *second* row, *third*
column, namely, 6.

For example slicing can produce views of the array:

>>> y = x[:,1]
>>> y
array([2, 5])
>>> y[0] = 9 # this also changes the corresponding element in x
>>> y
array([9, 5])
>>> x
array([[1, 9, 3],
       [4, 5, 6]])

Constructing arrays

New arrays can be constructed using the routines detailed in Array creation routines, and also by using the low-level ndarray constructor:

ndarray An array object represents a multidimensional, homogeneous array of fixed-size items.

Indexing arrays

Arrays can be indexed using an extended Python slicing syntax, array[selection]. Similar syntax is also used for accessing fields in a record array.

See also

Array Indexing.

Internal memory layout of an ndarray

An instance of class ndarray consists of a contiguous one-dimensional segment of computer memory (owned by the array, or by some other object), combined with an indexing scheme that maps N integers into the location of an item in the block. The ranges in which the indices can vary is specified by the shape of the array. How many bytes each item takes and how the bytes are interpreted is defined by the data-type object associated with the array.

A segment of memory is inherently 1-dimensional, and there are many different schemes for arranging the items of an N-dimensional array in a 1-dimensional block. Numpy is flexible, and ndarray objects can accommodate any strided indexing scheme. In a strided scheme, the N-dimensional index (n_0, n_1, ..., n_{N-1}) corresponds to the offset (in bytes):

from the beginning of the memory block associated with the array. Here, [image] are integers which specify the strides of the array. The column-major order (used, for example, in the Fortran language and in Matlab) and row-major order (used in C) schemes are just specific kinds of strided scheme, and correspond to memory that can be addressed by the strides:

where [image] = self.itemsize * self.shape[j].

Both the C and Fortran orders are contiguous, i.e., single-segment, memory layouts, in which every part of the memory block can be accessed by some combination of the indices.

While a C-style and Fortran-style contiguous array, which has the corresponding flags set, can be addressed with the above strides, the actual strides may be different. This can happen in two cases:

  1. If self.shape[k] == 1 then for any legal index index[k] == 0. This means that in the formula for the offset n_k = 0 and thus s_k n_k = 0 and the value of [image] = self.strides[k] is arbitrary.
  2. If an array has no elements (self.size == 0) there is no legal index and the strides are never used. Any array with no elements may be considered C-style and Fortran-style contiguous.

Point 1. means that self``and ``self.squeeze() always have the same contiguity and aligned flags value. This also means that even a high dimensional array could be C-style and Fortran-style contiguous at the same time.

An array is considered aligned if the memory offsets for all elements and the base offset itself is a multiple of self.itemsize.

Note

Points (1) and (2) are not yet applied by default. Beginning with Numpy 1.8.0, they are applied consistently only if the environment variable NPY_RELAXED_STRIDES_CHECKING=1 was defined when NumPy was built. Eventually this will become the default.

You can check whether this option was enabled when your NumPy was built by looking at the value of np.ones((10,1), order='C').flags.f_contiguous. If this is True, then your NumPy has relaxed strides checking enabled.

Warning

It does not generally hold that self.strides[-1] == self.itemsize for C-style contiguous arrays or self.strides[0] == self.itemsize for Fortran-style contiguous arrays is true.

Data in new ndarrays is in the row-major (C) order, unless otherwise specified, but, for example, basic array slicing often produces views in a different scheme.

Note

Several algorithms in NumPy work on arbitrarily strided arrays. However, some algorithms require single-segment arrays. When an irregularly strided array is passed in to such algorithms, a copy is automatically made.

Array attributes

Array attributes reflect information that is intrinsic to the array itself. Generally, accessing an array through its attributes allows you to get and sometimes set intrinsic properties of the array without creating a new array. The exposed attributes are the core parts of an array and only some of them can be reset meaningfully without creating a new array. Information on each attribute is given below.

Memory layout

The following attributes contain information about the memory layout of the array:

ndarray.flags | Information about the memory layout of the array.
ndarray.shape | Tuple of array dimensions.
ndarray.strides | Tuple of bytes to step in each dimension when traversing an array.
ndarray.ndim | Number of array dimensions.
ndarray.data | Python buffer object pointing to the start of the array’s data.
ndarray.size | Number of elements in the array.
ndarray.itemsize | Length of one array element in bytes.
ndarray.nbytes | Total bytes consumed by the elements of the array.
ndarray.base | Base object if memory is from some other object.

Data type

See also

Data type objects

The data type object associated with the array can be found in the dtype attribute:

ndarray.dtype Data-type of the array’s elements.

Other attributes

ndarray.T | Same as self.transpose(), except that self is returned if self.ndim < 2.
ndarray.real | The real part of the array.
ndarray.imag | The imaginary part of the array.
ndarray.flat | A 1-D iterator over the array.
ndarray.ctypes | An object to simplify the interaction of the array with the ctypes module.
__array_priority__ |

Array interface

See also

The Array Interface.

__array_interface__ | Python-side of the array interface
__array_struct__ | C-side of the array interface

ctypes foreign function interface

ndarray.ctypes An object to simplify the interaction of the array with the ctypes module.

Array methods

An ndarray object has many methods which operate on or with the array in some fashion, typically returning an array result. These methods are briefly explained below. (Each method’s docstring has a more complete description.)

For the following methods there are also corresponding functions in numpy: all, any, argmax, argmin, argpartition, argsort, choose, clip, compress, copy, cumprod, cumsum, diagonal, imag, max, mean, min, nonzero, partition, prod, ptp, put, ravel, real, repeat, reshape, round, searchsorted, sort, squeeze, std, sum, swapaxes, take, trace, transpose, var.

Array conversion

ndarray.item(*args) | Copy an element of an array to a standard Python scalar and return it.
ndarray.tolist() | Return the array as a (possibly nested) list.
ndarray.itemset(*args) | Insert scalar into an array (scalar is cast to array’s dtype, if possible)
ndarray.setasflat |
ndarray.tostring([order]) | Construct Python bytes containing the raw data bytes in the array.
ndarray.tobytes([order]) | Construct Python bytes containing the raw data bytes in the array.
ndarray.tofile(fid[, sep, format]) | Write array to a file as text or binary (default).
ndarray.dump(file) | Dump a pickle of the array to the specified file.
ndarray.dumps() | Returns the pickle of the array as a string.
ndarray.astype(dtype[, order, casting, ...]) | Copy of the array, cast to a specified type.
ndarray.byteswap(inplace) | Swap the bytes of the array elements
ndarray.copy([order]) | Return a copy of the array.
ndarray.view([dtype, type]) | New view of array with the same data.
ndarray.getfield(dtype[, offset]) | Returns a field of the given array as a certain type.
ndarray.setflags([write, align, uic]) | Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively.
ndarray.fill(value) | Fill the array with a scalar value.

Shape manipulation

For reshape, resize, and transpose, the single tuple argument may be replaced with n integers which will be interpreted as an n-tuple.

ndarray.reshape(shape[, order]) | Returns an array containing the same data with a new shape.
ndarray.resize(new_shape[, refcheck]) | Change shape and size of array in-place.
ndarray.transpose(*axes) | Returns a view of the array with axes transposed.
ndarray.swapaxes(axis1, axis2) | Return a view of the array with axis1 and axis2 interchanged.
ndarray.flatten([order]) | Return a copy of the array collapsed into one dimension.
ndarray.ravel([order]) | Return a flattened array.
ndarray.squeeze([axis]) | Remove single-dimensional entries from the shape of a.

Item selection and manipulation

For array methods that take an axis keyword, it defaults to None. If axis is None, then the array is treated as a 1-D array. Any other value for axis represents the dimension along which the operation should proceed.

ndarray.take(indices[, axis, out, mode]) | Return an array formed from the elements of a at the given indices.
ndarray.put(indices, values[, mode]) | Set a.flat[n] = values[n] for all n in indices.
ndarray.repeat(repeats[, axis]) | Repeat elements of an array.
ndarray.choose(choices[, out, mode]) | Use an index array to construct a new array from a set of choices.
ndarray.sort([axis, kind, order]) | Sort an array, in-place.
ndarray.argsort([axis, kind, order]) | Returns the indices that would sort this array.
ndarray.partition(kth[, axis, kind, order]) | Rearranges the elements in the array in such a way that value of the element in kth position is in the position it would be in a sorted array.
ndarray.argpartition(kth[, axis, kind, order]) | Returns the indices that would partition this array.
ndarray.searchsorted(v[, side, sorter]) | Find indices where elements of v should be inserted in a to maintain order.
ndarray.nonzero() | Return the indices of the elements that are non-zero.
ndarray.compress(condition[, axis, out]) | Return selected slices of this array along given axis.
ndarray.diagonal([offset, axis1, axis2]) | Return specified diagonals.

Calculation

Many of these methods take an argument named axis. In such cases,

  • If axis is None (the default), the array is treated as a 1-D array and the operation is performed over the entire array. This behavior is also the default if self is a 0-dimensional array or array scalar. (An array scalar is an instance of the types/classes float32, float64, etc., whereas a 0-dimensional array is an ndarray instance containing precisely one array scalar.)
  • If axis is an integer, then the operation is done over the given axis (for each 1-D subarray that can be created along the given axis).

Example of the axis argument

A 3-dimensional array of size 3 x 3 x 3, summed over each of its three axes

>>> x
array([[[ 0,  1,  2],
        [ 3,  4,  5],
        [ 6,  7,  8]],
       [[ 9, 10, 11],
        [12, 13, 14],
        [15, 16, 17]],
       [[18, 19, 20],
        [21, 22, 23],
        [24, 25, 26]]])
>>> x.sum(axis=0)
array([[27, 30, 33],
       [36, 39, 42],
       [45, 48, 51]])
>>> # for sum, axis is the first keyword, so we may omit it,
>>> # specifying only its value
>>> x.sum(0), x.sum(1), x.sum(2)
(array([[27, 30, 33],
        [36, 39, 42],
        [45, 48, 51]]),
 array([[ 9, 12, 15],
        [36, 39, 42],
        [63, 66, 69]]),
 array([[ 3, 12, 21],
        [30, 39, 48],
        [57, 66, 75]]))

The parameter dtype specifies the data type over which a reduction operation (like summing) should take place. The default reduce data type is the same as the data type of self. To avoid overflow, it can be useful to perform the reduction using a larger data type.

For several methods, an optional out argument can also be provided and the result will be placed into the output array given. The out argument must be an ndarray and have the same number of elements. It can have a different data type in which case casting will be performed.

ndarray.argmax([axis, out]) | Return indices of the maximum values along the given axis.
ndarray.min([axis, out]) | Return the minimum along a given axis.
ndarray.argmin([axis, out]) | Return indices of the minimum values along the given axis of a.
ndarray.ptp([axis, out]) | Peak to peak (maximum - minimum) value along a given axis.
ndarray.clip(a_min, a_max[, out]) | Return an array whose values are limited to [a_min, a_max].
ndarray.conj() | Complex-conjugate all elements.
ndarray.round([decimals, out]) | Return a with each element rounded to the given number of decimals.
ndarray.trace([offset, axis1, axis2, dtype, out]) | Return the sum along diagonals of the array.
ndarray.sum([axis, dtype, out]) | Return the sum of the array elements over the given axis.
ndarray.cumsum([axis, dtype, out]) | Return the cumulative sum of the elements along the given axis.
ndarray.mean([axis, dtype, out]) | Returns the average of the array elements along given axis.
ndarray.var([axis, dtype, out, ddof]) | Returns the variance of the array elements, along given axis.
ndarray.std([axis, dtype, out, ddof]) | Returns the standard deviation of the array elements along given axis.
ndarray.prod([axis, dtype, out]) | Return the product of the array elements over the given axis
ndarray.cumprod([axis, dtype, out]) | Return the cumulative product of the elements along the given axis.
ndarray.all([axis, out]) | Returns True if all elements evaluate to True.
ndarray.any([axis, out]) | Returns True if any of the elements of a evaluate to True.

Arithmetic and comparison operations

Arithmetic and comparison operations on ndarrays are defined as element-wise operations, and generally yield ndarray objects as results.

Each of the arithmetic operations (+, -, *, /, //, %, divmod(), ** or pow(), <<, >>, &, ^, |, ~) and the comparisons (==, <, >, <=, >=, !=) is equivalent to the corresponding universal function (or ufunc for short) in Numpy. For more information, see the section on Universal Functions.

Comparison operators:

ndarray.__lt__ | x.__lt__(y) <==> x<y
ndarray.__le__ | x.__le__(y) <==> x<=y
ndarray.__gt__ | x.__gt__(y) <==> x>y
ndarray.__ge__ | x.__ge__(y) <==> x>=y
ndarray.__eq__ | x.__eq__(y) <==> x==y
ndarray.__ne__ | x.__ne__(y) <==> x!=y

Truth value of an array (bool):

ndarray.__nonzero__ x.__nonzero__() <==> x != 0

Note

Truth-value testing of an array invokes ndarray.__nonzero__, which raises an error if the number of elements in the the array is larger than 1, because the truth value of such arrays is ambiguous. Use .any() and .all() instead to be clear about what is meant in such cases. (If the number of elements is 0, the array evaluates to False.)

Unary operations:

ndarray.__neg__ | x.__neg__() <==> -x
ndarray.__pos__ | x.__pos__() <==> +x
ndarray.__abs__() <==> abs(x) |
ndarray.__invert__ | x.__invert__() <==> ~x

Arithmetic:

ndarray.__add__ | x.__add__(y) <==> x+y
ndarray.__sub__ | x.__sub__(y) <==> x-y
ndarray.__mul__ | x.__mul__(y) <==> x*y
ndarray.__div__ | x.__div__(y) <==> x/y
ndarray.__truediv__ | x.__truediv__(y) <==> x/y
ndarray.__floordiv__ | x.__floordiv__(y) <==> x//y
ndarray.__mod__ | x.__mod__(y) <==> x%y
ndarray.__divmod__(y) <==> divmod(x, y) |
ndarray.__pow__(y[, z]) <==> pow(x, y[, z]) |
ndarray.__lshift__ | x.__lshift__(y) <==> x<<y
ndarray.__rshift__ | x.__rshift__(y) <==> x>>y
ndarray.__and__ | x.__and__(y) <==> x&y
ndarray.__or__ | x.__or__(y) <==> x|y
ndarray.__xor__ | x.__xor__(y) <==> x^y

Note

  • Any third argument to pow is silently ignored, as the underlying ufunc takes only two arguments.
  • The three division operators are all defined; div is active by default, truediv is active when __future__ division is in effect.
  • Because ndarray is a built-in type (written in C), the __r{op}__ special methods are not directly defined.
  • The functions called to implement many arithmetic special methods for arrays can be modified using set_numeric_ops.

Arithmetic, in-place:

ndarray.__iadd__ | x.__iadd__(y) <==> x+=y
ndarray.__isub__ | x.__isub__(y) <==> x-=y
ndarray.__imul__ | x.__imul__(y) <==> x*=y
ndarray.__idiv__ | x.__idiv__(y) <==> x/=y
ndarray.__itruediv__ | x.__itruediv__(y) <==> x/y
ndarray.__ifloordiv__ | x.__ifloordiv__(y) <==> x//y
ndarray.__imod__ | x.__imod__(y) <==> x%=y
ndarray.__ipow__ | x.__ipow__(y) <==> x**=y
ndarray.__ilshift__ | x.__ilshift__(y) <==> x<<=y
ndarray.__irshift__ | x.__irshift__(y) <==> x>>=y
ndarray.__iand__ | x.__iand__(y) <==> x&=y
ndarray.__ior__ | x.__ior__(y) <==> x|=y
ndarray.__ixor__ | x.__ixor__(y) <==> x^=y

Warning

In place operations will perform the calculation using the precision decided by the data type of the two operands, but will silently downcast the result (if necessary) so it can fit back into the array. Therefore, for mixed precision calculations, A {op}= B can be different than A = A {op} B. For example, suppose a = ones((3,3)). Then, a += 3j is different than a = a + 3j: while they both perform the same computation, a += 3 casts the result to fit back in a, whereas a = a + 3j re-binds the name a to the result.

Special methods

For standard library functions:

ndarray.__copy__([order]) | Return a copy of the array.
ndarray.__deepcopy__(() -> Deep copy of array.) | Used if copy.deepcopy is called on an array.
ndarray.__reduce__() | For pickling.
ndarray.__setstate__(version, shape, dtype, ...) | For unpickling.

Basic customization:

ndarray.__new__((S, ...) |
ndarray.__array__(...) | Returns either a new reference to self if dtype is not given or a new array of provided data type if dtype is different from the current dtype of the array.
ndarray.__array_wrap__(...) |

Container customization: (see Indexing)

ndarray.__len__() <==> len(x) |
ndarray.__getitem__ | x.__getitem__(y) <==> x[y]
ndarray.__setitem__ | x.__setitem__(i, y) <==> x[i]=y
ndarray.__getslice__ | x.__getslice__(i, j) <==> x[i:j]
ndarray.__setslice__ | x.__setslice__(i, j, y) <==> x[i:j]=y
ndarray.__contains__ | x.__contains__(y) <==> y in x

Conversion; the operations complex, int, long, float, oct, and hex. They work only on arrays that have one element in them and return the appropriate scalar.

ndarray.__int__() <==> int(x)
ndarray.__long__() <==> long(x)
ndarray.__float__() <==> float(x)
ndarray.__oct__() <==> oct(x)
ndarray.__hex__() <==> hex(x)

String representations:

ndarray.__str__() <==> str(x)
ndarray.__repr__() <==> repr(x)


numpy.ndarray

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__repr__

Next topic

numpy.ndarray.T

numpy.ndarray

class numpy.ndarray [source]

An array object represents a multidimensional, homogeneous array of fixed-size items. An associated data-type object describes the format of each element in the array (its byte-order, how many bytes it occupies in memory, whether it is an integer, a floating point number, or something else, etc.)

Arrays should be constructed using array, zeros or empty (refer to the See Also section below). The parameters given here refer to a low-level method (ndarray(...)) for instantiating an array.

For more information, refer to the numpy module and examine the the methods and attributes of an array.

Parameters:

(for the __new__ method; see Notes below)

shape : tuple of ints

Shape of created array.

dtype : data-type, optional

Any object that can be interpreted as a numpy data type.

buffer : object exposing buffer interface, optional

Used to fill the array with data.

offset : int, optional

Offset of array data in buffer.

strides : tuple of ints, optional

Strides of data in memory.

order : {‘C’, ‘F’}, optional

Row-major or column-major order.

See also

array
Construct an array.
zeros
Create an array, each element of which is zero.
empty
Create an array, but leave its allocated memory unchanged (i.e., it contains “garbage”).
dtype
Create a data-type.

Notes

There are two modes of creating an array using __new__:

  1. If buffer is None, then only shape, dtype, and order are used.
  2. If buffer is an object exposing the buffer interface, then all keywords are interpreted.

No __init__ method is needed because the array is fully initialized after the __new__ method.

Examples

These examples illustrate the low-level ndarray constructor. Refer to the See Also section above for easier ways of constructing an ndarray.

First mode, buffer is None:

>>> np.ndarray(shape=(2,2), dtype=float, order='F')
array([[ -1.13698227e+002,   4.25087011e-303],
       [  2.88528414e-306,   3.27025015e-309]])         #random

Second mode:

>>> np.ndarray((2,), buffer=np.array([1,2,3]),
...            offset=np.int_().itemsize,
...            dtype=int) # offset = 1*itemsize, i.e. skip first element
array([2, 3])

Attributes

T | Same as self.transpose(), except that self is returned if self.ndim < 2.
data | Python buffer object pointing to the start of the array’s data.
dtype | Data-type of the array’s elements.
flags | Information about the memory layout of the array.
flat | A 1-D iterator over the array.
imag | The imaginary part of the array.
real | The real part of the array.
size | Number of elements in the array.
itemsize | Length of one array element in bytes.
nbytes | Total bytes consumed by the elements of the array.
ndim | Number of array dimensions.
shape | Tuple of array dimensions.
strides | Tuple of bytes to step in each dimension when traversing an array.
ctypes | An object to simplify the interaction of the array with the ctypes module.
base | Base object if memory is from some other object.

Methods

all([axis, out]) | Returns True if all elements evaluate to True.
any([axis, out]) | Returns True if any of the elements of a evaluate to True.
argmax([axis, out]) | Return indices of the maximum values along the given axis.
argmin([axis, out]) | Return indices of the minimum values along the given axis of a.
argpartition(kth[, axis, kind, order]) | Returns the indices that would partition this array.
argsort([axis, kind, order]) | Returns the indices that would sort this array.
astype(dtype[, order, casting, subok, copy]) | Copy of the array, cast to a specified type.
byteswap(inplace) | Swap the bytes of the array elements
choose(choices[, out, mode]) | Use an index array to construct a new array from a set of choices.
clip(a_min, a_max[, out]) | Return an array whose values are limited to [a_min, a_max].
compress(condition[, axis, out]) | Return selected slices of this array along given axis.
conj() | Complex-conjugate all elements.
conjugate() | Return the complex conjugate, element-wise.
copy([order]) | Return a copy of the array.
cumprod([axis, dtype, out]) | Return the cumulative product of the elements along the given axis.
cumsum([axis, dtype, out]) | Return the cumulative sum of the elements along the given axis.
diagonal([offset, axis1, axis2]) | Return specified diagonals.
dot(b[, out]) | Dot product of two arrays.
dump(file) | Dump a pickle of the array to the specified file.
dumps() | Returns the pickle of the array as a string.
fill(value) | Fill the array with a scalar value.
flatten([order]) | Return a copy of the array collapsed into one dimension.
getfield(dtype[, offset]) | Returns a field of the given array as a certain type.
item(*args) | Copy an element of an array to a standard Python scalar and return it.
itemset(*args) | Insert scalar into an array (scalar is cast to array’s dtype, if possible)
max([axis, out]) | Return the maximum along a given axis.
mean([axis, dtype, out]) | Returns the average of the array elements along given axis.
min([axis, out]) | Return the minimum along a given axis.
newbyteorder([new_order]) | Return the array with the same data viewed with a different byte order.
nonzero() | Return the indices of the elements that are non-zero.
partition(kth[, axis, kind, order]) | Rearranges the elements in the array in such a way that value of the element in kth position is in the position it would be in a sorted array.
prod([axis, dtype, out]) | Return the product of the array elements over the given axis
ptp([axis, out]) | Peak to peak (maximum - minimum) value along a given axis.
put(indices, values[, mode]) | Set a.flat[n] = values[n] for all n in indices.
ravel([order]) | Return a flattened array.
repeat(repeats[, axis]) | Repeat elements of an array.
reshape(shape[, order]) | Returns an array containing the same data with a new shape.
resize(new_shape[, refcheck]) | Change shape and size of array in-place.
round([decimals, out]) | Return a with each element rounded to the given number of decimals.
searchsorted(v[, side, sorter]) | Find indices where elements of v should be inserted in a to maintain order.
setfield(val, dtype[, offset]) | Put a value into a specified place in a field defined by a data-type.
setflags([write, align, uic]) | Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively.
sort([axis, kind, order]) | Sort an array, in-place.
squeeze([axis]) | Remove single-dimensional entries from the shape of a.
std([axis, dtype, out, ddof]) | Returns the standard deviation of the array elements along given axis.
sum([axis, dtype, out]) | Return the sum of the array elements over the given axis.
swapaxes(axis1, axis2) | Return a view of the array with axis1 and axis2 interchanged.
take(indices[, axis, out, mode]) | Return an array formed from the elements of a at the given indices.
tobytes([order]) | Construct Python bytes containing the raw data bytes in the array.
tofile(fid[, sep, format]) | Write array to a file as text or binary (default).
tolist() | Return the array as a (possibly nested) list.
tostring([order]) | Construct Python bytes containing the raw data bytes in the array.
trace([offset, axis1, axis2, dtype, out]) | Return the sum along diagonals of the array.
transpose(*axes) | Returns a view of the array with axes transposed.
var([axis, dtype, out, ddof]) | Returns the variance of the array elements, along given axis.
view([dtype, type]) | New view of array with the same data.


numpy.ndarray.T

  • Routines
  • Array manipulation routines
  • index
  • next
  • previous

Previous topic

numpy.swapaxes

Next topic

numpy.transpose

numpy.ndarray.T

ndarray.T

Same as self.transpose(), except that self is returned if self.ndim < 2.

Examples

>>> x = np.array([[1.,2.],[3.,4.]])
>>> x
array([[ 1.,  2.],
       [ 3.,  4.]])
>>> x.T
array([[ 1.,  3.],
       [ 2.,  4.]])
>>> x = np.array([1.,2.,3.,4.])
>>> x
array([ 1.,  2.,  3.,  4.])
>>> x.T
array([ 1.,  2.,  3.,  4.])


numpy.ndarray.data

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.ndim

Next topic

numpy.ndarray.size

numpy.ndarray.data

ndarray.data

Python buffer object pointing to the start of the array’s data.


numpy.ndarray.dtype

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.base

Next topic

numpy.ndarray.T

numpy.ndarray.dtype

ndarray.dtype

Data-type of the array’s elements.

Parameters: None
Returns: d : numpy dtype object

See also

numpy.dtype

Examples

>>> x
array([[0, 1],
       [2, 3]])
>>> x.dtype
dtype('int32')
>>> type(x.dtype)
<type 'numpy.dtype'>


numpy.ndarray.flags

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.view

Next topic

numpy.ndarray.shape

numpy.ndarray.flags

ndarray.flags

Information about the memory layout of the array.

Notes

The flags object can be accessed dictionary-like (as in a.flags['WRITEABLE']), or by using lowercased attribute names (as in a.flags.writeable). Short flag names are only supported in dictionary access.

Only the UPDATEIFCOPY, WRITEABLE, and ALIGNED flags can be changed by the user, via direct assignment to the attribute or dictionary entry, or by calling ndarray.setflags.

The array flags cannot be set arbitrarily:

  • UPDATEIFCOPY can only be set False.
  • ALIGNED can only be set True if the data is truly aligned.
  • WRITEABLE can only be set True if the array owns its own memory or the ultimate owner of the memory exposes a writeable buffer interface or is a string.

Arrays can be both C-style and Fortran-style contiguous simultaneously. This is clear for 1-dimensional arrays, but can also be true for higher dimensional arrays.

Even for contiguous arrays a stride for a given dimension arr.strides[dim] may be arbitrary if arr.shape[dim] == 1 or the array has no elements. It does not generally hold that self.strides[-1] == self.itemsize for C-style contiguous arrays or self.strides[0] == self.itemsize for Fortran-style contiguous arrays is true.

Attributes

C_CONTIGUOUS (C) | The data is in a single, C-style contiguous segment.
F_CONTIGUOUS (F) | The data is in a single, Fortran-style contiguous segment.
OWNDATA (O) | The array owns the memory it uses or borrows it from another object.
WRITEABLE (W) | The data area can be written to. Setting this to False locks the data, making it read-only. A view (slice, etc.) inherits WRITEABLE from its base array at creation time, but a view of a writeable array may be subsequently locked while the base array remains writeable. (The opposite is not true, in that a view of a locked array may not be made writeable. However, currently, locking a base object does not lock any views that already reference it, so under that circumstance it is possible to alter the contents of a locked array via a previously created writeable view onto it.) Attempting to change a non-writeable array raises a RuntimeError exception.
ALIGNED (A) | The data and all elements are aligned appropriately for the hardware.
UPDATEIFCOPY (U) | This array is a copy of some other array. When this array is deallocated, the base array will be updated with the contents of this array.
FNC | F_CONTIGUOUS and not C_CONTIGUOUS.
FORC | F_CONTIGUOUS or C_CONTIGUOUS (one-segment test).
BEHAVED (B) | ALIGNED and WRITEABLE.
CARRAY (CA) | BEHAVED and C_CONTIGUOUS.
FARRAY (FA) | BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS.


numpy.ndarray.flat

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.ravel

Next topic

numpy.ndarray.flatten

numpy.ndarray.flat

ndarray.flat

A 1-D iterator over the array.

This is a numpy.flatiter instance, which acts similarly to, but is not a subclass of, Python’s built-in iterator object.

See also

flatten
Return a copy of the array collapsed into one dimension.

flatiter

Examples

>>> x = np.arange(1, 7).reshape(2, 3)
>>> x
array([[1, 2, 3],
       [4, 5, 6]])
>>> x.flat[3]
4
>>> x.T
array([[1, 4],
       [2, 5],
       [3, 6]])
>>> x.T.flat[3]
5
>>> type(x.flat)
<type 'numpy.flatiter'>

An assignment example:

>>> x.flat = 3; x
array([[3, 3, 3],
       [3, 3, 3]])
>>> x.flat[[1,4]] = 1; x
array([[3, 1, 3],
       [3, 1, 3]])


numpy.ndarray.imag

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.real

Next topic

numpy.ndarray.flat

numpy.ndarray.imag

ndarray.imag

The imaginary part of the array.

Examples

>>> x = np.sqrt([1+0j, 0+1j])
>>> x.imag
array([ 0.        ,  0.70710678])
>>> x.imag.dtype
dtype('float64')


numpy.ndarray.real

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.T

Next topic

numpy.ndarray.imag

numpy.ndarray.real

ndarray.real

The real part of the array.

See also

numpy.real
equivalent function

Examples

>>> x = np.sqrt([1+0j, 0+1j])
>>> x.real
array([ 1.        ,  0.70710678])
>>> x.real.dtype
dtype('float64')


numpy.ndarray.size

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.data

Next topic

numpy.ndarray.itemsize

numpy.ndarray.size

ndarray.size

Number of elements in the array.

Equivalent to np.prod(a.shape), i.e., the product of the array’s dimensions.

Examples

>>> x = np.zeros((3, 5, 2), dtype=np.complex128)
>>> x.size
30
>>> np.prod(x.shape)
30


numpy.ndarray.itemsize

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.size

Next topic

numpy.ndarray.nbytes

numpy.ndarray.itemsize

ndarray.itemsize

Length of one array element in bytes.

Examples

>>> x = np.array([1,2,3], dtype=np.float64)
>>> x.itemsize
8
>>> x = np.array([1,2,3], dtype=np.complex128)
>>> x.itemsize
16


numpy.ndarray.nbytes

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.itemsize

Next topic

numpy.ndarray.base

numpy.ndarray.nbytes

ndarray.nbytes

Total bytes consumed by the elements of the array.

Notes

Does not include memory consumed by non-element attributes of the array object.

Examples

>>> x = np.zeros((3,5,2), dtype=np.complex128)
>>> x.nbytes
480
>>> np.prod(x.shape) * x.itemsize
480


numpy.ndarray.ndim

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.strides

Next topic

numpy.ndarray.data

numpy.ndarray.ndim

ndarray.ndim

Number of array dimensions.

Examples

>>> x = np.array([1, 2, 3])
>>> x.ndim
1
>>> y = np.zeros((2, 3, 4))
>>> y.ndim
3


numpy.ndarray.shape

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.flags

Next topic

numpy.ndarray.strides

numpy.ndarray.shape

ndarray.shape

Tuple of array dimensions.

Notes

May be used to “reshape” the array, as long as this would not require a change in the total number of elements

Examples

>>> x = np.array([1, 2, 3, 4])
>>> x.shape
(4,)
>>> y = np.zeros((2, 3, 4))
>>> y.shape
(2, 3, 4)
>>> y.shape = (3, 8)
>>> y
array([[ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])
>>> y.shape = (3, 6)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: total size of new array must be unchanged


numpy.ndarray.strides

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.shape

Next topic

numpy.ndarray.ndim

numpy.ndarray.strides

ndarray.strides

Tuple of bytes to step in each dimension when traversing an array.

The byte offset of element (i[0], i[1], ..., i[n]) in an array a is:

offset = sum(np.array(i) * a.strides)

A more detailed explanation of strides can be found in the “ndarray.rst” file in the NumPy reference guide.

See also

numpy.lib.stride_tricks.as_strided

Notes

Imagine an array of 32-bit integers (each 4 bytes):

x = np.array([[0, 1, 2, 3, 4],
              [5, 6, 7, 8, 9]], dtype=np.int32)

This array is stored in memory as 40 bytes, one after the other (known as a contiguous block of memory). The strides of an array tell us how many bytes we have to skip in memory to move to the next position along a certain axis. For example, we have to skip 4 bytes (1 value) to move to the next column, but 20 bytes (5 values) to get to the same position in the next row. As such, the strides for the array x will be (20, 4).

Examples

>>> y = np.reshape(np.arange(2*3*4), (2,3,4))
>>> y
array([[[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]],
       [[12, 13, 14, 15],
        [16, 17, 18, 19],
        [20, 21, 22, 23]]])
>>> y.strides
(48, 16, 4)
>>> y[1,1,1]
17
>>> offset=sum(y.strides * np.array((1,1,1)))
>>> offset/y.itemsize
17

>>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0)
>>> x.strides
(32, 4, 224, 1344)
>>> i = np.array([3,5,2,2])
>>> offset = sum(i * x.strides)
>>> x[3,5,2,2]
813
>>> offset / x.itemsize
813


numpy.ndarray.ctypes

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next

Next topic

numpy.ndarray.item

numpy.ndarray.ctypes

ndarray.ctypes

An object to simplify the interaction of the array with the ctypes module.

This attribute creates an object that makes it easier to use arrays when calling shared libraries with the ctypes module. The returned object has, among others, data, shape, and strides attributes (see Notes below) which themselves return ctypes objects that can be used as arguments to a shared library.

Parameters:

None
Returns:

c : Python object

Possessing attributes data, shape, strides, etc.

See also

numpy.ctypeslib

Notes

Below are the public attributes of this object which were documented in “Guide to NumPy” (we have omitted undocumented public attributes, as well as documented private attributes):

  • data: A pointer to the memory area of the array as a Python integer. This memory area may contain data that is not aligned, or not in correct byte-order. The memory area may not even be writeable. The array flags and data-type of this array should be respected when passing this attribute to arbitrary C-code to avoid trouble that can include Python crashing. User Beware! The value of this attribute is exactly the same as self._array_interface_[‘data’][0].
  • shape (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the C-integer corresponding to dtype(‘p’) on this platform. This base-type could be c_int, c_long, or c_longlong depending on the platform. The c_intp type is defined accordingly in numpy.ctypeslib. The ctypes array contains the shape of the underlying array.
  • strides (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the same as for the shape attribute. This ctypes array contains the strides information from the underlying array. This strides information is important for showing how many bytes must be jumped to get to the next element in the array.
  • data_as(obj): Return the data pointer cast to a particular c-types object. For example, calling self._as_parameter_ is equivalent to self.data_as(ctypes.c_void_p). Perhaps you want to use the data as a pointer to a ctypes array of floating-point data: self.data_as(ctypes.POINTER(ctypes.c_double)).
  • shape_as(obj): Return the shape tuple as an array of some other c-types type. For example: self.shape_as(ctypes.c_short).
  • strides_as(obj): Return the strides tuple as an array of some other c-types type. For example: self.strides_as(ctypes.c_longlong).

Be careful using the ctypes attribute - especially on temporary arrays or arrays constructed on the fly. For example, calling (a+b).ctypes.data_as(ctypes.c_void_p) returns a pointer to memory that is invalid because the array created as (a+b) is deallocated before the next Python statement. You can avoid this problem using either c=a+b or ct=(a+b).ctypes. In the latter case, ct will hold a reference to the array until ct is deleted or re-assigned.

If the ctypes module is not available, then the ctypes attribute of array objects still returns something useful, but ctypes objects are not returned and errors may be raised instead. In particular, the object will still have the as parameter attribute which will return an integer equal to the data attribute.

Examples

>>> import ctypes
>>> x
array([[0, 1],
       [2, 3]])
>>> x.ctypes.data
30439712
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long))
<ctypes.LP_c_long object at 0x01F01300>
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long)).contents
c_long(0)
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_longlong)).contents
c_longlong(4294967296L)
>>> x.ctypes.shape
<numpy.core._internal.c_long_Array_2 object at 0x01FFD580>
>>> x.ctypes.shape_as(ctypes.c_long)
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides_as(ctypes.c_longlong)
<numpy.core._internal.c_longlong_Array_2 object at 0x01F01300>


numpy.ndarray.base

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.nbytes

Next topic

numpy.ndarray.dtype

numpy.ndarray.base

ndarray.base

Base object if memory is from some other object.

Examples

The base of an array that owns its memory is None:

>>> x = np.array([1,2,3,4])
>>> x.base is None
True

Slicing creates a view, whose memory is shared with x:

>>> y = x[2:]
>>> y.base is x
True


numpy.ndarray.all

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.cumprod

Next topic

numpy.ndarray.any

numpy.ndarray.all

ndarray.all(axis=None, out=None)

Returns True if all elements evaluate to True.

Refer to numpy.all for full documentation.

See also

numpy.all
equivalent function


numpy.ndarray.any

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.all

Next topic

numpy.ndarray.__lt__

numpy.ndarray.any

ndarray.any(axis=None, out=None)

Returns True if any of the elements of a evaluate to True.

Refer to numpy.any for full documentation.

See also

numpy.any
equivalent function


numpy.ndarray.argmax

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.diagonal

Next topic

numpy.ndarray.min

numpy.ndarray.argmax

ndarray.argmax(axis=None, out=None)

Return indices of the maximum values along the given axis.

Refer to numpy.argmax for full documentation.

See also

numpy.argmax
equivalent function


numpy.ndarray.argmin

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.min

Next topic

numpy.ndarray.ptp

numpy.ndarray.argmin

ndarray.argmin(axis=None, out=None)

Return indices of the minimum values along the given axis of a.

Refer to numpy.argmin for detailed documentation.

See also

numpy.argmin
equivalent function


numpy.ndarray.argpartition

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.partition

Next topic

numpy.ndarray.searchsorted

numpy.ndarray.argpartition

ndarray.argpartition(kth, axis=-1, kind='introselect', order=None)

Returns the indices that would partition this array.

Refer to numpy.argpartition for full documentation.

New in version 1.8.0.

See also

numpy.argpartition
equivalent function


numpy.ndarray.argsort

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.sort

Next topic

numpy.ndarray.partition

numpy.ndarray.argsort

ndarray.argsort(axis=-1, kind='quicksort', order=None)

Returns the indices that would sort this array.

Refer to numpy.argsort for full documentation.

See also

numpy.argsort
equivalent function


numpy.ndarray.astype

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.dumps

Next topic

numpy.ndarray.byteswap

numpy.ndarray.astype

ndarray.astype(dtype, order='K', casting='unsafe', subok=True, copy=True)

Copy of the array, cast to a specified type.

Parameters:

dtype : str or dtype

Typecode or data-type to which the array is cast.

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout order of the result. ‘C’ means C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran contiguous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements appear in memory as possible. Default is ‘K’.

casting : {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

Controls what kind of data casting may occur. Defaults to ‘unsafe’ for backwards compatibility.

  • ‘no’ means the data types should not be cast at all.
  • ‘equiv’ means only byte-order changes are allowed.
  • ‘safe’ means only casts which can preserve values are allowed.
  • ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.
  • ‘unsafe’ means any data conversions may be done.

subok : bool, optional

If True, then sub-classes will be passed-through (default), otherwise the returned array will be forced to be a base-class array.

copy : bool, optional

By default, astype always returns a newly allocated array. If this is set to false, and the dtype, order, and subok requirements are satisfied, the input array is returned instead of a copy.
Returns:

arr_t : ndarray

Unless copy is False and the other conditions for returning the input array are satisfied (see description for copy input paramter), arr_t is a new array of the same shape as the input array, with dtype, order given by dtype, order.
Raises:

ComplexWarning

When casting from complex to float or int. To avoid this, one should use a.real.astype(t).

Notes

Starting in NumPy 1.9, astype method now returns an error if the string dtype to cast to is not long enough in ‘safe’ casting mode to hold the max value of integer/float array that is being casted. Previously the casting was allowed even if the result was truncated.

Examples

>>> x = np.array([1, 2, 2.5])
>>> x
array([ 1. ,  2. ,  2.5])

>>> x.astype(int)
array([1, 2, 2])


numpy.ndarray.byteswap

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.astype

Next topic

numpy.ndarray.copy

numpy.ndarray.byteswap

ndarray.byteswap(inplace)

Swap the bytes of the array elements

Toggle between low-endian and big-endian data representation by returning a byteswapped array, optionally swapped in-place.

Parameters:

inplace : bool, optional

If True, swap bytes in-place, default is False.
Returns:

out : ndarray

The byteswapped array. If inplace is True, this is a view to self.

Examples

>>> A = np.array([1, 256, 8755], dtype=np.int16)
>>> map(hex, A)
['0x1', '0x100', '0x2233']
>>> A.byteswap(True)
array([  256,     1, 13090], dtype=int16)
>>> map(hex, A)
['0x100', '0x1', '0x3322']

Arrays of strings are not swapped

>>> A = np.array(['ceg', 'fac'])
>>> A.byteswap()
array(['ceg', 'fac'],
      dtype='|S3')


numpy.ndarray.choose

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.repeat

Next topic

numpy.ndarray.sort

numpy.ndarray.choose

ndarray.choose(choices, out=None, mode='raise')

Use an index array to construct a new array from a set of choices.

Refer to numpy.choose for full documentation.

See also

numpy.choose
equivalent function


numpy.ndarray.clip

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.ptp

Next topic

numpy.ndarray.conj

numpy.ndarray.clip

ndarray.clip(a_min, a_max, out=None)

Return an array whose values are limited to [a_min, a_max].

Refer to numpy.clip for full documentation.

See also

numpy.clip
equivalent function


numpy.ndarray.compress

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.nonzero

Next topic

numpy.ndarray.diagonal

numpy.ndarray.compress

ndarray.compress(condition, axis=None, out=None)

Return selected slices of this array along given axis.

Refer to numpy.compress for full documentation.

See also

numpy.compress
equivalent function


numpy.ndarray.conj

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.clip

Next topic

numpy.ndarray.round

numpy.ndarray.conj

ndarray.conj()

Complex-conjugate all elements.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.ndarray.conjugate

  • Array objects
  • The N-dimensional array (ndarray)
  • numpy.ndarray
  • index
  • next
  • previous

Previous topic

numpy.ndarray.conj

Next topic

numpy.ndarray.copy

numpy.ndarray.conjugate

ndarray.conjugate()

Return the complex conjugate, element-wise.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.ndarray.copy

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.byteswap

Next topic

numpy.ndarray.view

numpy.ndarray.copy

ndarray.copy(order='C')

Return a copy of the array.

Parameters:

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout of the copy. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible. (Note that this function and :func:numpy.copy are very similar, but have different default values for their order= arguments.)

See also

numpy.copy, numpy.copyto

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
       [0, 0, 0]])

>>> y
array([[1, 2, 3],
       [4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True


numpy.ndarray.cumprod

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.prod

Next topic

numpy.ndarray.all

numpy.ndarray.cumprod

ndarray.cumprod(axis=None, dtype=None, out=None)

Return the cumulative product of the elements along the given axis.

Refer to numpy.cumprod for full documentation.

See also

numpy.cumprod
equivalent function


numpy.ndarray.cumsum

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.sum

Next topic

numpy.ndarray.mean

numpy.ndarray.cumsum

ndarray.cumsum(axis=None, dtype=None, out=None)

Return the cumulative sum of the elements along the given axis.

Refer to numpy.cumsum for full documentation.

See also

numpy.cumsum
equivalent function


numpy.ndarray.diagonal

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.compress

Next topic

numpy.ndarray.argmax

numpy.ndarray.diagonal

ndarray.diagonal(offset=0, axis1=0, axis2=1)

Return specified diagonals. In NumPy 1.9 the returned array is a read-only view instead of a copy as in previous NumPy versions. In NumPy 1.10 the read-only restriction will be removed.

Refer to numpy.diagonal for full documentation.

See also

numpy.diagonal
equivalent function


numpy.ndarray.dot

  • Array objects
  • The N-dimensional array (ndarray)
  • numpy.ndarray
  • index
  • next
  • previous

Previous topic

numpy.ndarray.diagonal

Next topic

numpy.ndarray.dump

numpy.ndarray.dot

ndarray.dot(b, out=None)

Dot product of two arrays.

Refer to numpy.dot for full documentation.

See also

numpy.dot
equivalent function

Examples

>>> a = np.eye(2)
>>> b = np.ones((2, 2)) * 2
>>> a.dot(b)
array([[ 2.,  2.],
       [ 2.,  2.]])

This array method can be conveniently chained:

>>> a.dot(b).dot(b)
array([[ 8.,  8.],
       [ 8.,  8.]])


numpy.ndarray.dump

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.tofile

Next topic

numpy.ndarray.dumps

numpy.ndarray.dump

ndarray.dump(file)

Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.

Parameters:

file : str

A string naming the dump file.


numpy.ndarray.dumps

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.dump

Next topic

numpy.ndarray.astype

numpy.ndarray.dumps

ndarray.dumps()

Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an array.

Parameters: None


numpy.ndarray.fill

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.setflags

Next topic

numpy.ndarray.reshape

numpy.ndarray.fill

ndarray.fill(value)

Fill the array with a scalar value.

Parameters:

value : scalar

All elements of a will be assigned this value.

Examples

>>> a = np.array([1, 2])
>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([ 1.,  1.])


numpy.ndarray.flatten

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.ndarray.flat

Next topic

numpy.rollaxis

numpy.ndarray.flatten

ndarray.flatten(order='C')

Return a copy of the array collapsed into one dimension.

Parameters:

order : {‘C’, ‘F’, ‘A’}, optional

Whether to flatten in C (row-major), Fortran (column-major) order, or preserve the C/Fortran ordering from a. The default is ‘C’.
Returns:

y : ndarray

A copy of the input array, flattened to one dimension.

See also

ravel
Return a flattened array.
flat
A 1-D flat iterator over the array.

Examples

>>> a = np.array([[1,2], [3,4]])
>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten('F')
array([1, 3, 2, 4])


numpy.ndarray.getfield

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.view

Next topic

numpy.ndarray.setflags

numpy.ndarray.getfield

ndarray.getfield(dtype, offset=0)

Returns a field of the given array as a certain type.

A field is a view of the array data with a given data-type. The values in the view are determined by the given type and the offset into the current array in bytes. The offset needs to be such that the view dtype fits in the array dtype; for example an array of dtype complex128 has 16-byte elements. If taking a view with a 32-bit integer (4 bytes), the offset needs to be between 0 and 12 bytes.

Parameters:

dtype : str or dtype

The data type of the view. The dtype size of the view can not be larger than that of the array itself.

offset : int

Number of bytes to skip before beginning the element view.

Examples

>>> x = np.diag([1.+1.j]*2)
>>> x[1, 1] = 2 + 4.j
>>> x
array([[ 1.+1.j,  0.+0.j],
       [ 0.+0.j,  2.+4.j]])
>>> x.getfield(np.float64)
array([[ 1.,  0.],
       [ 0.,  2.]])

By choosing an offset of 8 bytes we can select the complex part of the array for our view:

>>> x.getfield(np.float64, offset=8)
array([[ 1.,  0.],
   [ 0.,  4.]])


numpy.ndarray.item

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.ctypes

Next topic

numpy.ndarray.tolist

numpy.ndarray.item

ndarray.item(*args)

Copy an element of an array to a standard Python scalar and return it.

Parameters:

*args : Arguments (variable number and type)

  • none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.
  • int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.
  • tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.
Returns:

z : Standard Python scalar object

A copy of the specified element of the array as a suitable Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.item(3)
2
>>> x.item(7)
5
>>> x.item((0, 1))
1
>>> x.item((2, 2))
3


numpy.ndarray.itemset

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • previous

Previous topic

numpy.ndarray.tolist

numpy.ndarray.itemset

ndarray.itemset(*args)

Insert scalar into an array (scalar is cast to array’s dtype, if possible)

There must be at least 1 argument, and define the last argument as item. Then, a.itemset(*args) is equivalent to but faster than a[args] = item. The item should be a scalar value and args must select a single item in the array a.

Parameters:

*args : Arguments

If one argument: a scalar, only used in case a is of size 1. If two arguments: the last argument is the value to be set and must be a scalar, the first argument specifies a single array element location. It is either an int or a tuple.

Notes

Compared to indexing syntax, itemset provides some speed increase for placing a scalar into a particular location in an ndarray, if you must do this. However, generally this is discouraged: among other problems, it complicates the appearance of the code. Also, when using itemset (and item) inside a loop, be sure to assign the methods to a local variable to avoid the attribute look-up at each loop iteration.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.itemset(4, 0)
>>> x.itemset((2, 2), 9)
>>> x
array([[3, 1, 7],
       [2, 0, 3],
       [8, 5, 9]])


numpy.ndarray.max

  • Array objects
  • The N-dimensional array (ndarray)
  • numpy.ndarray
  • index
  • next
  • previous

Previous topic

numpy.ndarray.itemset

Next topic

numpy.ndarray.mean

numpy.ndarray.max

ndarray.max(axis=None, out=None)

Return the maximum along a given axis.

Refer to numpy.amax for full documentation.

See also

numpy.amax
equivalent function


numpy.ndarray.mean

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.cumsum

Next topic

numpy.ndarray.var

numpy.ndarray.mean

ndarray.mean(axis=None, dtype=None, out=None)

Returns the average of the array elements along given axis.

Refer to numpy.mean for full documentation.

See also

numpy.mean
equivalent function


numpy.ndarray.min

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.argmax

Next topic

numpy.ndarray.argmin

numpy.ndarray.min

ndarray.min(axis=None, out=None)

Return the minimum along a given axis.

Refer to numpy.amin for full documentation.

See also

numpy.amin
equivalent function


numpy.ndarray.newbyteorder

  • Array objects
  • The N-dimensional array (ndarray)
  • numpy.ndarray
  • index
  • next
  • previous

Previous topic

numpy.ndarray.min

Next topic

numpy.ndarray.nonzero

numpy.ndarray.newbyteorder

ndarray.newbyteorder(new_order='S')

Return the array with the same data viewed with a different byte order.

Equivalent to:

arr.view(arr.dtype.newbytorder(new_order))

Changes are also made in all fields and sub-arrays of the array data type.

Parameters:

new_order : string, optional

Byte order to force; a value from the byte order specifications above. new_order codes can be any of:

* 'S' - swap dtype from current to opposite endian
* {'<', 'L'} - little endian
* {'>', 'B'} - big endian
* {'=', 'N'} - native order
* {'|', 'I'} - ignore (no change to byte order)

The default value (‘S’) results in swapping the current byte order. The code does a case-insensitive check on the first letter of new_order for the alternatives above. For example, any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns:

new_arr : array

New array object with the dtype reflecting given change to the byte order.


numpy.ndarray.nonzero

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.searchsorted

Next topic

numpy.ndarray.compress

numpy.ndarray.nonzero

ndarray.nonzero()

Return the indices of the elements that are non-zero.

Refer to numpy.nonzero for full documentation.

See also

numpy.nonzero
equivalent function


numpy.ndarray.partition

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.argsort

Next topic

numpy.ndarray.argpartition

numpy.ndarray.partition

ndarray.partition(kth, axis=-1, kind='introselect', order=None)

Rearranges the elements in the array in such a way that value of the element in kth position is in the position it would be in a sorted array. All elements smaller than the kth element are moved before this element and all equal or greater are moved behind it. The ordering of the elements in the two partitions is undefined.

New in version 1.8.0.

Parameters:

kth : int or sequence of ints

Element index to partition by. The kth element value will be in its final sorted position and all smaller elements will be moved before it and all equal or greater elements behind it. The order all elements in the partitions is undefined. If provided with a sequence of kth it will partition all elements indexed by kth of them into their sorted position at once.

axis : int, optional

Axis along which to sort. Default is -1, which means sort along the last axis.

kind : {‘introselect’}, optional

Selection algorithm. Default is ‘introselect’.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.

See also

numpy.partition
Return a parititioned copy of an array.
argpartition
Indirect partition.
sort
Full sort.

Notes

See np.partition for notes on the different algorithms.

Examples

>>> a = np.array([3, 4, 2, 1])
>>> a.partition(a, 3)
>>> a
array([2, 1, 3, 4])

>>> a.partition((1, 3))
array([1, 2, 3, 4])


numpy.ndarray.prod

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.std

Next topic

numpy.ndarray.cumprod

numpy.ndarray.prod

ndarray.prod(axis=None, dtype=None, out=None)

Return the product of the array elements over the given axis

Refer to numpy.prod for full documentation.

See also

numpy.prod
equivalent function


numpy.ndarray.ptp

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.argmin

Next topic

numpy.ndarray.clip

numpy.ndarray.ptp

ndarray.ptp(axis=None, out=None)

Peak to peak (maximum - minimum) value along a given axis.

Refer to numpy.ptp for full documentation.

See also

numpy.ptp
equivalent function


numpy.ndarray.put

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.take

Next topic

numpy.ndarray.repeat

numpy.ndarray.put

ndarray.put(indices, values, mode='raise')

Set a.flat[n] = values[n] for all n in indices.

Refer to numpy.put for full documentation.

See also

numpy.put
equivalent function


numpy.ndarray.ravel

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.flatten

Next topic

numpy.ndarray.squeeze

numpy.ndarray.ravel

ndarray.ravel([order])

Return a flattened array.

Refer to numpy.ravel for full documentation.

See also

numpy.ravel
equivalent function
ndarray.flat
a flat iterator on the array.


numpy.ndarray.repeat

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.put

Next topic

numpy.ndarray.choose

numpy.ndarray.repeat

ndarray.repeat(repeats, axis=None)

Repeat elements of an array.

Refer to numpy.repeat for full documentation.

See also

numpy.repeat
equivalent function


numpy.ndarray.reshape

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.fill

Next topic

numpy.ndarray.resize

numpy.ndarray.reshape

ndarray.reshape(shape, order='C')

Returns an array containing the same data with a new shape.

Refer to numpy.reshape for full documentation.

See also

numpy.reshape
equivalent function


numpy.ndarray.resize

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.reshape

Next topic

numpy.ndarray.transpose

numpy.ndarray.resize

ndarray.resize(new_shape, refcheck=True)

Change shape and size of array in-place.

Parameters:

new_shape : tuple of ints, or n ints

Shape of resized array.

refcheck : bool, optional

If False, reference count will not be checked. Default is True.
Returns:

None
Raises:

ValueError

If a does not own its own data or references or views to it exist, and the data memory must be changed.

SystemError

If the order keyword argument is specified. This behaviour is a bug in NumPy.

See also

resize
Return a new array with the specified shape.

Notes

This reallocates space for the data area if necessary.

Only contiguous arrays (data elements consecutive in memory) can be resized.

The purpose of the reference count check is to make sure you do not use this array as a buffer for another Python object and then reallocate the memory. However, reference counts can increase in other ways so if you are sure that you have not shared the memory for this array with another Python object, then you may safely set refcheck to False.

Examples

Shrinking an array: array is flattened (in the order that the data are stored in memory), resized, and reshaped:

>>> a = np.array([[0, 1], [2, 3]], order='C')
>>> a.resize((2, 1))
>>> a
array([[0],
       [1]])

>>> a = np.array([[0, 1], [2, 3]], order='F')
>>> a.resize((2, 1))
>>> a
array([[0],
       [2]])

Enlarging an array: as above, but missing entries are filled with zeros:

>>> b = np.array([[0, 1], [2, 3]])
>>> b.resize(2, 3) # new_shape parameter doesn't have to be a tuple
>>> b
array([[0, 1, 2],
       [3, 0, 0]])

Referencing an array prevents resizing...

>>> c = a
>>> a.resize((1, 1))
Traceback (most recent call last):
...
ValueError: cannot resize an array that has been referenced ...

Unless refcheck is False:

>>> a.resize((1, 1), refcheck=False)
>>> a
array([[0]])
>>> c
array([[0]])


numpy.ndarray.round

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.conj

Next topic

numpy.ndarray.trace

numpy.ndarray.round

ndarray.round(decimals=0, out=None)

Return a with each element rounded to the given number of decimals.

Refer to numpy.around for full documentation.

See also

numpy.around
equivalent function


numpy.ndarray.searchsorted

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.argpartition

Next topic

numpy.ndarray.nonzero

numpy.ndarray.searchsorted

ndarray.searchsorted(v, side='left', sorter=None)

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See also

numpy.searchsorted
equivalent function


numpy.ndarray.setfield

  • Array objects
  • The N-dimensional array (ndarray)
  • numpy.ndarray
  • index
  • next
  • previous

Previous topic

numpy.ndarray.searchsorted

Next topic

numpy.ndarray.setflags

numpy.ndarray.setfield

ndarray.setfield(val, dtype, offset=0)

Put a value into a specified place in a field defined by a data-type.

Place val into a‘s field defined by dtype and beginning offset bytes into the field.

Parameters:

val : object

Value to be placed in field.

dtype : dtype object

Data-type of the field in which to place val.

offset : int, optional

The number of bytes into the field at which to place val.
Returns:

None

See also

getfield

Examples

>>> x = np.eye(3)
>>> x.getfield(np.float64)
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
>>> x.setfield(3, np.int32)
>>> x.getfield(np.int32)
array([[3, 3, 3],
       [3, 3, 3],
       [3, 3, 3]])
>>> x
array([[  1.00000000e+000,   1.48219694e-323,   1.48219694e-323],
       [  1.48219694e-323,   1.00000000e+000,   1.48219694e-323],
       [  1.48219694e-323,   1.48219694e-323,   1.00000000e+000]])
>>> x.setfield(np.eye(3), np.int32)
>>> x
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])


numpy.ndarray.setflags

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.getfield

Next topic

numpy.ndarray.fill

numpy.ndarray.setflags

ndarray.setflags(write=None, align=None, uic=None)

Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively.

These Boolean-valued flags affect how numpy interprets the memory area used by a (see Notes below). The ALIGNED flag can only be set to True if the data is actually aligned according to the type. The UPDATEIFCOPY flag can never be set to True. The flag WRITEABLE can only be set to True if the array owns its own memory, or the ultimate owner of the memory exposes a writeable buffer interface, or is a string. (The exception for string is made so that unpickling can be done without copying memory.)

Parameters:

write : bool, optional

Describes whether or not a can be written to.

align : bool, optional

Describes whether or not a is aligned properly for its type.

uic : bool, optional

Describes whether or not a is a copy of another “base” array.

Notes

Array flags provide information about how the memory area used for the array is to be interpreted. There are 6 Boolean flags in use, only three of which can be changed by the user: UPDATEIFCOPY, WRITEABLE, and ALIGNED.

WRITEABLE (W) the data area can be written to;

ALIGNED (A) the data and strides are aligned appropriately for the hardware (as determined by the compiler);

UPDATEIFCOPY (U) this array is a copy of some other array (referenced by .base). When this array is deallocated, the base array will be updated with the contents of this array.

All flags can be accessed using their first (upper case) letter as well as the full name.

Examples

>>> y
array([[3, 1, 7],
       [2, 0, 0],
       [8, 5, 9]])
>>> y.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : True
  WRITEABLE : True
  ALIGNED : True
  UPDATEIFCOPY : False
>>> y.setflags(write=0, align=0)
>>> y.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : True
  WRITEABLE : False
  ALIGNED : False
  UPDATEIFCOPY : False
>>> y.setflags(uic=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: cannot set UPDATEIFCOPY flag to True


numpy.ndarray.sort

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.argsort

Next topic

numpy.msort

numpy.ndarray.sort

ndarray.sort(axis=-1, kind='quicksort', order=None)

Sort an array, in-place.

Parameters:

axis : int, optional

Axis along which to sort. Default is -1, which means sort along the last axis.

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm. Default is ‘quicksort’.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.

See also

numpy.sort
Return a sorted copy of an array.
argsort
Indirect sort.
lexsort
Indirect stable sort on multiple keys.
searchsorted
Find elements in sorted array.
partition
Partial sort.

Notes

See sort for notes on the different sorting algorithms.

Examples

>>> a = np.array([[1,4], [3,1]])
>>> a.sort(axis=1)
>>> a
array([[1, 4],
       [1, 3]])
>>> a.sort(axis=0)
>>> a
array([[1, 3],
       [1, 4]])

Use the order keyword to specify a field to use when sorting a structured array:

>>> a = np.array([('a', 2), ('c', 1)], dtype=[('x', 'S1'), ('y', int)])
>>> a.sort(order='y')
>>> a
array([('c', 1), ('a', 2)],
      dtype=[('x', '|S1'), ('y', '<i4')])


numpy.ndarray.squeeze

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.ravel

Next topic

numpy.ndarray.take

numpy.ndarray.squeeze

ndarray.squeeze(axis=None)

Remove single-dimensional entries from the shape of a.

Refer to numpy.squeeze for full documentation.

See also

numpy.squeeze
equivalent function


numpy.ndarray.std

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.var

Next topic

numpy.ndarray.prod

numpy.ndarray.std

ndarray.std(axis=None, dtype=None, out=None, ddof=0)

Returns the standard deviation of the array elements along given axis.

Refer to numpy.std for full documentation.

See also

numpy.std
equivalent function


numpy.ndarray.sum

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.trace

Next topic

numpy.ndarray.cumsum

numpy.ndarray.sum

ndarray.sum(axis=None, dtype=None, out=None)

Return the sum of the array elements over the given axis.

Refer to numpy.sum for full documentation.

See also

numpy.sum
equivalent function


numpy.ndarray.swapaxes

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.transpose

Next topic

numpy.ndarray.flatten

numpy.ndarray.swapaxes

ndarray.swapaxes(axis1, axis2)

Return a view of the array with axis1 and axis2 interchanged.

Refer to numpy.swapaxes for full documentation.

See also

numpy.swapaxes
equivalent function


numpy.ndarray.take

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.squeeze

Next topic

numpy.ndarray.put

numpy.ndarray.take

ndarray.take(indices, axis=None, out=None, mode='raise')

Return an array formed from the elements of a at the given indices.

Refer to numpy.take for full documentation.

See also

numpy.take
equivalent function


numpy.ndarray.tobytes

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.tostring

Next topic

numpy.ndarray.tofile

numpy.ndarray.tobytes

ndarray.tobytes(order='C')

Construct Python bytes containing the raw data bytes in the array.

Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.

New in version 1.9.0.

Parameters:

order : {‘C’, ‘F’, None}, optional

Order of the data for multidimensional arrays: C, Fortran, or the same as for the original array.
Returns:

s : bytes

Python bytes exhibiting a copy of a‘s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]])
>>> x.tobytes()
b'\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x03\x00\x00\x00'


numpy.ndarray.tofile

  • Input and output
  • next
  • previous

Previous topic

numpy.fromstring

Next topic

numpy.ndarray.tolist

numpy.ndarray.tofile

ndarray.tofile(fid, sep="", format="%s")

Write array to a file as text or binary (default).

Data is always written in ‘C’ order, independent of the order of a. The data produced by this method can be recovered using the function fromfile().

Parameters:

fid : file or str

An open file object, or a string containing a filename.

sep : str

Separator between array items for text output. If “” (empty), a binary file is written, equivalent to file.write(a.tobytes()).

format : str

Format string for text file output. Each entry in the array is formatted to text by first converting it to the closest Python type, and then using “format” % item.

Notes

This is a convenience function for quick storage of array data. Information on endianness and precision is lost, so this method is not a good choice for files intended to archive data or transport data between machines with different endianness. Some of these problems can be overcome by outputting the data as text files, at the expense of speed and file size.


numpy.ndarray.tolist

  • Input and output
  • next
  • previous

Previous topic

numpy.ndarray.tofile

Next topic

numpy.array_repr

numpy.ndarray.tolist

ndarray.tolist()

Return the array as a (possibly nested) list.

Return a copy of the array data as a (nested) Python list. Data items are converted to the nearest compatible Python type.

Parameters:

none
Returns:

y : list

The possibly nested list of array elements.

Notes

The array may be recreated, a = np.array(a.tolist()).

Examples

>>> a = np.array([1, 2])
>>> a.tolist()
[1, 2]
>>> a = np.array([[1, 2], [3, 4]])
>>> list(a)
[array([1, 2]), array([3, 4])]
>>> a.tolist()
[[1, 2], [3, 4]]


numpy.ndarray.tostring

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next

Next topic

numpy.ndarray.tobytes

numpy.ndarray.tostring

ndarray.tostring(order='C')

Construct Python bytes containing the raw data bytes in the array.

Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.

This function is a compatibility alias for tobytes. Despite its name it returns bytes not strings.

Parameters:

order : {‘C’, ‘F’, None}, optional

Order of the data for multidimensional arrays: C, Fortran, or the same as for the original array.
Returns:

s : bytes

Python bytes exhibiting a copy of a‘s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]])
>>> x.tobytes()
b'\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x03\x00\x00\x00'


numpy.ndarray.trace

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.round

Next topic

numpy.ndarray.sum

numpy.ndarray.trace

ndarray.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)

Return the sum along diagonals of the array.

Refer to numpy.trace for full documentation.

See also

numpy.trace
equivalent function


numpy.ndarray.transpose

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.resize

Next topic

numpy.ndarray.swapaxes

numpy.ndarray.transpose

ndarray.transpose(*axes)

Returns a view of the array with axes transposed.

For a 1-D array, this has no effect. (To change between column and row vectors, first cast the 1-D array into a matrix object.) For a 2-D array, this is the usual matrix transpose. For an n-D array, if axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided and a.shape = (i[0], i[1], ... i[n-2], i[n-1]), then a.transpose().shape = (i[n-1], i[n-2], ... i[1], i[0]).

Parameters:

axes : None, tuple of ints, or n ints

  • None or no argument: reverses the order of the axes.
  • tuple of ints: i in the j-th place in the tuple means a‘s i-th axis becomes a.transpose()‘s j-th axis.
  • n ints: same as an n-tuple of the same ints (this form is intended simply as a “convenience” alternative to the tuple form)
Returns:

out : ndarray

View of a, with axes suitably permuted.

See also

ndarray.T
Array property returning the array transposed.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> a
array([[1, 2],
       [3, 4]])
>>> a.transpose()
array([[1, 3],
       [2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
       [2, 4]])
>>> a.transpose(1, 0)
array([[1, 3],
       [2, 4]])


numpy.ndarray.var

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.mean

Next topic

numpy.ndarray.std

numpy.ndarray.var

ndarray.var(axis=None, dtype=None, out=None, ddof=0)

Returns the variance of the array elements, along given axis.

Refer to numpy.var for full documentation.

See also

numpy.var
equivalent function


numpy.ndarray.view

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.copy

Next topic

numpy.ndarray.getfield

numpy.ndarray.view

ndarray.view(dtype=None, type=None)

New view of array with the same data.

Parameters:

dtype : data-type or ndarray sub-class, optional

Data-type descriptor of the returned view, e.g., float32 or int16. The default, None, results in the view having the same data-type as a. This argument can also be specified as an ndarray sub-class, which then specifies the type of the returned object (this is equivalent to setting the type parameter).

type : Python type, optional

Type of the returned view, e.g., ndarray or matrix. Again, the default None results in type preservation.

Notes

a.view() is used two different ways:

a.view(some_dtype) or a.view(dtype=some_dtype) constructs a view of the array’s memory with a different data-type. This can cause a reinterpretation of the bytes of memory.

a.view(ndarray_subclass) or a.view(type=ndarray_subclass) just returns an instance of ndarray_subclass that looks at the same array (same shape, dtype, etc.) This does not cause a reinterpretation of the memory.

For a.view(some_dtype), if some_dtype has a different number of bytes per entry than the previous dtype (for example, converting a regular array to a structured array), then the behavior of the view cannot be predicted just from the superficial appearance of a (shown by print(a)). It also depends on exactly how a is stored in memory. Therefore if a is C-ordered versus fortran-ordered, versus defined as a slice or transpose, etc., the view may give different results.

Examples

>>> x = np.array([(1, 2)], dtype=[('a', np.int8), ('b', np.int8)])

Viewing array data using a different type and dtype:

>>> y = x.view(dtype=np.int16, type=np.matrix)
>>> y
matrix([[513]], dtype=int16)
>>> print type(y)
<class 'numpy.matrixlib.defmatrix.matrix'>

Creating a view on a structured array so it can be used in calculations

>>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)])
>>> xv = x.view(dtype=np.int8).reshape(-1,2)
>>> xv
array([[1, 2],
       [3, 4]], dtype=int8)
>>> xv.mean(0)
array([ 2.,  3.])

Making changes to the view changes the underlying array

>>> xv[0,1] = 20
>>> print x
[(1, 20) (3, 4)]

Using a view to convert an array to a record array:

>>> z = x.view(np.recarray)
>>> z.a
array([1], dtype=int8)

Views share data:

>>> x[0] = (9, 10)
>>> z[0]
(9, 10)

Views that change the dtype size (bytes per entry) should normally be avoided on arrays defined by slices, transposes, fortran-ordering, etc.:

>>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16)
>>> y = x[:, 0:2]
>>> y
array([[1, 2],
       [4, 5]], dtype=int16)
>>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: new type not compatible with array.
>>> z = y.copy()
>>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
array([[(1, 2)],
       [(4, 5)]], dtype=[('width', '<i2'), ('length', '<i2')])


numpy.ndarray.__lt__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.any

Next topic

numpy.ndarray.__le__

numpy.ndarray.__lt__

ndarray.__lt__

x.__lt__(y) <==> x<y


numpy.ndarray.__le__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__lt__

Next topic

numpy.ndarray.__gt__

numpy.ndarray.__le__

ndarray.__le__

x.__le__(y) <==> x<=y


numpy.ndarray.__gt__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__le__

Next topic

numpy.ndarray.__ge__

numpy.ndarray.__gt__

ndarray.__gt__

x.__gt__(y) <==> x>y


numpy.ndarray.__ge__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__gt__

Next topic

numpy.ndarray.__eq__

numpy.ndarray.__ge__

ndarray.__ge__

x.__ge__(y) <==> x>=y


numpy.ndarray.__eq__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__ge__

Next topic

numpy.ndarray.__ne__

numpy.ndarray.__eq__

ndarray.__eq__

x.__eq__(y) <==> x==y


numpy.ndarray.__ne__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__eq__

Next topic

numpy.ndarray.__nonzero__

numpy.ndarray.__ne__

ndarray.__ne__

x.__ne__(y) <==> x!=y


numpy.ndarray.__nonzero__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__ne__

Next topic

numpy.ndarray.__neg__

numpy.ndarray.__nonzero__

ndarray.__nonzero__

x.__nonzero__() <==> x != 0


numpy.ndarray.__neg__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__nonzero__

Next topic

numpy.ndarray.__pos__

numpy.ndarray.__neg__

ndarray.__neg__

x.__neg__() <==> -x


numpy.ndarray.__pos__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__neg__

Next topic

numpy.ndarray.__abs__

numpy.ndarray.__pos__

ndarray.__pos__

x.__pos__() <==> +x


numpy.ndarray.__abs__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__pos__

Next topic

numpy.ndarray.__invert__

numpy.ndarray.__abs__

ndarray.__abs__() <==> abs(x)


numpy.ndarray.__invert__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__abs__

Next topic

numpy.ndarray.__add__

numpy.ndarray.__invert__

ndarray.__invert__

x.__invert__() <==> ~x


numpy.ndarray.__add__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__invert__

Next topic

numpy.ndarray.__sub__

numpy.ndarray.__add__

ndarray.__add__

x.__add__(y) <==> x+y


numpy.ndarray.__sub__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__add__

Next topic

numpy.ndarray.__mul__

numpy.ndarray.__sub__

ndarray.__sub__

x.__sub__(y) <==> x-y


numpy.ndarray.__mul__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__sub__

Next topic

numpy.ndarray.__div__

numpy.ndarray.__mul__

ndarray.__mul__

x.__mul__(y) <==> x*y


numpy.ndarray.__div__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__mul__

Next topic

numpy.ndarray.__truediv__

numpy.ndarray.__div__

ndarray.__div__

x.__div__(y) <==> x/y


numpy.ndarray.__truediv__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__div__

Next topic

numpy.ndarray.__floordiv__

numpy.ndarray.__truediv__

ndarray.__truediv__

x.__truediv__(y) <==> x/y


numpy.ndarray.__floordiv__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__truediv__

Next topic

numpy.ndarray.__mod__

numpy.ndarray.__floordiv__

ndarray.__floordiv__

x.__floordiv__(y) <==> x//y


numpy.ndarray.__mod__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__floordiv__

Next topic

numpy.ndarray.__divmod__

numpy.ndarray.__mod__

ndarray.__mod__

x.__mod__(y) <==> x%y


numpy.ndarray.__divmod__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__mod__

Next topic

numpy.ndarray.__pow__

numpy.ndarray.__divmod__

ndarray.__divmod__(y) <==> divmod(x, y)


numpy.ndarray.__pow__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__divmod__

Next topic

numpy.ndarray.__lshift__

numpy.ndarray.__pow__

ndarray.__pow__(y[, z]) <==> pow(x, y[, z])


numpy.ndarray.__lshift__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__pow__

Next topic

numpy.ndarray.__rshift__

numpy.ndarray.__lshift__

ndarray.__lshift__

x.__lshift__(y) <==> x<<y


numpy.ndarray.__rshift__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__lshift__

Next topic

numpy.ndarray.__and__

numpy.ndarray.__rshift__

ndarray.__rshift__

x.__rshift__(y) <==> x>>y


numpy.ndarray.__and__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__rshift__

Next topic

numpy.ndarray.__or__

numpy.ndarray.__and__

ndarray.__and__

x.__and__(y) <==> x&y


numpy.ndarray.__or__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__and__

Next topic

numpy.ndarray.__xor__

numpy.ndarray.__or__

ndarray.__or__

x.__or__(y) <==> x|y


numpy.ndarray.__xor__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__or__

Next topic

numpy.ndarray.__iadd__

numpy.ndarray.__xor__

ndarray.__xor__

x.__xor__(y) <==> x^y


numpy.ndarray.__iadd__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__xor__

Next topic

numpy.ndarray.__isub__

numpy.ndarray.__iadd__

ndarray.__iadd__

x.__iadd__(y) <==> x+=y


numpy.ndarray.__isub__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__iadd__

Next topic

numpy.ndarray.__imul__

numpy.ndarray.__isub__

ndarray.__isub__

x.__isub__(y) <==> x-=y


numpy.ndarray.__imul__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__isub__

Next topic

numpy.ndarray.__idiv__

numpy.ndarray.__imul__

ndarray.__imul__

x.__imul__(y) <==> x*=y


numpy.ndarray.__idiv__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__imul__

Next topic

numpy.ndarray.__itruediv__

numpy.ndarray.__idiv__

ndarray.__idiv__

x.__idiv__(y) <==> x/=y


numpy.ndarray.__itruediv__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__idiv__

Next topic

numpy.ndarray.__ifloordiv__

numpy.ndarray.__itruediv__

ndarray.__itruediv__

x.__itruediv__(y) <==> x/y


numpy.ndarray.__ifloordiv__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__itruediv__

Next topic

numpy.ndarray.__imod__

numpy.ndarray.__ifloordiv__

ndarray.__ifloordiv__

x.__ifloordiv__(y) <==> x//y


numpy.ndarray.__imod__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__ifloordiv__

Next topic

numpy.ndarray.__ipow__

numpy.ndarray.__imod__

ndarray.__imod__

x.__imod__(y) <==> x%=y


numpy.ndarray.__ipow__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__imod__

Next topic

numpy.ndarray.__ilshift__

numpy.ndarray.__ipow__

ndarray.__ipow__

x.__ipow__(y) <==> x**=y


numpy.ndarray.__ilshift__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__ipow__

Next topic

numpy.ndarray.__irshift__

numpy.ndarray.__ilshift__

ndarray.__ilshift__

x.__ilshift__(y) <==> x<<=y


numpy.ndarray.__irshift__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__ilshift__

Next topic

numpy.ndarray.__iand__

numpy.ndarray.__irshift__

ndarray.__irshift__

x.__irshift__(y) <==> x>>=y


numpy.ndarray.__iand__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__irshift__

Next topic

numpy.ndarray.__ior__

numpy.ndarray.__iand__

ndarray.__iand__

x.__iand__(y) <==> x&=y


numpy.ndarray.__ior__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__iand__

Next topic

numpy.ndarray.__ixor__

numpy.ndarray.__ior__

ndarray.__ior__

x.__ior__(y) <==> x|=y


numpy.ndarray.__ixor__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__ior__

Next topic

numpy.ndarray.__copy__

numpy.ndarray.__ixor__

ndarray.__ixor__

x.__ixor__(y) <==> x^=y


numpy.ndarray.__copy__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__ixor__

Next topic

numpy.ndarray.__deepcopy__

numpy.ndarray.__copy__

ndarray.__copy__([order])

Return a copy of the array.

Parameters:

order : {‘C’, ‘F’, ‘A’}, optional

If order is ‘C’ (False) then the result is contiguous (default). If order is ‘Fortran’ (True) then the result has fortran order. If order is ‘Any’ (None) then the result has fortran order only if the array already is in fortran order.


numpy.ndarray.__deepcopy__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__copy__

Next topic

numpy.ndarray.__reduce__

numpy.ndarray.__deepcopy__

ndarray.__deepcopy__() → Deep copy of array.

Used if copy.deepcopy is called on an array.


numpy.ndarray.__reduce__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__deepcopy__

Next topic

numpy.ndarray.__setstate__

numpy.ndarray.__reduce__

ndarray.__reduce__()

For pickling.


numpy.ndarray.__setstate__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__reduce__

Next topic

numpy.ndarray.__new__

numpy.ndarray.__setstate__

ndarray.__setstate__(version, shape, dtype, isfortran, rawdata)

For unpickling.

Parameters:

version : int

optional pickle version. If omitted defaults to 0.

shape : tuple

dtype : data-type

isFortran : bool

rawdata : string or list

a binary string with the data (or a list if ‘a’ is an object array)


numpy.ndarray.__new__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__setstate__

Next topic

numpy.ndarray.__array__

numpy.ndarray.__new__

static ndarray.__new__(S, ...) → a new object with type S, a subtype of T


numpy.ndarray.__array__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__new__

Next topic

numpy.ndarray.__array_wrap__

numpy.ndarray.__array__

ndarray.__array__(|dtype) → reference if type unchanged, copy otherwise.

Returns either a new reference to self if dtype is not given or a new array of provided data type if dtype is different from the current dtype of the array.


numpy.ndarray.__array_wrap__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__array__

Next topic

numpy.ndarray.__len__

numpy.ndarray.__array_wrap__

ndarray.__array_wrap__(obj) → Object of same type as ndarray object a.


numpy.ndarray.__len__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__array_wrap__

Next topic

numpy.ndarray.__getitem__

numpy.ndarray.__len__

ndarray.__len__() <==> len(x)


numpy.ndarray.__getitem__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__len__

Next topic

numpy.ndarray.__setitem__

numpy.ndarray.__getitem__

ndarray.__getitem__

x.__getitem__(y) <==> x[y]


numpy.ndarray.__setitem__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__getitem__

Next topic

numpy.ndarray.__getslice__

numpy.ndarray.__setitem__

ndarray.__setitem__

x.__setitem__(i, y) <==> x[i]=y


numpy.ndarray.__getslice__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__setitem__

Next topic

numpy.ndarray.__setslice__

numpy.ndarray.__getslice__

ndarray.__getslice__

x.__getslice__(i, j) <==> x[i:j]

Use of negative indices is not supported.


numpy.ndarray.__setslice__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__getslice__

Next topic

numpy.ndarray.__contains__

numpy.ndarray.__setslice__

ndarray.__setslice__

x.__setslice__(i, j, y) <==> x[i:j]=y

Use of negative indices is not supported.


numpy.ndarray.__contains__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__setslice__

Next topic

numpy.ndarray.__int__

numpy.ndarray.__contains__

ndarray.__contains__

x.__contains__(y) <==> y in x


numpy.ndarray.__int__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__contains__

Next topic

numpy.ndarray.__long__

numpy.ndarray.__int__

ndarray.__int__() <==> int(x)


numpy.ndarray.__long__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__int__

Next topic

numpy.ndarray.__float__

numpy.ndarray.__long__

ndarray.__long__() <==> long(x)


numpy.ndarray.__float__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__long__

Next topic

numpy.ndarray.__oct__

numpy.ndarray.__float__

ndarray.__float__() <==> float(x)


numpy.ndarray.__oct__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__float__

Next topic

numpy.ndarray.__hex__

numpy.ndarray.__oct__

ndarray.__oct__() <==> oct(x)


numpy.ndarray.__hex__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__oct__

Next topic

numpy.ndarray.__str__

numpy.ndarray.__hex__

ndarray.__hex__() <==> hex(x)


numpy.ndarray.__str__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__hex__

Next topic

numpy.ndarray.__repr__

numpy.ndarray.__str__

ndarray.__str__() <==> str(x)


numpy.ndarray.__repr__

  • Array objects
  • The N-dimensional array (ndarray)
  • index
  • next
  • previous

Previous topic

numpy.ndarray.__str__

Next topic

Scalars

numpy.ndarray.__repr__

ndarray.__repr__() <==> repr(x)


Scalars

  • Array objects
  • next
  • previous

Table Of Contents

  • Scalars
    • Built-in scalar types
    • Attributes
    • Indexing
    • Methods
    • Defining new types

Previous topic

numpy.ndarray.__repr__

Next topic

numpy.generic.flags

Scalars

Python defines only one type of a particular data class (there is only one integer type, one floating-point type, etc.). This can be convenient in applications that don’t need to be concerned with all the ways data can be represented in a computer. For scientific computing, however, more control is often needed.

In NumPy, there are 24 new fundamental Python types to describe different types of scalars. These type descriptors are mostly based on the types available in the C language that CPython is written in, with several additional types compatible with Python’s types.

Array scalars have the same attributes and methods as ndarrays. [1] This allows one to treat items of an array partly on the same footing as arrays, smoothing out rough edges that result when mixing scalar and array operations.

Array scalars live in a hierarchy (see the Figure below) of data types. They can be detected using the hierarchy: For example, isinstance(val, np.generic) will return True if val is an array scalar object. Alternatively, what kind of array scalar is present can be determined using other members of the data type hierarchy. Thus, for example isinstance(val, np.complexfloating) will return True if val is a complex valued type, while isinstance(val, np.flexible) will return true if val is one of the flexible itemsize array types (string, unicode, void).

Figure: Hierarchy of type objects representing the array data types. Not shown are the two integer types intp and uintp which just point to the integer type that holds a pointer for the platform. All the number types can be obtained using bit-width names as well.

[1] However, array scalars are immutable, so none of the array scalar attributes are settable.

Built-in scalar types

The built-in scalar types are shown below. Along with their (mostly) C-derived names, the integer, float, and complex data-types are also available using a bit-width convention so that an array of the right size can always be ensured (e.g. int8, float64, complex128). Two aliases (intp and uintp) pointing to the integer type that is sufficiently large to hold a C pointer are also provided. The C-like names are associated with character codes, which are shown in the table. Use of the character codes, however, is discouraged.

Some of the scalar types are essentially equivalent to fundamental Python types and therefore inherit from them as well as from the generic array scalar type:

Array scalar type | Related Python type
int_ | IntType (Python 2 only)
float_ | FloatType
complex_ | ComplexType
str_ | StringType
unicode_ | UnicodeType

The bool_ data type is very similar to the Python BooleanType but does not inherit from it because Python’s BooleanType does not allow itself to be inherited from, and on the C-level the size of the actual bool data is not the same as a Python Boolean scalar.

Warning

The bool_ type is not a subclass of the int_ type (the bool_ is not even a number type). This is different than Python’s default implementation of bool as a sub-class of int.

Warning

The int_ type does not inherit from the int built-in under Python 3, because type int is no longer a fixed-width integer type.

Tip

The default data type in Numpy is float_.

In the tables below, platform? means that the type may not be available on all platforms. Compatibility with different C or Python types is indicated: two types are compatible if their data is of the same size and interpreted in the same way.

Booleans:

Type | Remarks | Character code
bool_ | compatible: Python bool | '?'
bool8 | 8 bits |

Integers:

byte | compatible: C char | 'b'
short | compatible: C short | 'h'
intc | compatible: C int | 'i'
int_ | compatible: Python int | 'l'
longlong | compatible: C long long | 'q'
intp | large enough to fit a pointer | 'p'
int8 | 8 bits |
int16 | 16 bits |
int32 | 32 bits |
int64 | 64 bits |

Unsigned integers:

ubyte | compatible: C unsigned char | 'B'
ushort | compatible: C unsigned short | 'H'
uintc | compatible: C unsigned int | 'I'
uint | compatible: Python int | 'L'
ulonglong | compatible: C long long | 'Q'
uintp | large enough to fit a pointer | 'P'
uint8 | 8 bits |
uint16 | 16 bits |
uint32 | 32 bits |
uint64 | 64 bits |

Floating-point numbers:

half |  | 'e'
single | compatible: C float | 'f'
double | compatible: C double |
float_ | compatible: Python float | 'd'
longfloat | compatible: C long float | 'g'
float16 | 16 bits |
float32 | 32 bits |
float64 | 64 bits |
float96 | 96 bits, platform? |
float128 | 128 bits, platform? |

Complex floating-point numbers:

csingle |  | 'F'
complex_ | compatible: Python complex | 'D'
clongfloat |  | 'G'
complex64 | two 32-bit floats |
complex128 | two 64-bit floats |
complex192 | two 96-bit floats, platform? |
complex256 | two 128-bit floats, platform? |

Any Python object:

object_ any Python object 'O'

Note

The data actually stored in object arrays (i.e., arrays having dtype object_) are references to Python objects, not the objects themselves. Hence, object arrays behave more like usual Python lists, in the sense that their contents need not be of the same Python type.

The object type is also special because an array containing object_ items does not return an object_ object on item access, but instead returns the actual object that the array item refers to.

The following data types are flexible. They have no predefined size: the data they describe can be of different length in different arrays. (In the character codes # is an integer denoting how many elements the data type consists of.)

str_ | compatible: Python str | 'S#'
unicode_ | compatible: Python unicode | 'U#'
void |  | 'V#'

Warning

Numeric Compatibility: If you used old typecode characters in your Numeric code (which was never recommended), you will need to change some of them to the new characters. In particular, the needed changes are c -> S1, b -> B, 1 -> b, s -> h, w -> H, and u -> I. These changes make the type character convention more consistent with other Python modules such as the struct module.

Attributes

The array scalar objects have an array priority of NPY_SCALAR_PRIORITY (-1,000,000.0). They also do not (yet) have a ctypes attribute. Otherwise, they share the same attributes as arrays:

generic.flags | integer value of flags
generic.shape | tuple of array dimensions
generic.strides | tuple of bytes steps in each dimension
generic.ndim | number of array dimensions
generic.data | pointer to start of data
generic.size | number of elements in the gentype
generic.itemsize | length of one element in bytes
generic.base | base object
generic.dtype | get array data-descriptor
generic.real | real part of scalar
generic.imag | imaginary part of scalar
generic.flat | a 1-d view of scalar
generic.T | transpose
generic.__array_interface__ | Array protocol: Python side
generic.__array_struct__ | Array protocol: struct
generic.__array_priority__ | Array priority.
generic.__array_wrap__ | sc.__array_wrap__(obj) return scalar from array

Indexing

See also

Indexing, Data type objects (dtype)

Array scalars can be indexed like 0-dimensional arrays: if x is an array scalar,

  • x[()] returns a 0-dimensional ndarray
  • x['field-name'] returns the array scalar in the field field-name. (x can have fields, for example, when it corresponds to a record data type.)

Methods

Array scalars have exactly the same methods as arrays. The default behavior of these methods is to internally convert the scalar to an equivalent 0-dimensional array and to call the corresponding array method. In addition, math operations on array scalars are defined so that the same hardware flags are set and used to interpret the results as for ufunc, so that the error state used for ufuncs also carries over to the math on array scalars.

The exceptions to the above rules are given below:

generic | Base class for numpy scalar types.
generic.__array__ | sc.__array__(|type) return 0-dim array
generic.__array_wrap__ | sc.__array_wrap__(obj) return scalar from array
generic.squeeze | Not implemented (virtual attribute)
generic.byteswap | Not implemented (virtual attribute)
generic.__reduce__ |
generic.__setstate__ |
generic.setflags | Not implemented (virtual attribute)

Defining new types

There are two ways to effectively define a new array scalar type (apart from composing record dtypes from the built-in scalar types): One way is to simply subclass the ndarray and overwrite the methods of interest. This will work to a degree, but internally certain behaviors are fixed by the data type of the array. To fully customize the data type of an array you need to define a new data-type, and register it with NumPy. Such new types can only be defined in C, using the Numpy C-API.


numpy.generic.flags

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.dtype

Next topic

numpy.generic.flat

numpy.generic.flags

generic.flags

integer value of flags


numpy.generic.shape

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.real

Next topic

numpy.generic.size

numpy.generic.shape

generic.shape

tuple of array dimensions


numpy.generic.strides

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.size

Next topic

numpy.generic.all

numpy.generic.strides

generic.strides

tuple of bytes steps in each dimension


numpy.generic.ndim

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.nbytes

Next topic

numpy.generic.real

numpy.generic.ndim

generic.ndim

number of array dimensions


numpy.generic.data

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.base

Next topic

numpy.generic.dtype

numpy.generic.data

generic.data

pointer to start of data


numpy.generic.size

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.shape

Next topic

numpy.generic.strides

numpy.generic.size

generic.size

number of elements in the gentype


numpy.generic.itemsize

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.imag

Next topic

numpy.generic.nbytes

numpy.generic.itemsize

generic.itemsize

length of one element in bytes


numpy.generic.base

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.T

Next topic

numpy.generic.data

numpy.generic.base

generic.base

base object


numpy.generic.dtype

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.data

Next topic

numpy.generic.flags

numpy.generic.dtype

generic.dtype

get array data-descriptor


numpy.generic.real

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.ndim

Next topic

numpy.generic.shape

numpy.generic.real

generic.real

real part of scalar


numpy.generic.imag

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.flat

Next topic

numpy.generic.itemsize

numpy.generic.imag

generic.imag

imaginary part of scalar


numpy.generic.flat

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.flags

Next topic

numpy.generic.imag

numpy.generic.flat

generic.flat

a 1-d view of scalar


numpy.generic.T

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic

Next topic

numpy.generic.base

numpy.generic.T

generic.T

transpose


numpy.generic.__array_interface__

  • Array objects
  • Scalars
  • index
  • next
  • previous

Previous topic

numpy.generic.T

Next topic

numpy.generic.__array_struct__

numpy.generic.__array_interface__

generic.__array_interface__

Array protocol: Python side


numpy.generic.__array_struct__

  • Array objects
  • Scalars
  • index
  • next
  • previous

Previous topic

numpy.generic.__array_interface__

Next topic

numpy.generic.__array_priority__

numpy.generic.__array_struct__

generic.__array_struct__

Array protocol: struct


numpy.generic.__array_priority__

  • Array objects
  • Scalars
  • index
  • next
  • previous

Previous topic

numpy.generic.__array_struct__

Next topic

numpy.generic.__array_wrap__

numpy.generic.__array_priority__

generic.__array_priority__

Array priority.


numpy.generic.__array_wrap__

  • Array objects
  • Scalars
  • index
  • next
  • previous

Previous topic

numpy.generic.__array__

Next topic

numpy.generic.squeeze

numpy.generic.__array_wrap__

generic.__array_wrap__()

sc.__array_wrap__(obj) return scalar from array


numpy.generic

  • Array objects
  • Scalars
  • index
  • next
  • previous

Previous topic

numpy.generic.__array_wrap__

Next topic

numpy.generic.T

numpy.generic

class numpy.generic [source]

Base class for numpy scalar types.

Class from which most (all?) numpy scalar types are derived. For consistency, exposes the same API as ndarray, despite many consequent attributes being either “get-only,” or completely irrelevant. This is the class from which it is strongly suggested users should derive custom scalar types.

Attributes

T | transpose
base | base object
data | pointer to start of data
dtype | get array data-descriptor
flags | integer value of flags
flat | a 1-d view of scalar
imag | imaginary part of scalar
itemsize | length of one element in bytes
nbytes | length of item in bytes
ndim | number of array dimensions
real | real part of scalar
shape | tuple of array dimensions
size | number of elements in the gentype
strides | tuple of bytes steps in each dimension

Methods

all | Not implemented (virtual attribute)
any | Not implemented (virtual attribute)
argmax | Not implemented (virtual attribute)
argmin | Not implemented (virtual attribute)
argsort | Not implemented (virtual attribute)
astype | Not implemented (virtual attribute)
byteswap | Not implemented (virtual attribute)
choose | Not implemented (virtual attribute)
clip | Not implemented (virtual attribute)
compress | Not implemented (virtual attribute)
conj
conjugate | Not implemented (virtual attribute)
copy | Not implemented (virtual attribute)
cumprod | Not implemented (virtual attribute)
cumsum | Not implemented (virtual attribute)
diagonal | Not implemented (virtual attribute)
dump | Not implemented (virtual attribute)
dumps | Not implemented (virtual attribute)
fill | Not implemented (virtual attribute)
flatten | Not implemented (virtual attribute)
getfield | Not implemented (virtual attribute)
item | Not implemented (virtual attribute)
itemset | Not implemented (virtual attribute)
max | Not implemented (virtual attribute)
mean | Not implemented (virtual attribute)
min | Not implemented (virtual attribute)
newbyteorder([new_order]) | Return a new dtype with a different byte order.
nonzero | Not implemented (virtual attribute)
prod | Not implemented (virtual attribute)
ptp | Not implemented (virtual attribute)
put | Not implemented (virtual attribute)
ravel | Not implemented (virtual attribute)
repeat | Not implemented (virtual attribute)
reshape | Not implemented (virtual attribute)
resize | Not implemented (virtual attribute)
round | Not implemented (virtual attribute)
searchsorted | Not implemented (virtual attribute)
setfield | Not implemented (virtual attribute)
setflags | Not implemented (virtual attribute)
sort | Not implemented (virtual attribute)
squeeze | Not implemented (virtual attribute)
std | Not implemented (virtual attribute)
sum | Not implemented (virtual attribute)
swapaxes | Not implemented (virtual attribute)
take | Not implemented (virtual attribute)
tobytes
tofile | Not implemented (virtual attribute)
tolist | Not implemented (virtual attribute)
tostring | Not implemented (virtual attribute)
trace | Not implemented (virtual attribute)
transpose | Not implemented (virtual attribute)
var | Not implemented (virtual attribute)
view | Not implemented (virtual attribute)


numpy.generic.nbytes

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.itemsize

Next topic

numpy.generic.ndim

numpy.generic.nbytes

generic.nbytes

length of item in bytes


numpy.generic.all

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.strides

Next topic

numpy.generic.any

numpy.generic.all

generic.all()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.any

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.all

Next topic

numpy.generic.argmax

numpy.generic.any

generic.any()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.argmax

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.any

Next topic

numpy.generic.argmin

numpy.generic.argmax

generic.argmax()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.argmin

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.argmax

Next topic

numpy.generic.argsort

numpy.generic.argmin

generic.argmin()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.argsort

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.argmin

Next topic

numpy.generic.astype

numpy.generic.argsort

generic.argsort()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.astype

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.argsort

Next topic

numpy.generic.byteswap

numpy.generic.astype

generic.astype()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.byteswap

  • Array objects
  • Scalars
  • index
  • next
  • previous

Previous topic

numpy.generic.squeeze

Next topic

numpy.generic.__reduce__

numpy.generic.byteswap

generic.byteswap()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.choose

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.byteswap

Next topic

numpy.generic.clip

numpy.generic.choose

generic.choose()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.clip

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.choose

Next topic

numpy.generic.compress

numpy.generic.clip

generic.clip()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.compress

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.clip

Next topic

numpy.generic.conj

numpy.generic.compress

generic.compress()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.conj

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.compress

Next topic

numpy.generic.conjugate

numpy.generic.conj

generic.conj()


numpy.generic.conjugate

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.conj

Next topic

numpy.generic.copy

numpy.generic.conjugate

generic.conjugate()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.copy

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.conjugate

Next topic

numpy.generic.cumprod

numpy.generic.copy

generic.copy()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.cumprod

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.copy

Next topic

numpy.generic.cumsum

numpy.generic.cumprod

generic.cumprod()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.cumsum

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.cumprod

Next topic

numpy.generic.diagonal

numpy.generic.cumsum

generic.cumsum()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.diagonal

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.cumsum

Next topic

numpy.generic.dump

numpy.generic.diagonal

generic.diagonal()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.dump

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.diagonal

Next topic

numpy.generic.dumps

numpy.generic.dump

generic.dump()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.dumps

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.dump

Next topic

numpy.generic.fill

numpy.generic.dumps

generic.dumps()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.fill

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.dumps

Next topic

numpy.generic.flatten

numpy.generic.fill

generic.fill()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.flatten

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.fill

Next topic

numpy.generic.getfield

numpy.generic.flatten

generic.flatten()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.getfield

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.flatten

Next topic

numpy.generic.item

numpy.generic.getfield

generic.getfield()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.item

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.getfield

Next topic

numpy.generic.itemset

numpy.generic.item

generic.item()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.itemset

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.item

Next topic

numpy.generic.max

numpy.generic.itemset

generic.itemset()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.max

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.itemset

Next topic

numpy.generic.mean

numpy.generic.max

generic.max()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.mean

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.max

Next topic

numpy.generic.min

numpy.generic.mean

generic.mean()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.min

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.mean

Next topic

numpy.generic.newbyteorder

numpy.generic.min

generic.min()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.newbyteorder

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.min

Next topic

numpy.generic.nonzero

numpy.generic.newbyteorder

generic.newbyteorder(new_order='S')

Return a new dtype with a different byte order.

Changes are also made in all fields and sub-arrays of the data type.

The new_order code can be any from the following:

  • {‘<’, ‘L’} - little endian
  • {‘>’, ‘B’} - big endian
  • {‘=’, ‘N’} - native order
  • ‘S’ - swap dtype from current to opposite endian
  • {‘|’, ‘I’} - ignore (no change to byte order)
Parameters:

new_order : str, optional

Byte order to force; a value from the byte order specifications above. The default value (‘S’) results in swapping the current byte order. The code does a case-insensitive check on the first letter of new_order for the alternatives above. For example, any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns:

new_dtype : dtype

New dtype object with the given change to the byte order.


numpy.generic.nonzero

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.newbyteorder

Next topic

numpy.generic.prod

numpy.generic.nonzero

generic.nonzero()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.prod

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.nonzero

Next topic

numpy.generic.ptp

numpy.generic.prod

generic.prod()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.ptp

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.prod

Next topic

numpy.generic.put

numpy.generic.ptp

generic.ptp()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.put

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.ptp

Next topic

numpy.generic.ravel

numpy.generic.put

generic.put()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.ravel

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.put

Next topic

numpy.generic.repeat

numpy.generic.ravel

generic.ravel()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.repeat

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.ravel

Next topic

numpy.generic.reshape

numpy.generic.repeat

generic.repeat()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.reshape

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.repeat

Next topic

numpy.generic.resize

numpy.generic.reshape

generic.reshape()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.resize

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.reshape

Next topic

numpy.generic.round

numpy.generic.resize

generic.resize()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.round

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.resize

Next topic

numpy.generic.searchsorted

numpy.generic.round

generic.round()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.searchsorted

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.round

Next topic

numpy.generic.setfield

numpy.generic.searchsorted

generic.searchsorted()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.setfield

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.searchsorted

Next topic

numpy.generic.setflags

numpy.generic.setfield

generic.setfield()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.setflags

  • Array objects
  • Scalars
  • index
  • next
  • previous

Previous topic

numpy.generic.__setstate__

Next topic

Data type objects (dtype)

numpy.generic.setflags

generic.setflags()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.sort

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.setflags

Next topic

numpy.generic.squeeze

numpy.generic.sort

generic.sort()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.squeeze

  • Array objects
  • Scalars
  • index
  • next
  • previous

Previous topic

numpy.generic.__array_wrap__

Next topic

numpy.generic.byteswap

numpy.generic.squeeze

generic.squeeze()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.std

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.squeeze

Next topic

numpy.generic.sum

numpy.generic.std

generic.std()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.sum

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.std

Next topic

numpy.generic.swapaxes

numpy.generic.sum

generic.sum()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.swapaxes

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.sum

Next topic

numpy.generic.take

numpy.generic.swapaxes

generic.swapaxes()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.take

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.swapaxes

Next topic

numpy.generic.tobytes

numpy.generic.take

generic.take()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.tobytes

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.take

Next topic

numpy.generic.tofile

numpy.generic.tobytes

generic.tobytes()


numpy.generic.tofile

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.tobytes

Next topic

numpy.generic.tolist

numpy.generic.tofile

generic.tofile()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.tolist

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.tofile

Next topic

numpy.generic.tostring

numpy.generic.tolist

generic.tolist()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.tostring

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.tolist

Next topic

numpy.generic.trace

numpy.generic.tostring

generic.tostring()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.trace

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.tostring

Next topic

numpy.generic.transpose

numpy.generic.trace

generic.trace()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.transpose

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.trace

Next topic

numpy.generic.var

numpy.generic.transpose

generic.transpose()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.var

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.transpose

Next topic

numpy.generic.view

numpy.generic.var

generic.var()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.view

  • Array objects
  • Scalars
  • numpy.generic
  • index
  • next
  • previous

Previous topic

numpy.generic.var

Next topic

numpy.generic.__array__

numpy.generic.view

generic.view()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.generic.__array__

  • Array objects
  • Scalars
  • index
  • next
  • previous

Previous topic

numpy.generic.view

Next topic

numpy.generic.__array_wrap__

numpy.generic.__array__

generic.__array__()

sc.__array__(|type) return 0-dim array


numpy.generic.__reduce__

  • Array objects
  • Scalars
  • index
  • next
  • previous

Previous topic

numpy.generic.byteswap

Next topic

numpy.generic.__setstate__

numpy.generic.__reduce__

generic.__reduce__()


numpy.generic.__setstate__

  • Array objects
  • Scalars
  • index
  • next
  • previous

Previous topic

numpy.generic.__reduce__

Next topic

numpy.generic.setflags

numpy.generic.__setstate__

generic.__setstate__()


Data type objects (dtype)

  • Array objects
  • next
  • previous

Table Of Contents

  • Data type objects (dtype)
    • Specifying and constructing data types
    • dtype
      • Attributes
      • Methods

Previous topic

numpy.generic.setflags

Next topic

numpy.dtype

Data type objects (dtype)

A data type object (an instance of numpy.dtype class) describes how the bytes in the fixed-size block of memory corresponding to an array item should be interpreted. It describes the following aspects of the data:

  1. Type of the data (integer, float, Python object, etc.)
  2. Size of the data (how many bytes is in e.g. the integer)
  3. Byte order of the data (little-endian or big-endian)
  4. If the data type is a record, an aggregate of other data types, (e.g., describing an array item consisting of an integer and a float),
    1. what are the names of the “fields” of the record, by which they can be accessed,
    2. what is the data-type of each field, and
    3. which part of the memory block each field takes.
  5. If the data type is a sub-array, what is its shape and data type.

To describe the type of scalar data, there are several built-in scalar types in Numpy for various precision of integers, floating-point numbers, etc. An item extracted from an array, e.g., by indexing, will be a Python object whose type is the scalar type associated with the data type of the array.

Note that the scalar types are not dtype objects, even though they can be used in place of one whenever a data type specification is needed in Numpy.

Struct data types are formed by creating a data type whose fields contain other data types. Each field has a name by which it can be accessed. The parent data type should be of sufficient size to contain all its fields; the parent is nearly always based on the void type which allows an arbitrary item size. Struct data types may also contain nested struct sub-array data types in their fields.

Finally, a data type can describe items that are themselves arrays of items of another data type. These sub-arrays must, however, be of a fixed size.

If an array is created using a data-type describing a sub-array, the dimensions of the sub-array are appended to the shape of the array when the array is created. Sub-arrays in a field of a record behave differently, see Record Access.

Sub-arrays always have a C-contiguous memory layout.

Example

A simple data type containing a 32-bit big-endian integer: (see Specifying and constructing data types for details on construction)

>>> dt = np.dtype('>i4')
>>> dt.byteorder
'>'
>>> dt.itemsize
4
>>> dt.name
'int32'
>>> dt.type is np.int32
True

The corresponding array scalar type is int32.

Example

A record data type containing a 16-character string (in field ‘name’) and a sub-array of two 64-bit floating-point number (in field ‘grades’):

>>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
>>> dt['name']
dtype('|S16')
>>> dt['grades']
dtype(('float64',(2,)))

Items of an array of this data type are wrapped in an array scalar type that also has two fields:

>>> x = np.array([('Sarah', (8.0, 7.0)), ('John', (6.0, 7.0))], dtype=dt)
>>> x[1]
('John', [6.0, 7.0])
>>> x[1]['grades']
array([ 6.,  7.])
>>> type(x[1])
<type 'numpy.void'>
>>> type(x[1]['grades'])
<type 'numpy.ndarray'>

Specifying and constructing data types

Whenever a data-type is required in a NumPy function or method, either a dtype object or something that can be converted to one can be supplied. Such conversions are done by the dtype constructor:

dtype Create a data type object.

What can be converted to a data-type object is described below:

dtype object

Used as-is.

None

The default data type: float_.

Array-scalar types

The 24 built-in array scalar type objects all convert to an associated data-type object. This is true for their sub-classes as well.

Note that not all data-type information can be supplied with a type-object: for example, flexible data-types have a default itemsize of 0, and require an explicitly given size to be useful.

Example

>>> dt = np.dtype(np.int32)      # 32-bit integer
>>> dt = np.dtype(np.complex128) # 128-bit complex floating-point number

Generic types

The generic hierarchical type objects convert to corresponding type objects according to the associations:

number, inexact, floating | float
complexfloating | cfloat
integer, signedinteger | int_
unsignedinteger | uint
character | string
generic, flexible | void

Built-in Python types

Several python types are equivalent to a corresponding array scalar when used to generate a dtype object:

int | int_
bool | bool_
float | float_
complex | cfloat
str | string
unicode | unicode_
buffer | void
(all others) | object_

Example

>>> dt = np.dtype(float)   # Python-compatible floating-point number
>>> dt = np.dtype(int)     # Python-compatible integer
>>> dt = np.dtype(object)  # Python object

Types with .dtype

Any type object with a dtype attribute: The attribute will be accessed and used directly. The attribute must return something that is convertible into a dtype object.

Several kinds of strings can be converted. Recognized strings can be prepended with '>' (big-endian), '<' (little-endian), or '=' (hardware-native, the default), to specify the byte order.

One-character strings

Each built-in data-type has a character code (the updated Numeric typecodes), that uniquely identifies it.

Example

>>> dt = np.dtype('b')  # byte, native byte order
>>> dt = np.dtype('>H') # big-endian unsigned short
>>> dt = np.dtype('<f') # little-endian single-precision float
>>> dt = np.dtype('d')  # double-precision floating-point number

Array-protocol type strings (see The Array Interface)

The first character specifies the kind of data and the remaining characters specify the number of bytes per item. The item size may be ignored for some kinds (i.e., boolean, object), rounded to the next supported size (float, complex), or interpreted as the number of characters (Unicode). The supported kinds are

'b' | boolean
'i' | (signed) integer
'u' | unsigned integer
'f' | floating-point
'c' | complex-floating point
'O' | (Python) objects
'S', 'a' | (byte-)string
'U' | Unicode
'V' | raw data (void)

Example

>>> dt = np.dtype('i4')   # 32-bit signed integer
>>> dt = np.dtype('f8')   # 64-bit floating-point number
>>> dt = np.dtype('c16')  # 128-bit complex floating-point number
>>> dt = np.dtype('a25')  # 25-character string

String with comma-separated fields

Numarray introduced a short-hand notation for specifying the format of a record as a comma-separated string of basic formats.

A basic format in this context is an optional shape specifier followed by an array-protocol type string. Parenthesis are required on the shape if it has more than one dimension. NumPy allows a modification on the format in that any string that can uniquely identify the type can be used to specify the data-type in a field. The generated data-type fields are named 'f0', 'f1', ..., 'f<N-1>' where N (>1) is the number of comma-separated basic formats in the string. If the optional shape specifier is provided, then the data-type for the corresponding field describes a sub-array.

Example

  • field named f0 containing a 32-bit integer
  • field named f1 containing a 2 x 3 sub-array of 64-bit floating-point numbers
  • field named f2 containing a 32-bit floating-point number
>>> dt = np.dtype("i4, (2,3)f8, f4")
  • field named f0 containing a 3-character string
  • field named f1 containing a sub-array of shape (3,) containing 64-bit unsigned integers
  • field named f2 containing a 3 x 4 sub-array containing 10-character strings
>>> dt = np.dtype("a3, 3u8, (3,4)a10")

Type strings

Any string in numpy.sctypeDict.keys():

Example

>>> dt = np.dtype('uint32')   # 32-bit unsigned integer
>>> dt = np.dtype('Float64')  # 64-bit floating-point number

(flexible_dtype, itemsize)

The first argument must be an object that is converted to a zero-sized flexible data-type object, the second argument is an integer providing the desired itemsize.

Example

>>> dt = np.dtype((void, 10))  # 10-byte wide data block
>>> dt = np.dtype((str, 35))   # 35-character string
>>> dt = np.dtype(('U', 10))   # 10-character unicode string

(fixed_dtype, shape)

The first argument is any object that can be converted into a fixed-size data-type object. The second argument is the desired shape of this type. If the shape parameter is 1, then the data-type object is equivalent to fixed dtype. If shape is a tuple, then the new dtype defines a sub-array of the given shape.

Example

>>> dt = np.dtype((np.int32, (2,2)))          # 2 x 2 integer sub-array
>>> dt = np.dtype(('S10', 1))                 # 10-character string
>>> dt = np.dtype(('i4, (2,3)f8, f4', (2,3))) # 2 x 3 record sub-array

[(field_name, field_dtype, field_shape), ...]

obj should be a list of fields where each field is described by a tuple of length 2 or 3. (Equivalent to the descr item in the __array_interface__ attribute.)

The first element, field_name, is the field name (if this is '' then a standard field name, 'f#', is assigned). The field name may also be a 2-tuple of strings where the first string is either a “title” (which may be any string or unicode string) or meta-data for the field which can be any object, and the second string is the “name” which must be a valid Python identifier.

The second element, field_dtype, can be anything that can be interpreted as a data-type.

The optional third element field_shape contains the shape if this field represents an array of the data-type in the second element. Note that a 3-tuple with a third argument equal to 1 is equivalent to a 2-tuple.

This style does not accept align in the dtype constructor as it is assumed that all of the memory is accounted for by the array interface description.

Example

Data-type with fields big (big-endian 32-bit integer) and little (little-endian 32-bit integer):

>>> dt = np.dtype([('big', '>i4'), ('little', '<i4')])

Data-type with fields R, G, B, A, each being an unsigned 8-bit integer:

>>> dt = np.dtype([('R','u1'), ('G','u1'), ('B','u1'), ('A','u1')])

{'names': ..., 'formats': ..., 'offsets': ..., 'titles': ..., 'itemsize': ...}

This style has two required and three optional keys. The names and formats keys are required. Their respective values are equal-length lists with the field names and the field formats. The field names must be strings and the field formats can be any object accepted by dtype constructor.

When the optional keys offsets and titles are provided, their values must each be lists of the same length as the names and formats lists. The offsets value is a list of byte offsets (integers) for each field, while the titles value is a list of titles for each field (None can be used if no title is desired for that field). The titles can be any string or unicode object and will add another entry to the fields dictionary keyed by the title and referencing the same field tuple which will contain the title as an additional tuple member.

The itemsize key allows the total size of the dtype to be set, and must be an integer large enough so all the fields are within the dtype. If the dtype being constructed is aligned, the itemsize must also be divisible by the struct alignment.

Example

Data type with fields r, g, b, a, each being a 8-bit unsigned integer:

>>> dt = np.dtype({'names': ['r','g','b','a'],
...                'formats': [uint8, uint8, uint8, uint8]})

Data type with fields r and b (with the given titles), both being 8-bit unsigned integers, the first at byte position 0 from the start of the field and the second at position 2:

>>> dt = np.dtype({'names': ['r','b'], 'formats': ['u1', 'u1'],
...                'offsets': [0, 2],
...                'titles': ['Red pixel', 'Blue pixel']})

{'field1': ..., 'field2': ..., ...}

This usage is discouraged, because it is ambiguous with the other dict-based construction method. If you have a field called ‘names’ and a field called ‘formats’ there will be a conflict.

This style allows passing in the fields attribute of a data-type object.

obj should contain string or unicode keys that refer to (data-type, offset) or (data-type, offset, title) tuples.

Example

Data type containing field col1 (10-character string at byte position 0), col2 (32-bit float at byte position 10), and col3 (integers at byte position 14):

>>> dt = np.dtype({'col1': ('S10', 0), 'col2': (float32, 10),
    'col3': (int, 14)})

(base_dtype, new_dtype)

This usage is discouraged. In NumPy 1.7 and later, it is possible to specify struct dtypes with overlapping fields, functioning like the ‘union’ type in C. The union mechanism is preferred.

Both arguments must be convertible to data-type objects in this case. The base_dtype is the data-type object that the new data-type builds on. This is how you could assign named fields to any built-in data-type object.

Example

32-bit integer, whose first two bytes are interpreted as an integer via field real, and the following two bytes via field imag.

>>> dt = np.dtype((np.int32,{'real':(np.int16, 0),'imag':(np.int16, 2)})

32-bit integer, which is interpreted as consisting of a sub-array of shape (4,) containing 8-bit integers:

>>> dt = np.dtype((np.int32, (np.int8, 4)))

32-bit integer, containing fields r, g, b, a that interpret the 4 bytes in the integer as four unsigned integers:

>>> dt = np.dtype(('i4', [('r','u1'),('g','u1'),('b','u1'),('a','u1')]))

dtype

Numpy data type descriptions are instances of the dtype class.

Attributes

The type of the data is described by the following dtype attributes:

dtype.type | The type object used to instantiate a scalar of this data-type.
dtype.kind | A character code (one of ‘biufcOSUV’) identifying the general kind of data.
dtype.char | A unique character code for each of the 21 different built-in types.
dtype.num | A unique number for each of the 21 different built-in types.
dtype.str | The array-protocol typestring of this data-type object.

Size of the data is in turn described by:

dtype.name | A bit-width name for this data-type.
dtype.itemsize | The element size of this data-type object.

Endianness of this data:

dtype.byteorder A character indicating the byte-order of this data-type object.

Information about sub-data-types in a record:

dtype.fields | Dictionary of named fields defined for this data type, or None.
dtype.names | Ordered list of field names, or None if there are no fields.

For data types that describe sub-arrays:

dtype.subdtype | Tuple (item_dtype, shape) if this dtype describes a sub-array, and None otherwise.
dtype.shape | Shape tuple of the sub-array if this data type describes a sub-array, and () otherwise.

Attributes providing additional information:

dtype.hasobject | Boolean indicating whether this dtype contains any reference-counted objects in any fields or sub-dtypes.
dtype.flags | Bit-flags describing how this data type is to be interpreted.
dtype.isbuiltin | Integer indicating how this dtype relates to the built-in dtypes.
dtype.isnative | Boolean indicating whether the byte order of this dtype is native to the platform.
dtype.descr | Array-interface compliant full description of the data-type.
dtype.alignment | The required alignment (bytes) of this data-type according to the compiler.

Methods

Data types have the following method for changing the byte order:

dtype.newbyteorder([new_order]) Return a new dtype with a different byte order.

The following methods implement the pickle protocol:

dtype.__reduce__
dtype.__setstate__


numpy.dtype

  • Data type routines
  • next
  • previous

Previous topic

numpy.obj2sctype

Next topic

numpy.dtype.base

numpy.dtype

class numpy.dtype [source]

Create a data type object.

A numpy array is homogeneous, and contains elements described by a dtype object. A dtype object can be constructed from different combinations of fundamental numeric types.

Parameters:

obj

Object to be converted to a data type object.

align : bool, optional

Add padding to the fields to match what a C compiler would output for a similar C-struct. Can be True only if obj is a dictionary or a comma-separated string. If a struct dtype is being created, this also sets a sticky alignment flag isalignedstruct.

copy : bool, optional

Make a new copy of the data-type object. If False, the result may just be a reference to a built-in data-type object.

See also

result_type

Examples

Using array-scalar type:

>>> np.dtype(np.int16)
dtype('int16')

Record, one field name ‘f1’, containing int16:

>>> np.dtype([('f1', np.int16)])
dtype([('f1', '<i2')])

Record, one field named ‘f1’, in itself containing a record with one field:

>>> np.dtype([('f1', [('f1', np.int16)])])
dtype([('f1', [('f1', '<i2')])])

Record, two fields: the first field contains an unsigned int, the second an int32:

>>> np.dtype([('f1', np.uint), ('f2', np.int32)])
dtype([('f1', '<u4'), ('f2', '<i4')])

Using array-protocol type strings:

>>> np.dtype([('a','f8'),('b','S10')])
dtype([('a', '<f8'), ('b', '|S10')])

Using comma-separated field formats. The shape is (2,3):

>>> np.dtype("i4, (2,3)f8")
dtype([('f0', '<i4'), ('f1', '<f8', (2, 3))])

Using tuples. int is a fixed type, 3 the field’s shape. void is a flexible type, here of size 10:

>>> np.dtype([('hello',(np.int,3)),('world',np.void,10)])
dtype([('hello', '<i4', 3), ('world', '|V10')])

Subdivide int16 into 2 int8‘s, called x and y. 0 and 1 are the offsets in bytes:

>>> np.dtype((np.int16, {'x':(np.int8,0), 'y':(np.int8,1)}))
dtype(('<i2', [('x', '|i1'), ('y', '|i1')]))

Using dictionaries. Two fields named ‘gender’ and ‘age’:

>>> np.dtype({'names':['gender','age'], 'formats':['S1',np.uint8]})
dtype([('gender', '|S1'), ('age', '|u1')])

Offsets in bytes, here 0 and 25:

>>> np.dtype({'surname':('S25',0),'age':(np.uint8,25)})
dtype([('surname', '|S25'), ('age', '|u1')])

Attributes

base
descr | Array-interface compliant full description of the data-type.
fields | Dictionary of named fields defined for this data type, or None.
hasobject | Boolean indicating whether this dtype contains any reference-counted objects in any fields or sub-dtypes.
isalignedstruct | Boolean indicating whether the dtype is a struct which maintains field alignment.
isbuiltin | Integer indicating how this dtype relates to the built-in dtypes.
isnative | Boolean indicating whether the byte order of this dtype is native to the platform.
metadata
name | A bit-width name for this data-type.
names | Ordered list of field names, or None if there are no fields.
shape | Shape tuple of the sub-array if this data type describes a sub-array, and () otherwise.
str | The array-protocol typestring of this data-type object.
subdtype | Tuple (item_dtype, shape) if this dtype describes a sub-array, and None otherwise.

Methods

newbyteorder([new_order]) Return a new dtype with a different byte order.


numpy.dtype.base

  • Data type routines
  • numpy.dtype
  • index
  • next
  • previous

Previous topic

numpy.dtype

Next topic

numpy.dtype.descr

numpy.dtype.base

dtype.base


numpy.dtype.descr

  • Data type routines
  • numpy.dtype
  • index
  • next
  • previous

Previous topic

numpy.dtype.base

Next topic

numpy.dtype.fields

numpy.dtype.descr

dtype.descr

Array-interface compliant full description of the data-type.

The format is that required by the ‘descr’ key in the __array_interface__ attribute.


numpy.dtype.fields

  • Data type routines
  • numpy.dtype
  • index
  • next
  • previous

Previous topic

numpy.dtype.descr

Next topic

numpy.dtype.hasobject

numpy.dtype.fields

dtype.fields

Dictionary of named fields defined for this data type, or None.

The dictionary is indexed by keys that are the names of the fields. Each entry in the dictionary is a tuple fully describing the field:

(dtype, offset[, title])

If present, the optional title can be any object (if it is a string or unicode then it will also be a key in the fields dictionary, otherwise it’s meta-data). Notice also that the first two elements of the tuple can be passed directly as arguments to the ndarray.getfield and ndarray.setfield methods.

See also

ndarray.getfield, ndarray.setfield

Examples

>>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
>>> print dt.fields
{'grades': (dtype(('float64',(2,))), 16), 'name': (dtype('|S16'), 0)}


numpy.dtype.hasobject

  • Data type routines
  • numpy.dtype
  • index
  • next
  • previous

Previous topic

numpy.dtype.fields

Next topic

numpy.dtype.isalignedstruct

numpy.dtype.hasobject

dtype.hasobject

Boolean indicating whether this dtype contains any reference-counted objects in any fields or sub-dtypes.

Recall that what is actually in the ndarray memory representing the Python object is the memory address of that object (a pointer). Special handling may be required, and this attribute is useful for distinguishing data types that may contain arbitrary Python objects and data-types that won’t.


numpy.dtype.isalignedstruct

  • Data type routines
  • numpy.dtype
  • index
  • next
  • previous

Previous topic

numpy.dtype.hasobject

Next topic

numpy.dtype.isbuiltin

numpy.dtype.isalignedstruct

dtype.isalignedstruct

Boolean indicating whether the dtype is a struct which maintains field alignment. This flag is sticky, so when combining multiple structs together, it is preserved and produces new dtypes which are also aligned.


numpy.dtype.isbuiltin

  • Data type routines
  • numpy.dtype
  • index
  • next
  • previous

Previous topic

numpy.dtype.isalignedstruct

Next topic

numpy.dtype.isnative

numpy.dtype.isbuiltin

dtype.isbuiltin

Integer indicating how this dtype relates to the built-in dtypes.

Read-only.

0 | if this is a structured array type, with fields
1 | if this is a dtype compiled into numpy (such as ints, floats etc)
2 | if the dtype is for a user-defined numpy type A user-defined type uses the numpy C-API machinery to extend numpy to handle a new array type. See User-defined data-types in the Numpy manual.

Examples

>>> dt = np.dtype('i2')
>>> dt.isbuiltin
1
>>> dt = np.dtype('f8')
>>> dt.isbuiltin
1
>>> dt = np.dtype([('field1', 'f8')])
>>> dt.isbuiltin
0


numpy.dtype.isnative

  • Data type routines
  • numpy.dtype
  • index
  • next
  • previous

Previous topic

numpy.dtype.isbuiltin

Next topic

numpy.dtype.metadata

numpy.dtype.isnative

dtype.isnative

Boolean indicating whether the byte order of this dtype is native to the platform.


numpy.dtype.metadata

  • Data type routines
  • numpy.dtype
  • index
  • next
  • previous

Previous topic

numpy.dtype.isnative

Next topic

numpy.dtype.name

numpy.dtype.metadata

dtype.metadata


numpy.dtype.name

  • Data type routines
  • numpy.dtype
  • index
  • next
  • previous

Previous topic

numpy.dtype.metadata

Next topic

numpy.dtype.names

numpy.dtype.name

dtype.name

A bit-width name for this data-type.

Un-sized flexible data-type objects do not have this attribute.


numpy.dtype.names

  • Data type routines
  • numpy.dtype
  • index
  • next
  • previous

Previous topic

numpy.dtype.name

Next topic

numpy.dtype.shape

numpy.dtype.names

dtype.names

Ordered list of field names, or None if there are no fields.

The names are ordered according to increasing byte offset. This can be used, for example, to walk through all of the named fields in offset order.

Examples

>>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
>>> dt.names
('name', 'grades')


numpy.dtype.shape

  • Data type routines
  • numpy.dtype
  • index
  • next
  • previous

Previous topic

numpy.dtype.names

Next topic

numpy.dtype.str

numpy.dtype.shape

dtype.shape

Shape tuple of the sub-array if this data type describes a sub-array, and () otherwise.


numpy.dtype.str

  • Data type routines
  • numpy.dtype
  • index
  • next
  • previous

Previous topic

numpy.dtype.shape

Next topic

numpy.dtype.subdtype

numpy.dtype.str

dtype.str

The array-protocol typestring of this data-type object.


numpy.dtype.subdtype

  • Data type routines
  • numpy.dtype
  • index
  • next
  • previous

Previous topic

numpy.dtype.str

Next topic

numpy.dtype.newbyteorder

numpy.dtype.subdtype

dtype.subdtype

Tuple (item_dtype, shape) if this dtype describes a sub-array, and None otherwise.

The shape is the fixed shape of the sub-array described by this data type, and item_dtype the data type of the array.

If a field whose dtype object has this attribute is retrieved, then the extra dimensions implied by shape are tacked on to the end of the retrieved array.


numpy.dtype.newbyteorder

  • Data type routines
  • numpy.dtype
  • index
  • next
  • previous

Previous topic

numpy.dtype.subdtype

Next topic

numpy.format_parser

numpy.dtype.newbyteorder

dtype.newbyteorder(new_order='S')

Return a new dtype with a different byte order.

Changes are also made in all fields and sub-arrays of the data type.

Parameters:

new_order : string, optional

Byte order to force; a value from the byte order specifications below. The default value (‘S’) results in swapping the current byte order. new_order codes can be any of:

* 'S' - swap dtype from current to opposite endian
* {'<', 'L'} - little endian
* {'>', 'B'} - big endian
* {'=', 'N'} - native order
* {'|', 'I'} - ignore (no change to byte order)

The code does a case-insensitive check on the first letter of new_order for these alternatives. For example, any of ‘>’ or ‘B’ or ‘b’ or ‘brian’ are valid to specify big-endian.
Returns:

new_dtype : dtype

New dtype object with the given change to the byte order.

Notes

Changes are also made in all fields and sub-arrays of the data type.

Examples

>>> import sys
>>> sys_is_le = sys.byteorder == 'little'
>>> native_code = sys_is_le and '<' or '>'
>>> swapped_code = sys_is_le and '>' or '<'
>>> native_dt = np.dtype(native_code+'i2')
>>> swapped_dt = np.dtype(swapped_code+'i2')
>>> native_dt.newbyteorder('S') == swapped_dt
True
>>> native_dt.newbyteorder() == swapped_dt
True
>>> native_dt == swapped_dt.newbyteorder('S')
True
>>> native_dt == swapped_dt.newbyteorder('=')
True
>>> native_dt == swapped_dt.newbyteorder('N')
True
>>> native_dt == native_dt.newbyteorder('|')
True
>>> np.dtype('<i2') == native_dt.newbyteorder('<')
True
>>> np.dtype('<i2') == native_dt.newbyteorder('L')
True
>>> np.dtype('>i2') == native_dt.newbyteorder('>')
True
>>> np.dtype('>i2') == native_dt.newbyteorder('B')
True


numpy.dtype.type

  • Array objects
  • Data type objects (dtype)
  • index
  • next
  • previous

Previous topic

numpy.dtype.newbyteorder

Next topic

numpy.dtype.kind

numpy.dtype.type

dtype.type

The type object used to instantiate a scalar of this data-type.


numpy.dtype.kind

  • Array objects
  • Data type objects (dtype)
  • index
  • next
  • previous

Previous topic

numpy.dtype.type

Next topic

numpy.dtype.char

numpy.dtype.kind

dtype.kind

A character code (one of ‘biufcOSUV’) identifying the general kind of data.

b | boolean
i | signed integer
u | unsigned integer
f | floating-point
c | complex floating-point
O | object
S | (byte-)string
U | Unicode
V | void


numpy.dtype.char

  • Array objects
  • Data type objects (dtype)
  • index
  • next
  • previous

Previous topic

numpy.dtype.kind

Next topic

numpy.dtype.num

numpy.dtype.char

dtype.char

A unique character code for each of the 21 different built-in types.


numpy.dtype.num

  • Array objects
  • Data type objects (dtype)
  • index
  • next
  • previous

Previous topic

numpy.dtype.char

Next topic

numpy.dtype.str

numpy.dtype.num

dtype.num

A unique number for each of the 21 different built-in types.

These are roughly ordered from least-to-most precision.


numpy.dtype.itemsize

  • Array objects
  • Data type objects (dtype)
  • index
  • next
  • previous

Previous topic

numpy.dtype.name

Next topic

numpy.dtype.byteorder

numpy.dtype.itemsize

dtype.itemsize

The element size of this data-type object.

For 18 of the 21 types this number is fixed by the data-type. For the flexible data-types, this number can be anything.


numpy.dtype.byteorder

  • Array objects
  • Data type objects (dtype)
  • index
  • next
  • previous

Previous topic

numpy.dtype.itemsize

Next topic

numpy.dtype.fields

numpy.dtype.byteorder

dtype.byteorder

A character indicating the byte-order of this data-type object.

One of:

‘=’ native
‘<’ little-endian
‘>’ big-endian
‘|’ not applicable

All built-in data-type objects have byteorder either ‘=’ or ‘|’.

Examples

>>> dt = np.dtype('i2')
>>> dt.byteorder
'='
>>> # endian is not relevant for 8 bit numbers
>>> np.dtype('i1').byteorder
'|'
>>> # or ASCII strings
>>> np.dtype('S2').byteorder
'|'
>>> # Even if specific code is given, and it is native
>>> # '=' is the byteorder
>>> import sys
>>> sys_is_le = sys.byteorder == 'little'
>>> native_code = sys_is_le and '<' or '>'
>>> swapped_code = sys_is_le and '>' or '<'
>>> dt = np.dtype(native_code + 'i2')
>>> dt.byteorder
'='
>>> # Swapped code shows up as itself
>>> dt = np.dtype(swapped_code + 'i2')
>>> dt.byteorder == swapped_code
True


numpy.dtype.flags

  • Array objects
  • Data type objects (dtype)
  • index
  • next
  • previous

Previous topic

numpy.dtype.hasobject

Next topic

numpy.dtype.isbuiltin

numpy.dtype.flags

dtype.flags

Bit-flags describing how this data type is to be interpreted.

Bit-masks are in numpy.core.multiarray as the constants ITEM_HASOBJECT, LIST_PICKLE, ITEM_IS_POINTER, NEEDS_INIT, NEEDS_PYAPI, USE_GETITEM, USE_SETITEM. A full explanation of these flags is in C-API documentation; they are largely useful for user-defined data-types.


numpy.dtype.alignment

  • Array objects
  • Data type objects (dtype)
  • index
  • next
  • previous

Previous topic

numpy.dtype.descr

Next topic

numpy.dtype.newbyteorder

numpy.dtype.alignment

dtype.alignment

The required alignment (bytes) of this data-type according to the compiler.

More information is available in the C-API section of the manual.


numpy.dtype.__reduce__

  • Array objects
  • Data type objects (dtype)
  • index
  • next
  • previous

Previous topic

numpy.dtype.newbyteorder

Next topic

numpy.dtype.__setstate__

numpy.dtype.__reduce__

dtype.__reduce__()


numpy.dtype.__setstate__

  • Array objects
  • Data type objects (dtype)
  • index
  • next
  • previous

Previous topic

numpy.dtype.__reduce__

Next topic

Indexing

numpy.dtype.__setstate__

dtype.__setstate__()


Indexing

  • Array objects
  • next
  • previous

Table Of Contents

  • Indexing
    • Basic Slicing and Indexing
    • Advanced Indexing
      • Integer array indexing
        • Purely integer array indexing
        • Combining advanced and basic indexing
      • Boolean array indexing
    • Detailed notes
    • Record Access
    • Flat Iterator indexing

Previous topic

numpy.dtype.__setstate__

Next topic

Iterating Over Arrays

Indexing

ndarrays can be indexed using the standard Python x[obj] syntax, where x is the array and obj the selection. There are three kinds of indexing available: record access, basic slicing, advanced indexing. Which one occurs depends on obj.

Note

In Python, x[(exp1, exp2, ..., expN)] is equivalent to x[exp1, exp2, ..., expN]; the latter is just syntactic sugar for the former.

Basic Slicing and Indexing

Basic slicing extends Python’s basic concept of slicing to N dimensions. Basic slicing occurs when obj is a slice object (constructed by start:stop:step notation inside of brackets), an integer, or a tuple of slice objects and integers. Ellipsis and newaxis objects can be interspersed with these as well. In order to remain backward compatible with a common usage in Numeric, basic slicing is also initiated if the selection object is any non-ndarray sequence (such as a list) containing slice objects, the Ellipsis object, or the newaxis object, but not for integer arrays or other embedded sequences.

The simplest case of indexing with N integers returns an array scalar representing the corresponding item. As in Python, all indices are zero-based: for the i-th index [image], the valid range is [image] where [image] is the i-th element of the shape of the array. Negative indices are interpreted as counting from the end of the array (i.e., if n_i < 0, it means n_i + d_i).

All arrays generated by basic slicing are always views of the original array.

The standard rules of sequence slicing apply to basic slicing on a per-dimension basis (including using a step index). Some useful concepts to remember include:

  • The basic slice syntax is i:j:k where i is the starting index, j is the stopping index, and k is the step ( [image]). This selects the m elements (in the corresponding dimension) with index values i, i + k, ..., i + (m - 1) k where [image] and q and r are the quotient and remainder obtained by dividing j - i by k: j - i = q k + r, so that i + (m - 1) k < j.

    Example

    >>> x = np.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
>>> x[1:7:2]
array([1, 3, 5])

  • Negative i and j are interpreted as n + i and n + j where n is the number of elements in the corresponding dimension. Negative k makes stepping go towards smaller indices.

    Example

    >>> x[-2:10]
array([8, 9])
>>> x[-3:3:-1]
array([7, 6, 5, 4])

  • Assume n is the number of elements in the dimension being sliced. Then, if i is not given it defaults to 0 for k > 0 and n - 1 for k < 0 . If j is not given it defaults to n for k > 0 and -1 for k < 0 . If k is not given it defaults to 1. Note that :: is the same as : and means select all indices along this axis.

    Example

    >>> x[5:]
array([5, 6, 7, 8, 9])

  • If the number of objects in the selection tuple is less than N , then : is assumed for any subsequent dimensions.

    Example

    >>> x = np.array([[[1],[2],[3]], [[4],[5],[6]]])
>>> x.shape
(2, 3, 1)
>>> x[1:2]
array([[[4],
        [5],
        [6]]])

  • Ellipsis expand to the number of : objects needed to make a selection tuple of the same length as x.ndim. There may only be a single ellipsis present.

    Example

    >>> x[...,0]
array([[1, 2, 3],
       [4, 5, 6]])

  • Each newaxis object in the selection tuple serves to expand the dimensions of the resulting selection by one unit-length dimension. The added dimension is the position of the newaxis object in the selection tuple.

    Example

    >>> x[:,np.newaxis,:,:].shape
(2, 1, 3, 1)

  • An integer, i, returns the same values as i:i+1 except the dimensionality of the returned object is reduced by 1. In particular, a selection tuple with the p-th element an integer (and all other entries :) returns the corresponding sub-array with dimension N - 1. If N = 1 then the returned object is an array scalar. These objects are explained in Scalars.

  • If the selection tuple has all entries : except the p-th entry which is a slice object i:j:k, then the returned array has dimension N formed by concatenating the sub-arrays returned by integer indexing of elements i, i+k, ..., i + (m - 1) k < j,

  • Basic slicing with more than one non-: entry in the slicing tuple, acts like repeated application of slicing using a single non-: entry, where the non-: entries are successively taken (with all other non-: entries replaced by :). Thus, x[ind1,...,ind2,:] acts like x[ind1][...,ind2,:] under basic slicing.

    Warning

    The above is not true for advanced indexing.

  • You may use slicing to set values in the array, but (unlike lists) you can never grow the array. The size of the value to be set in x[obj] = value must be (broadcastable) to the same shape as x[obj].

Note

Remember that a slicing tuple can always be constructed as obj and used in the x[obj] notation. Slice objects can be used in the construction in place of the [start:stop:step] notation. For example, x[1:10:5,::-1] can also be implemented as obj = (slice(1,10,5), slice(None,None,-1)); x[obj] . This can be useful for constructing generic code that works on arrays of arbitrary dimension.

numpy.newaxis

The newaxis object can be used in all slicing operations to create an axis of length one. :const: newaxis is an alias for ‘None’, and ‘None’ can be used in place of this with the same result.

Advanced Indexing

Advanced indexing is triggered when the selection object, obj, is a non-tuple sequence object, an ndarray (of data type integer or bool), or a tuple with at least one sequence object or ndarray (of data type integer or bool). There are two types of advanced indexing: integer and Boolean.

Advanced indexing always returns a copy of the data (contrast with basic slicing that returns a view).

Warning

The definition of advanced indexing means that x[(1,2,3),] is fundamentally different than x[(1,2,3)]. The latter is equivalent to x[1,2,3] which will trigger basic selection while the former will trigger advanced indexing. Be sure to understand why this is occurs.

Also recognize that x[[1,2,3]] will trigger advanced indexing, whereas x[[1,2,slice(None)]] will trigger basic slicing.

Integer array indexing

Integer array indexing allows selection of arbitrary items in the array based on their N-dimensional index. Each integer array represents a number of indexes into that dimension.

Purely integer array indexing

When the index consists of as many integer arrays as the array being indexed has dimensions, the indexing is straight forward, but different from slicing.

Advanced indexes always are broadcast and iterated as one:

result[i_1, ..., i_M] == x[ind_1[i_1, ..., i_M], ind_2[i_1, ..., i_M],
                           ..., ind_N[i_1, ..., i_M]]

Note that the result shape is identical to the (broadcast) indexing array shapes ind_1, ..., ind_N.

Example

From each row, a specific element should be selected. The row index is just [0, 1, 2] and the column index specifies the element to choose for the corresponding row, here [0, 1, 0]. Using both together the task can be solved using advanced indexing:

>>> x = np.array([[1, 2], [3, 4], [5, 6]])
>>> x[[0, 1, 2], [0, 1, 0]]
array([1, 4, 5])

To achieve a behaviour similar to the basic slicing above, broadcasting can be used. The function ix_ can help with this broadcasting. This is best understood with an example.

Example

From a 4x3 array the corner elements should be selected using advanced indexing. Thus all elements for which the column is one of [0, 2] and the row is one of [0, 3] need to be selected. To use advanced indexing one needs to select all elements explicitly. Using the method explained previously one could write:

>>> x = array([[ 0,  1,  2],
...            [ 3,  4,  5],
...            [ 6,  7,  8],
...            [ 9, 10, 11]])
>>> rows = np.array([[0, 0],
...                  [3, 3]], dtype=np.intp)
>>> columns = np.array([[0, 2],
...                     [0, 2]], dtype=np.intp)
>>> x[rows, columns]
array([[ 0,  2],
       [ 9, 11]])

However, since the indexing arrays above just repeat themselves, broadcasting can be used (compare operations such as rows[:, np.newaxis] + columns) to simplify this:

>>> rows = np.array([0, 3], dtype=np.intp)
>>> columns = np.array([0, 2], dtype=np.intp)
>>> rows[:, np.newaxis]
array([[0],
       [3]])
>>> x[rows[:, np.newaxis], columns]
array([[ 0,  2],
       [ 9, 11]])

This broadcasting can also be achieved using the function ix_:

>>> x[np.ix_(rows, columns)]
array([[ 0,  2],
       [ 9, 11]])

Note that without the np.ix_ call, only the diagonal elements would be selected, as was used in the previous example. This difference is the most important thing to remember about indexing with multiple advanced indexes.

Combining advanced and basic indexing

When there is at least one slice (:), ellipsis (...) or np.newaxis in the index (or the array has more dimensions than there are advanced indexes), then the behaviour can be more complicated. It is like concatenating the indexing result for each advanced index element

In the simplest case, there is only a single advanced index. A single advanced index can for example replace a slice and the result array will be the same, however, it is a copy and may have a different memory layout. A slice is preferable when it is possible.

Example

>>> x[1:2, 1:3]
array([[4, 5]])
>>> x[1:2, [1, 2]]
array([[4, 5]])

The easiest way to understand the situation may be to think in terms of the result shape. There are two parts to the indexing operation, the subspace defined by the basic indexing (excluding integers) and the subspace from the advanced indexing part. Two cases of index combination need to be distinguished:

  • The advanced indexes are separated by a slice, ellipsis or newaxis. For example x[arr1, :, arr2].
  • The advanced indexes are all next to each other. For example x[..., arr1, arr2, :] but not x[arr1, :, 1] since 1 is an advanced index in this regard.

In the first case, the dimensions resulting from the advanced indexing operation come first in the result array, and the subspace dimensions after that. In the second case, the dimensions from the advanced indexing operations are inserted into the result array at the same spot as they were in the initial array (the latter logic is what makes simple advanced indexing behave just like slicing).

Example

Suppose x.shape is (10,20,30) and ind is a (2,3,4)-shaped indexing intp array, then result = x[...,ind,:] has shape (10,2,3,4,30) because the (20,)-shaped subspace has been replaced with a (2,3,4)-shaped broadcasted indexing subspace. If we let i, j, k loop over the (2,3,4)-shaped subspace then result[...,i,j,k,:] = x[...,ind[i,j,k],:]. This example produces the same result as x.take(ind, axis=-2).

Example

Let x.shape be (10,20,30,40,50) and suppose ind_1 and ind_2 can be broadcast to the shape (2,3,4). Then x[:,ind_1,ind_2] has shape (10,2,3,4,40,50) because the (20,30)-shaped subspace from X has been replaced with the (2,3,4) subspace from the indices. However, x[:,ind_1,:,ind_2] has shape (2,3,4,10,30,50) because there is no unambiguous place to drop in the indexing subspace, thus it is tacked-on to the beginning. It is always possible to use .transpose() to move the subspace anywhere desired. Note that this example cannot be replicated using take.

Boolean array indexing

This advanced indexing occurs when obj is an array object of Boolean type, such as may be returned from comparison operators. A single boolean index array is practically identical to x[obj.nonzero()] where, as described above, obj.nonzero() returns a tuple (of length obj.ndim) of integer index arrays showing the True elements of obj. However, it is faster when obj.shape == x.shape.

If obj.ndim == x.ndim, x[obj] returns a 1-dimensional array filled with the elements of x corresponding to the True values of obj. The search order will be C-style (last index varies the fastest). If obj has True values at entries that are outside of the bounds of x, then an index error will be raised. If obj is smaller than x it is identical to filling it with False.

Example

A common use case for this is filtering for desired element values. For example one may wish to select all entries from an array which are not NaN:

>>> x = np.array([[1., 2.], [np.nan, 3.], [np.nan, np.nan]])
>>> x[~np.isnan(x)]
array([ 1.,  2.,  3.])

Or wish to add a constant to all negative elements:

>>> x = np.array([1., -1., -2., 3])
>>> x[x < 0] += 20
>>> x
array([  1.,  19.,  18.,   3.])

In general if an index includes a Boolean array, the result will be identical to inserting obj.nonzero() into the same position and using the integer array indexing mechanism described above. x[ind_1, boolean_array, ind_2] is equivalent to x[(ind_1,) + boolean_array.nonzero() + (ind_2,)].

If there is only one Boolean array and no integer indexing array present, this is straight forward. Care must only be taken to make sure that the boolean index has exactly as many dimensions as it is supposed to work with.

Example

From an array, select all rows which sum up to less or equal two:

>>> x = np.array([[0, 1], [1, 1], [2, 2]])
>>> rowsum = x.sum(-1)
>>> x[rowsum <= 2, :]
array([[0, 1],
       [1, 1]])

But if rowsum would have two dimensions as well:

>>> rowsum = x.sum(-1, keepdims=True)
>>> rowsum.shape
(3, 1)
>>> x[rowsum <= 2, :]    # fails
IndexError: too many indices
>>> x[rowsum <= 2]
array([0, 1])

The last one giving only the first elements because of the extra dimension. Compare rowsum.nonzero() to understand this example.

Combining multiple Boolean indexing arrays or a Boolean with an integer indexing array can best be understood with the obj.nonzero() analogy. The function ix_ also supports boolean arrays and will work without any surprises.

Example

Use boolean indexing to select all rows adding up to an even number. At the same time columns 0 and 2 should be selected with an advanced integer index. Using the ix_ function this can be done with:

>>> x = array([[ 0,  1,  2],
...            [ 3,  4,  5],
...            [ 6,  7,  8],
...            [ 9, 10, 11]])
>>> rows = (x.sum(-1) % 2) == 0
>>> rows
array([False,  True, False,  True], dtype=bool)
>>> columns = [0, 2]
>>> x[np.ix_(rows, columns)]
array([[ 3,  5],
       [ 9, 11]])

Without the np.ix_ call or only the diagonal elements would be selected.

Or without np.ix_ (compare the integer array examples):

>>> rows = rows.nonzero()[0]
>>> x[rows[:, np.newaxis], columns]
array([[ 3,  5],
       [ 9, 11]])

Detailed notes

These are some detailed notes, which are not of importance for day to day indexing (in no particular order):

  • The native NumPy indexing type is intp and may differ from the default integer array type. intp is the smallest data type sufficient to safely index any array; for advanced indexing it may be faster than other types.
  • For advanced assignments, there is in general no guarantee for the iteration order. This means that if an element is set more than once, it is not possible to predict the final result.
  • An empty (tuple) index is a full scalar index into a zero dimensional array. x[()] returns a scalar if x is zero dimensional and a view otherwise. On the other hand x[...] always returns a view.
  • If a zero dimensional array is present in the index and it is a full integer index the result will be a scalar and not a zero dimensional array. (Advanced indexing is not triggered.)
  • When an ellipsis (...) is present but has no size (i.e. replaces zero :) the result will still always be an array. A view if no advanced index is present, otherwise a copy.
  • the nonzero equivalence for Boolean arrays does not hold for zero dimensional boolean arrays.
  • When the result of an advanced indexing operation has no elements but an individual index is out of bounds, whether or not an IndexError is raised is undefined (e.g. x[[], [123]] with 123 being out of bounds).
  • When a casting error occurs during assignment (for example updating a numerical array using a sequence of strings), the array being assigned to may end up in an unpredictable partially updated state. However, if any other error (such as an out of bounds index) occurs, the array will remain unchanged.
  • The memory layout of an advanced indexing result is optimized for each indexing operation and no particular memory order can be assumed.
  • When using a subclass (especially one which manipulates its shape), the default ndarray.__setitem__ behaviour will call __getitem__ for basic indexing but not for advanced indexing. For such a subclass it may be preferable to call ndarray.__setitem__ with a base class ndarray view on the data. This must be done if the subclasses __getitem__ does not return views.

Record Access

See also

Data type objects (dtype), Scalars

If the ndarray object is a record array, i.e. its data type is a record data type, the fields of the array can be accessed by indexing the array with strings, dictionary-like.

Indexing x['field-name'] returns a new view to the array, which is of the same shape as x (except when the field is a sub-array) but of data type x.dtype['field-name'] and contains only the part of the data in the specified field. Also record array scalars can be “indexed” this way.

Indexing into a record array can also be done with a list of field names, e.g. x[['field-name1','field-name2']]. Currently this returns a new array containing a copy of the values in the fields specified in the list. As of NumPy 1.7, returning a copy is being deprecated in favor of returning a view. A copy will continue to be returned for now, but a FutureWarning will be issued when writing to the copy. If you depend on the current behavior, then we suggest copying the returned array explicitly, i.e. use x[[‘field-name1’,’field-name2’]].copy(). This will work with both past and future versions of NumPy.

If the accessed field is a sub-array, the dimensions of the sub-array are appended to the shape of the result.

Example

>>> x = np.zeros((2,2), dtype=[('a', np.int32), ('b', np.float64, (3,3))])
>>> x['a'].shape
(2, 2)
>>> x['a'].dtype
dtype('int32')
>>> x['b'].shape
(2, 2, 3, 3)
>>> x['b'].dtype
dtype('float64')

Flat Iterator indexing

x.flat returns an iterator that will iterate over the entire array (in C-contiguous style with the last index varying the fastest). This iterator object can also be indexed using basic slicing or advanced indexing as long as the selection object is not a tuple. This should be clear from the fact that x.flat is a 1-dimensional view. It can be used for integer indexing with 1-dimensional C-style-flat indices. The shape of any returned array is therefore the shape of the integer indexing object.


Iterating Over Arrays

  • Array objects
  • next
  • previous

Table Of Contents

  • Iterating Over Arrays
    • Single Array Iteration
      • Controlling Iteration Order
      • Modifying Array Values
      • Using an External Loop
      • Tracking an Index or Multi-Index
      • Buffering the Array Elements
      • Iterating as a Specific Data Type
    • Broadcasting Array Iteration
      • Iterator-Allocated Output Arrays
      • Outer Product Iteration
      • Reduction Iteration
    • Putting the Inner Loop in Cython

Previous topic

Indexing

Next topic

Standard array subclasses

Iterating Over Arrays

The iterator object nditer, introduced in NumPy 1.6, provides many flexible ways to visit all the elements of one or more arrays in a systematic fashion. This page introduces some basic ways to use the object for computations on arrays in Python, then concludes with how one can accelerate the inner loop in Cython. Since the Python exposure of nditer is a relatively straightforward mapping of the C array iterator API, these ideas will also provide help working with array iteration from C or C++.

Single Array Iteration

The most basic task that can be done with the nditer is to visit every element of an array. Each element is provided one by one using the standard Python iterator interface.

Example

>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a):
...     print x,
...
0 1 2 3 4 5

An important thing to be aware of for this iteration is that the order is chosen to match the memory layout of the array instead of using a standard C or Fortran ordering. This is done for access efficiency, reflecting the idea that by default one simply wants to visit each element without concern for a particular ordering. We can see this by iterating over the transpose of our previous array, compared to taking a copy of that transpose in C order.

Example

>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a.T):
...     print x,
...
0 1 2 3 4 5

>>> for x in np.nditer(a.T.copy(order='C')):
...     print x,
...
0 3 1 4 2 5

The elements of both a and a.T get traversed in the same order, namely the order they are stored in memory, whereas the elements of a.T.copy(order=’C’) get visited in a different order because they have been put into a different memory layout.

Controlling Iteration Order

There are times when it is important to visit the elements of an array in a specific order, irrespective of the layout of the elements in memory. The nditer object provides an order parameter to control this aspect of iteration. The default, having the behavior described above, is order=’K’ to keep the existing order. This can be overridden with order=’C’ for C order and order=’F’ for Fortran order.

Example

>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a, order='F'):
...     print x,
...
0 3 1 4 2 5
>>> for x in np.nditer(a.T, order='C'):
...     print x,
...
0 3 1 4 2 5

Modifying Array Values

By default, the nditer treats the input array as a read-only object. To modify the array elements, you must specify either read-write or write-only mode. This is controlled with per-operand flags.

Regular assignment in Python simply changes a reference in the local or global variable dictionary instead of modifying an existing variable in place. This means that simply assigning to x will not place the value into the element of the array, but rather switch x from being an array element reference to being a reference to the value you assigned. To actually modify the element of the array, x should be indexed with the ellipsis.

Example

>>> a = np.arange(6).reshape(2,3)
>>> a
array([[0, 1, 2],
       [3, 4, 5]])
>>> for x in np.nditer(a, op_flags=['readwrite']):
...     x[...] = 2 * x
...
>>> a
array([[ 0,  2,  4],
       [ 6,  8, 10]])

Using an External Loop

In all the examples so far, the elements of a are provided by the iterator one at a time, because all the looping logic is internal to the iterator. While this is simple and convenient, it is not very efficient. A better approach is to move the one-dimensional innermost loop into your code, external to the iterator. This way, NumPy’s vectorized operations can be used on larger chunks of the elements being visited.

The nditer will try to provide chunks that are as large as possible to the inner loop. By forcing ‘C’ and ‘F’ order, we get different external loop sizes. This mode is enabled by specifying an iterator flag.

Observe that with the default of keeping native memory order, the iterator is able to provide a single one-dimensional chunk, whereas when forcing Fortran order, it has to provide three chunks of two elements each.

Example

>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a, flags=['external_loop']):
...     print x,
...
[0 1 2 3 4 5]

>>> for x in np.nditer(a, flags=['external_loop'], order='F'):
...     print x,
...
[0 3] [1 4] [2 5]

Tracking an Index or Multi-Index

During iteration, you may want to use the index of the current element in a computation. For example, you may want to visit the elements of an array in memory order, but use a C-order, Fortran-order, or multidimensional index to look up values in a different array.

The Python iterator protocol doesn’t have a natural way to query these additional values from the iterator, so we introduce an alternate syntax for iterating with an nditer. This syntax explicitly works with the iterator object itself, so its properties are readily accessible during iteration. With this looping construct, the current value is accessible by indexing into the iterator, and the index being tracked is the property index or multi_index depending on what was requested.

The Python interactive interpreter unfortunately prints out the values of expressions inside the while loop during each iteration of the loop. We have modified the output in the examples using this looping construct in order to be more readable.

Example

>>> a = np.arange(6).reshape(2,3)
>>> it = np.nditer(a, flags=['f_index'])
>>> while not it.finished:
...     print "%d <%d>" % (it[0], it.index),
...     it.iternext()
...
0 <0> 1 <2> 2 <4> 3 <1> 4 <3> 5 <5>

>>> it = np.nditer(a, flags=['multi_index'])
>>> while not it.finished:
...     print "%d <%s>" % (it[0], it.multi_index),
...     it.iternext()
...
0 <(0, 0)> 1 <(0, 1)> 2 <(0, 2)> 3 <(1, 0)> 4 <(1, 1)> 5 <(1, 2)>

>>> it = np.nditer(a, flags=['multi_index'], op_flags=['writeonly'])
>>> while not it.finished:
...     it[0] = it.multi_index[1] - it.multi_index[0]
...     it.iternext()
...
>>> a
array([[ 0,  1,  2],
       [-1,  0,  1]])

Tracking an index or multi-index is incompatible with using an external loop, because it requires a different index value per element. If you try to combine these flags, the nditer object will raise an exception

Example

>>> a = np.zeros((2,3))
>>> it = np.nditer(a, flags=['c_index', 'external_loop'])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: Iterator flag EXTERNAL_LOOP cannot be used if an index or multi-index is being tracked

Buffering the Array Elements

When forcing an iteration order, we observed that the external loop option may provide the elements in smaller chunks because the elements can’t be visited in the appropriate order with a constant stride. When writing C code, this is generally fine, however in pure Python code this can cause a significant reduction in performance.

By enabling buffering mode, the chunks provided by the iterator to the inner loop can be made larger, significantly reducing the overhead of the Python interpreter. In the example forcing Fortran iteration order, the inner loop gets to see all the elements in one go when buffering is enabled.

Example

>>> a = np.arange(6).reshape(2,3)
>>> for x in np.nditer(a, flags=['external_loop'], order='F'):
...     print x,
...
[0 3] [1 4] [2 5]

>>> for x in np.nditer(a, flags=['external_loop','buffered'], order='F'):
...     print x,
...
[0 3 1 4 2 5]

Iterating as a Specific Data Type

There are times when it is necessary to treat an array as a different data type than it is stored as. For instance, one may want to do all computations on 64-bit floats, even if the arrays being manipulated are 32-bit floats. Except when writing low-level C code, it’s generally better to let the iterator handle the copying or buffering instead of casting the data type yourself in the inner loop.

There are two mechanisms which allow this to be done, temporary copies and buffering mode. With temporary copies, a copy of the entire array is made with the new data type, then iteration is done in the copy. Write access is permitted through a mode which updates the original array after all the iteration is complete. The major drawback of temporary copies is that the temporary copy may consume a large amount of memory, particularly if the iteration data type has a larger itemsize than the original one.

Buffering mode mitigates the memory usage issue and is more cache-friendly than making temporary copies. Except for special cases, where the whole array is needed at once outside the iterator, buffering is recommended over temporary copying. Within NumPy, buffering is used by the ufuncs and other functions to support flexible inputs with minimal memory overhead.

In our examples, we will treat the input array with a complex data type, so that we can take square roots of negative numbers. Without enabling copies or buffering mode, the iterator will raise an exception if the data type doesn’t match precisely.

Example

>>> a = np.arange(6).reshape(2,3) - 3
>>> for x in np.nditer(a, op_dtypes=['complex128']):
...     print np.sqrt(x),
...
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: Iterator operand required copying or buffering, but neither copying nor buffering was enabled

In copying mode, ‘copy’ is specified as a per-operand flag. This is done to provide control in a per-operand fashion. Buffering mode is specified as an iterator flag.

Example

>>> a = np.arange(6).reshape(2,3) - 3
>>> for x in np.nditer(a, op_flags=['readonly','copy'],
...                 op_dtypes=['complex128']):
...     print np.sqrt(x),
...
1.73205080757j 1.41421356237j 1j 0j (1+0j) (1.41421356237+0j)

>>> for x in np.nditer(a, flags=['buffered'], op_dtypes=['complex128']):
...     print np.sqrt(x),
...
1.73205080757j 1.41421356237j 1j 0j (1+0j) (1.41421356237+0j)

The iterator uses NumPy’s casting rules to determine whether a specific conversion is permitted. By default, it enforces ‘safe’ casting. This means, for example, that it will raise an exception if you try to treat a 64-bit float array as a 32-bit float array. In many cases, the rule ‘same_kind’ is the most reasonable rule to use, since it will allow conversion from 64 to 32-bit float, but not from float to int or from complex to float.

Example

>>> a = np.arange(6.)
>>> for x in np.nditer(a, flags=['buffered'], op_dtypes=['float32']):
...     print x,
...
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: Iterator operand 0 dtype could not be cast from dtype('float64') to dtype('float32') according to the rule 'safe'

>>> for x in np.nditer(a, flags=['buffered'], op_dtypes=['float32'],
...                 casting='same_kind'):
...     print x,
...
0.0 1.0 2.0 3.0 4.0 5.0

>>> for x in np.nditer(a, flags=['buffered'], op_dtypes=['int32'], casting='same_kind'):
...     print x,
...
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: Iterator operand 0 dtype could not be cast from dtype('float64') to dtype('int32') according to the rule 'same_kind'

One thing to watch out for is conversions back to the original data type when using a read-write or write-only operand. A common case is to implement the inner loop in terms of 64-bit floats, and use ‘same_kind’ casting to allow the other floating-point types to be processed as well. While in read-only mode, an integer array could be provided, read-write mode will raise an exception because conversion back to the array would violate the casting rule.

Example

>>> a = np.arange(6)
>>> for x in np.nditer(a, flags=['buffered'], op_flags=['readwrite'],
...                 op_dtypes=['float64'], casting='same_kind'):
...     x[...] = x / 2.0
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
TypeError: Iterator requested dtype could not be cast from dtype('float64') to dtype('int64'), the operand 0 dtype, according to the rule 'same_kind'

Broadcasting Array Iteration

NumPy has a set of rules for dealing with arrays that have differing shapes which are applied whenever functions take multiple operands which combine element-wise. This is called broadcasting. The nditer object can apply these rules for you when you need to write such a function.

As an example, we print out the result of broadcasting a one and a two dimensional array together.

Example

>>> a = np.arange(3)
>>> b = np.arange(6).reshape(2,3)
>>> for x, y in np.nditer([a,b]):
...     print "%d:%d" % (x,y),
...
0:0 1:1 2:2 0:3 1:4 2:5

When a broadcasting error occurs, the iterator raises an exception which includes the input shapes to help diagnose the problem.

Example

>>> a = np.arange(2)
>>> b = np.arange(6).reshape(2,3)
>>> for x, y in np.nditer([a,b]):
...     print "%d:%d" % (x,y),
...
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: operands could not be broadcast together with shapes (2) (2,3)

Iterator-Allocated Output Arrays

A common case in NumPy functions is to have outputs allocated based on the broadcasting of the input, and additionally have an optional parameter called ‘out’ where the result will be placed when it is provided. The nditer object provides a convenient idiom that makes it very easy to support this mechanism.

We’ll show how this works by creating a function square which squares its input. Let’s start with a minimal function definition excluding ‘out’ parameter support.

Example

>>> def square(a):
...     it = np.nditer([a, None])
...     for x, y in it:
...          y[...] = x*x
...     return it.operands[1]
...
>>> square([1,2,3])
array([1, 4, 9])

By default, the nditer uses the flags ‘allocate’ and ‘writeonly’ for operands that are passed in as None. This means we were able to provide just the two operands to the iterator, and it handled the rest.

When adding the ‘out’ parameter, we have to explicitly provide those flags, because if someone passes in an array as ‘out’, the iterator will default to ‘readonly’, and our inner loop would fail. The reason ‘readonly’ is the default for input arrays is to prevent confusion about unintentionally triggering a reduction operation. If the default were ‘readwrite’, any broadcasting operation would also trigger a reduction, a topic which is covered later in this document.

While we’re at it, let’s also introduce the ‘no_broadcast’ flag, which will prevent the output from being broadcast. This is important, because we only want one input value for each output. Aggregating more than one input value is a reduction operation which requires special handling. It would already raise an error because reductions must be explicitly enabled in an iterator flag, but the error message that results from disabling broadcasting is much more understandable for end-users. To see how to generalize the square function to a reduction, look at the sum of squares function in the section about Cython.

For completeness, we’ll also add the ‘external_loop’ and ‘buffered’ flags, as these are what you will typically want for performance reasons.

Example

>>> def square(a, out=None):
...     it = np.nditer([a, out],
...             flags = ['external_loop', 'buffered'],
...             op_flags = [['readonly'],
...                         ['writeonly', 'allocate', 'no_broadcast']])
...     for x, y in it:
...         y[...] = x*x
...     return it.operands[1]
...

>>> square([1,2,3])
array([1, 4, 9])

>>> b = np.zeros((3,))
>>> square([1,2,3], out=b)
array([ 1.,  4.,  9.])
>>> b
array([ 1.,  4.,  9.])

>>> square(np.arange(6).reshape(2,3), out=b)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 4, in square
ValueError: non-broadcastable output operand with shape (3) doesn't match the broadcast shape (2,3)

Outer Product Iteration

Any binary operation can be extended to an array operation in an outer product fashion like in outer, and the nditer object provides a way to accomplish this by explicitly mapping the axes of the operands. It is also possible to do this with newaxis indexing, but we will show you how to directly use the nditer op_axes parameter to accomplish this with no intermediate views.

We’ll do a simple outer product, placing the dimensions of the first operand before the dimensions of the second operand. The op_axes parameter needs one list of axes for each operand, and provides a mapping from the iterator’s axes to the axes of the operand.

Suppose the first operand is one dimensional and the second operand is two dimensional. The iterator will have three dimensions, so op_axes will have two 3-element lists. The first list picks out the one axis of the first operand, and is -1 for the rest of the iterator axes, with a final result of [0, -1, -1]. The second list picks out the two axes of the second operand, but shouldn’t overlap with the axes picked out in the first operand. Its list is [-1, 0, 1]. The output operand maps onto the iterator axes in the standard manner, so we can provide None instead of constructing another list.

The operation in the inner loop is a straightforward multiplication. Everything to do with the outer product is handled by the iterator setup.

Example

>>> a = np.arange(3)
>>> b = np.arange(8).reshape(2,4)
>>> it = np.nditer([a, b, None], flags=['external_loop'],
...             op_axes=[[0, -1, -1], [-1, 0, 1], None])
>>> for x, y, z in it:
...     z[...] = x*y
...
>>> it.operands[2]
array([[[ 0,  0,  0,  0],
        [ 0,  0,  0,  0]],
       [[ 0,  1,  2,  3],
        [ 4,  5,  6,  7]],
       [[ 0,  2,  4,  6],
        [ 8, 10, 12, 14]]])

Reduction Iteration

Whenever a writeable operand has fewer elements than the full iteration space, that operand is undergoing a reduction. The nditer object requires that any reduction operand be flagged as read-write, and only allows reductions when ‘reduce_ok’ is provided as an iterator flag.

For a simple example, consider taking the sum of all elements in an array.

Example

>>> a = np.arange(24).reshape(2,3,4)
>>> b = np.array(0)
>>> for x, y in np.nditer([a, b], flags=['reduce_ok', 'external_loop'],
...                     op_flags=[['readonly'], ['readwrite']]):
...     y[...] += x
...
>>> b
array(276)
>>> np.sum(a)
276

Things are a little bit more tricky when combining reduction and allocated operands. Before iteration is started, any reduction operand must be initialized to its starting values. Here’s how we can do this, taking sums along the last axis of a.

Example

>>> a = np.arange(24).reshape(2,3,4)
>>> it = np.nditer([a, None], flags=['reduce_ok', 'external_loop'],
...             op_flags=[['readonly'], ['readwrite', 'allocate']],
...             op_axes=[None, [0,1,-1]])
>>> it.operands[1][...] = 0
>>> for x, y in it:
...     y[...] += x
...
>>> it.operands[1]
array([[ 6, 22, 38],
       [54, 70, 86]])
>>> np.sum(a, axis=2)
array([[ 6, 22, 38],
       [54, 70, 86]])

To do buffered reduction requires yet another adjustment during the setup. Normally the iterator construction involves copying the first buffer of data from the readable arrays into the buffer. Any reduction operand is readable, so it may be read into a buffer. Unfortunately, initialization of the operand after this buffering operation is complete will not be reflected in the buffer that the iteration starts with, and garbage results will be produced.

The iterator flag “delay_bufalloc” is there to allow iterator-allocated reduction operands to exist together with buffering. When this flag is set, the iterator will leave its buffers uninitialized until it receives a reset, after which it will be ready for regular iteration. Here’s how the previous example looks if we also enable buffering.

Example

>>> a = np.arange(24).reshape(2,3,4)
>>> it = np.nditer([a, None], flags=['reduce_ok', 'external_loop',
...                                  'buffered', 'delay_bufalloc'],
...             op_flags=[['readonly'], ['readwrite', 'allocate']],
...             op_axes=[None, [0,1,-1]])
>>> it.operands[1][...] = 0
>>> it.reset()
>>> for x, y in it:
...     y[...] += x
...
>>> it.operands[1]
array([[ 6, 22, 38],
       [54, 70, 86]])

Putting the Inner Loop in Cython

Those who want really good performance out of their low level operations should strongly consider directly using the iteration API provided in C, but for those who are not comfortable with C or C++, Cython is a good middle ground with reasonable performance tradeoffs. For the nditer object, this means letting the iterator take care of broadcasting, dtype conversion, and buffering, while giving the inner loop to Cython.

For our example, we’ll create a sum of squares function. To start, let’s implement this function in straightforward Python. We want to support an ‘axis’ parameter similar to the numpy sum function, so we will need to construct a list for the op_axes parameter. Here’s how this looks.

Example

>>> def axis_to_axeslist(axis, ndim):
...     if axis is None:
...         return [-1] * ndim
...     else:
...         if type(axis) is not tuple:
...             axis = (axis,)
...         axeslist = [1] * ndim
...         for i in axis:
...             axeslist[i] = -1
...         ax = 0
...         for i in range(ndim):
...             if axeslist[i] != -1:
...                 axeslist[i] = ax
...                 ax += 1
...         return axeslist
...
>>> def sum_squares_py(arr, axis=None, out=None):
...     axeslist = axis_to_axeslist(axis, arr.ndim)
...     it = np.nditer([arr, out], flags=['reduce_ok', 'external_loop',
...                                       'buffered', 'delay_bufalloc'],
...                 op_flags=[['readonly'], ['readwrite', 'allocate']],
...                 op_axes=[None, axeslist],
...                 op_dtypes=['float64', 'float64'])
...     it.operands[1][...] = 0
...     it.reset()
...     for x, y in it:
...         y[...] += x*x
...     return it.operands[1]
...
>>> a = np.arange(6).reshape(2,3)
>>> sum_squares_py(a)
array(55.0)
>>> sum_squares_py(a, axis=-1)
array([  5.,  50.])

To Cython-ize this function, we replace the inner loop (y[...] += x*x) with Cython code that’s specialized for the float64 dtype. With the ‘external_loop’ flag enabled, the arrays provided to the inner loop will always be one-dimensional, so very little checking needs to be done.

Here’s the listing of sum_squares.pyx:

import numpy as np
cimport numpy as np
cimport cython

def axis_to_axeslist(axis, ndim):
    if axis is None:
        return [-1] * ndim
    else:
        if type(axis) is not tuple:
            axis = (axis,)
        axeslist = [1] * ndim
        for i in axis:
            axeslist[i] = -1
        ax = 0
        for i in range(ndim):
            if axeslist[i] != -1:
                axeslist[i] = ax
                ax += 1
        return axeslist

@cython.boundscheck(False)
def sum_squares_cy(arr, axis=None, out=None):
    cdef np.ndarray[double] x
    cdef np.ndarray[double] y
    cdef int size
    cdef double value

    axeslist = axis_to_axeslist(axis, arr.ndim)
    it = np.nditer([arr, out], flags=['reduce_ok', 'external_loop',
                                      'buffered', 'delay_bufalloc'],
                op_flags=[['readonly'], ['readwrite', 'allocate']],
                op_axes=[None, axeslist],
                op_dtypes=['float64', 'float64'])
    it.operands[1][...] = 0
    it.reset()
    for xarr, yarr in it:
        x = xarr
        y = yarr
        size = x.shape[0]
        for i in range(size):
           value = x[i]
           y[i] = y[i] + value * value
    return it.operands[1]

On this machine, building the .pyx file into a module looked like the following, but you may have to find some Cython tutorials to tell you the specifics for your system configuration.:

$ cython sum_squares.pyx
$ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -I/usr/include/python2.7 -fno-strict-aliasing -o sum_squares.so sum_squares.c

Running this from the Python interpreter produces the same answers as our native Python/NumPy code did.

Example

>>> from sum_squares import sum_squares_cy
>>> a = np.arange(6).reshape(2,3)
>>> sum_squares_cy(a)
array(55.0)
>>> sum_squares_cy(a, axis=-1)
array([  5.,  50.])

Doing a little timing in IPython shows that the reduced overhead and memory allocation of the Cython inner loop is providing a very nice speedup over both the straightforward Python code and an expression using NumPy’s built-in sum function.:

>>> a = np.random.rand(1000,1000)

>>> timeit sum_squares_py(a, axis=-1)
10 loops, best of 3: 37.1 ms per loop

>>> timeit np.sum(a*a, axis=-1)
10 loops, best of 3: 20.9 ms per loop

>>> timeit sum_squares_cy(a, axis=-1)
100 loops, best of 3: 11.8 ms per loop

>>> np.all(sum_squares_cy(a, axis=-1) == np.sum(a*a, axis=-1))
True

>>> np.all(sum_squares_py(a, axis=-1) == np.sum(a*a, axis=-1))
True


Standard array subclasses

  • Array objects
  • next
  • previous

Table Of Contents

  • Standard array subclasses
    • Special attributes and methods
    • Matrix objects
    • Memory-mapped file arrays
    • Character arrays (numpy.char)
    • Record arrays (numpy.rec)
    • Masked arrays (numpy.ma)
    • Standard container class
    • Array Iterators
      • Default iteration
      • Flat iteration
      • N-dimensional enumeration
      • Iterator for broadcasting

Previous topic

Iterating Over Arrays

Next topic

numpy.matrix.T

Standard array subclasses

The ndarray in NumPy is a “new-style” Python built-in-type. Therefore, it can be inherited from (in Python or in C) if desired. Therefore, it can form a foundation for many useful classes. Often whether to sub-class the array object or to simply use the core array component as an internal part of a new class is a 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 in can be replaced as a single array or does it really require two or more arrays at its core.

Note that asarray always returns the base-class ndarray. If you are confident that your use of the array object can handle any subclass of an ndarray, then asanyarray can be used to allow subclasses to propagate more cleanly through your subroutine. In principal a subclass could redefine any aspect of the array and therefore, under strict guidelines, 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 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.

Special attributes and methods

See also

Subclassing ndarray

Numpy provides several hooks that classes can customize:

class.__numpy_ufunc__(self, ufunc, method, i, inputs, **kwargs)

New in version 1.10.

Any class (ndarray subclass or not) can define this method to override behavior of Numpy’s ufuncs. This works quite similarly to Python’s __mul__ and other binary operation routines.

  • ufunc is the ufunc object that was called.
  • method is a string indicating which Ufunc method was called (one of "__call__", "reduce", "reduceat", "accumulate", "outer", "inner").
  • i is the index of self in inputs.
  • inputs is a tuple of the input arguments to the ufunc
  • kwargs is a dictionary containing the optional input arguments of the ufunc. The out argument is always contained in kwargs, if given. See the discussion in Universal functions (ufunc) for details.

The method should return either the result of the operation, or NotImplemented if the operation requested is not implemented.

If one of the arguments has a __numpy_ufunc__ method, it is executed instead of the ufunc. If more than one of the input arguments implements __numpy_ufunc__, they are tried in the order: subclasses before superclasses, otherwise left to right. The first routine returning something else than NotImplemented determines the result. If all of the __numpy_ufunc__ operations return NotImplemented, a TypeError is raised.

If an ndarray subclass defines the __numpy_ufunc__ method, this disables the __array_wrap__, __array_prepare__, __array_priority__ mechanism described below.

Note

In addition to ufuncs, __numpy_ufunc__ also overrides the behavior of numpy.dot even though it is not an Ufunc.

Note

If you also define right-hand binary operator override methods (such as __rmul__) or comparison operations (such as __gt__) in your class, they take precedence over the __numpy_ufunc__ mechanism when resolving results of binary operations (such as ndarray_obj * your_obj).

The technical special case is: ndarray.__mul__ returns NotImplemented if the other object is not a subclass of ndarray, and defines both __numpy_ufunc__ and __rmul__. Similar exception applies for the other operations than multiplication.

In such a case, when computing a binary operation such as ndarray_obj * your_obj, your __numpy_ufunc__ method will not be called. Instead, the execution passes on to your right-hand __rmul__ operation, as per standard Python operator override rules.

Similar special case applies to in-place operations: If you define __rmul__, then ndarray_obj *= your_obj will not call your __numpy_ufunc__ implementation. Instead, the default Python behavior ndarray_obj = ndarray_obj * your_obj occurs.

Note that the above discussion applies only to Python’s builtin binary operation mechanism. np.multiply(ndarray_obj, your_obj) always calls only your __numpy_ufunc__, as expected.

class.__array_finalize__(self)

This method is called whenever the system internally allocates a new array from obj, where obj is a subclass (subtype) of the ndarray. It can be used to change attributes of self after construction (so as to ensure a 2-d matrix for example), or to update meta-information from the “parent.” Subclasses inherit a default implementation of this method that does nothing.

class.__array_prepare__(array, context=None)

At the beginning of every ufunc, this method is called on the input object with the highest array priority, or the output object if one was specified. The output array is passed in and whatever is returned is passed to the ufunc. Subclasses inherit a default implementation of this method which simply returns the output array unmodified. Subclasses may opt to use this method to transform the output array into an instance of the subclass and update metadata before returning the array to the ufunc for computation.

class.__array_wrap__(array, context=None)

At the end of every ufunc, this method is called on the input object with the highest array priority, or the output object if one was specified. The ufunc-computed array is passed in and whatever is returned is passed to the user. Subclasses inherit a default implementation of this method, which transforms the array into a new instance of the object’s class. Subclasses may opt to use this method to transform the output array into an instance of the subclass and update metadata before returning the array to the user.

class.__array_priority__

The value of this attribute is used to determine what type of object to return in situations where there is more than one possibility for the Python type of the returned object. Subclasses inherit a default value of 1.0 for this attribute.

class.__array__([dtype])

If a class (ndarray subclass or not) having the __array__ method is used as the output object of an ufunc, results will be written to the object returned by __array__. Similar conversion is done on input arrays.

Matrix objects

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 unexpected results when you use matrices but expect them to act like arrays:

  1. Matrix objects can be created using a string notation to allow Matlab-style syntax where spaces separate columns and semicolons (‘;’) separate rows.

  2. Matrix objects are always two-dimensional. This has far-reaching implications, in that m.ravel() is still two-dimensional (with a 1 in the first dimension) and item selection returns two-dimensional objects so that sequence behavior is fundamentally different than arrays.

  3. Matrix objects over-ride multiplication to be matrix-multiplication. Make sure you understand this for functions that you may want to receive matrices. Especially in light of the fact that asanyarray(m) returns a matrix when m is a matrix.

  4. Matrix objects over-ride power to be matrix raised to a power. The same warning about using power inside a function that uses asanyarray(...) to get an array object holds for this fact.

  5. The default __array_priority__ of matrix objects is 10.0, and therefore mixed operations with ndarrays always produce matrices.

  6. Matrices have special attributes which make calculations easier. These are

    matrix.T | Returns the transpose of the matrix.
    matrix.H | Returns the (complex) conjugate transpose of self.
    matrix.I | Returns the (multiplicative) inverse of invertible self.
    matrix.A | Return self as an ndarray object.

Warning

Matrix objects over-ride multiplication, ‘*’, and power, ‘**’, to be matrix-multiplication and matrix power, respectively. If your subroutine can accept sub-classes and you do not convert to base- class arrays, then you must use the ufuncs multiply and power to be sure that you are performing the correct operation for all inputs.

The matrix class is a Python subclass of the ndarray and can be used as a reference for how to construct your own subclass of the ndarray. Matrices can be created from other matrices, strings, and anything else that can be converted to an ndarray . The name “mat “is an alias for “matrix “in NumPy.

matrix | Returns a matrix from an array-like object, or from a string of data.
asmatrix(data[, dtype]) | Interpret the input as a matrix.
bmat(obj[, ldict, gdict]) | Build a matrix object from a string, nested sequence, or array.

Example 1: Matrix creation from a string

>>> a=mat('1 2 3; 4 5 3')
>>> print (a*a.T).I
[[ 0.2924 -0.1345]
 [-0.1345  0.0819]]

Example 2: Matrix creation from nested sequence

>>> mat([[1,5,10],[1.0,3,4j]])
matrix([[  1.+0.j,   5.+0.j,  10.+0.j],
        [  1.+0.j,   3.+0.j,   0.+4.j]])

Example 3: Matrix creation from an array

>>> mat(random.rand(3,3)).T
matrix([[ 0.7699,  0.7922,  0.3294],
        [ 0.2792,  0.0101,  0.9219],
        [ 0.3398,  0.7571,  0.8197]])

Memory-mapped file arrays

Memory-mapped files are useful for reading and/or modifying small segments of a large file with regular layout, without reading the entire file into memory. A simple subclass of the ndarray uses a memory-mapped file for the data buffer of the array. For small files, the over-head of reading the entire file into memory is typically not significant, however for large files using memory mapping can save considerable resources.

Memory-mapped-file arrays have one additional method (besides those they inherit from the ndarray): .flush() which must be called manually by the user to ensure that any changes to the array actually get written to disk.

memmap | Create a memory-map to an array stored in a binary file on disk.
memmap.flush() | Write any changes in the array to the file on disk.

Example:

>>> a = memmap('newfile.dat', dtype=float, mode='w+', shape=1000)
>>> a[10] = 10.0
>>> a[30] = 30.0
>>> del a
>>> b = fromfile('newfile.dat', dtype=float)
>>> print b[10], b[30]
10.0 30.0
>>> a = memmap('newfile.dat', dtype=float)
>>> print a[10], a[30]
10.0 30.0

Character arrays (numpy.char)

See also

Creating character arrays (numpy.char)

Note

The chararray class exists for backwards compatibility with Numarray, it is not recommended for new development. Starting from numpy 1.4, if one needs arrays of strings, it is recommended to use arrays of dtype object_, string_ or unicode_, and use the free functions in the numpy.char module for fast vectorized string operations.

These are enhanced arrays of either string_ type or unicode_ type. These arrays inherit from the ndarray, but specially-define the operations +, *, and % on a (broadcasting) element-by-element basis. These operations are not available on the standard ndarray of character type. In addition, the chararray has all of the standard string (and unicode) methods, executing them on an element-by-element basis. Perhaps the easiest way to create a chararray is to use self.view(chararray) where self is an ndarray of str or unicode data-type. However, a chararray can also be created using the numpy.chararray constructor, or via the numpy.char.array function:

chararray | Provides a convenient view on arrays of string and unicode values.
core.defchararray.array(obj[, itemsize, ...]) | Create a chararray.

Another difference with the standard ndarray of str data-type is that the chararray inherits the feature introduced by Numarray that white-space at the end of any element in the array will be ignored on item retrieval and comparison operations.

Record arrays (numpy.rec)

See also

Creating record arrays (numpy.rec), Data type routines, Data type objects (dtype).

Numpy provides the recarray class which allows accessing the fields of a record/structured array as attributes, and a corresponding scalar data type object record.

recarray | Construct an ndarray that allows field access using attributes.
record | A data-type scalar that allows field access as attribute lookup.

Masked arrays (numpy.ma)

See also

Masked arrays

Standard container class

For backward compatibility and as a standard “container “class, the UserArray from Numeric has been brought over to NumPy and named numpy.lib.user_array.container The container class is a Python class whose self.array attribute is an ndarray. Multiple inheritance is probably easier with numpy.lib.user_array.container than with the ndarray itself and so it is included by default. It is not documented here beyond mentioning its existence because you are encouraged to use the ndarray class directly if you can.

numpy.lib.user_array.container(data[, ...])

Methods

Array Iterators

Iterators are a powerful concept for array processing. Essentially, iterators implement a generalized for-loop. If myiter is an iterator object, then the Python code:

for val in myiter:
    ...
    some code involving val
    ...

calls val = myiter.next() repeatedly until StopIteration is raised by the iterator. There are several ways to iterate over an array that may be useful: default iteration, flat iteration, and N -dimensional enumeration.

Default iteration

The default iterator of an ndarray object is the default Python iterator of a sequence type. Thus, when the array object itself is used as an iterator. The default behavior is equivalent to:

for i in range(arr.shape[0]):
    val = arr[i]

This default iterator selects a sub-array of dimension N-1 from the array. This can be a useful construct for defining recursive algorithms. To loop over the entire array requires N for-loops.

>>> a = arange(24).reshape(3,2,4)+10
>>> for val in a:
...     print 'item:', val
item: [[10 11 12 13]
 [14 15 16 17]]
item: [[18 19 20 21]
 [22 23 24 25]]
item: [[26 27 28 29]
 [30 31 32 33]]

Flat iteration

ndarray.flat A 1-D iterator over the array.

As mentioned previously, the flat attribute of ndarray objects returns an iterator that will cycle over the entire array in C-style contiguous order.

>>> for i, val in enumerate(a.flat):
...     if i%5 == 0: print i, val
0 10
5 15
10 20
15 25
20 30

Here, I’ve used the built-in enumerate iterator to return the iterator index as well as the value.

N-dimensional enumeration

ndenumerate(arr) Multidimensional index iterator.

Sometimes it may be useful to get the N-dimensional index while iterating. The ndenumerate iterator can achieve this.

>>> for i, val in ndenumerate(a):
...     if sum(i)%5 == 0: print i, val
(0, 0, 0) 10
(1, 1, 3) 25
(2, 0, 3) 29
(2, 1, 2) 32

Iterator for broadcasting

broadcast Produce an object that mimics broadcasting.

The general concept of broadcasting is also available from Python using the broadcast iterator. This object takes N objects as inputs and returns an iterator that returns tuples providing each of the input sequence elements in the broadcasted result.

>>> for val in broadcast([[1,0],[2,3]],[0,1]):
...     print val
(1, 0)
(0, 1)
(2, 0)
(3, 1)


numpy.matrix.T

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.I

Next topic

numpy.matrix.base

numpy.matrix.T

matrix.T

Returns the transpose of the matrix.

Does not conjugate! For the complex conjugate transpose, use .H.

Parameters:

None
Returns:

ret : matrix object

The (non-conjugated) transpose of the matrix.

See also

transpose, getH

Examples

>>> m = np.matrix('[1, 2; 3, 4]')
>>> m
matrix([[1, 2],
        [3, 4]])
>>> m.getT()
matrix([[1, 3],
        [2, 4]])


numpy.matrix.H

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.A1

Next topic

numpy.matrix.I

numpy.matrix.H

matrix.H

Returns the (complex) conjugate transpose of self.

Equivalent to np.transpose(self) if self is real-valued.

Parameters:

None
Returns:

ret : matrix object

complex conjugate transpose of self

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4)))
>>> z = x - 1j*x; z
matrix([[  0. +0.j,   1. -1.j,   2. -2.j,   3. -3.j],
        [  4. -4.j,   5. -5.j,   6. -6.j,   7. -7.j],
        [  8. -8.j,   9. -9.j,  10.-10.j,  11.-11.j]])
>>> z.getH()
matrix([[  0. +0.j,   4. +4.j,   8. +8.j],
        [  1. +1.j,   5. +5.j,   9. +9.j],
        [  2. +2.j,   6. +6.j,  10.+10.j],
        [  3. +3.j,   7. +7.j,  11.+11.j]])


numpy.matrix.I

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.H

Next topic

numpy.matrix.T

numpy.matrix.I

matrix.I

Returns the (multiplicative) inverse of invertible self.

Parameters:

None
Returns:

ret : matrix object

If self is non-singular, ret is such that ret * self == self * ret == np.matrix(np.eye(self[0,:].size) all return True.
Raises:

numpy.linalg.LinAlgError: Singular matrix

If self is singular.

See also

linalg.inv

Examples

>>> m = np.matrix('[1, 2; 3, 4]'); m
matrix([[1, 2],
        [3, 4]])
>>> m.getI()
matrix([[-2. ,  1. ],
        [ 1.5, -0.5]])
>>> m.getI() * m
matrix([[ 1.,  0.],
        [ 0.,  1.]])


numpy.matrix.A

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix

Next topic

numpy.matrix.A1

numpy.matrix.A

matrix.A

Return self as an ndarray object.

Equivalent to np.asarray(self).

Parameters:

None
Returns:

ret : ndarray

self as an ndarray

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]])
>>> x.getA()
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]])


numpy.matrix

  • Array objects
  • Standard array subclasses
  • index
  • next
  • previous

Previous topic

numpy.broadcast.reset

Next topic

numpy.matrix.A

numpy.matrix

class numpy.matrix [source]

Returns a matrix from an array-like object, or from a string of data. A matrix is a specialized 2-D array that retains its 2-D nature through operations. It has certain special operators, such as * (matrix multiplication) and ** (matrix power).

Parameters:

data : array_like or string

If data is a string, it is interpreted as a matrix with commas or spaces separating columns, and semicolons separating rows.

dtype : data-type

Data-type of the output matrix.

copy : bool

If data is already an ndarray, then this flag determines whether the data is copied (the default), or whether a view is constructed.

See also

array

Examples

>>> a = np.matrix('1 2; 3 4')
>>> print a
[[1 2]
 [3 4]]

>>> np.matrix([[1, 2], [3, 4]])
matrix([[1, 2],
        [3, 4]])

Attributes

A | Return self as an ndarray object.
A1 | Return self as a flattened ndarray.
H | Returns the (complex) conjugate transpose of self.
I | Returns the (multiplicative) inverse of invertible self.
T | Returns the transpose of the matrix.
base | Base object if memory is from some other object.
ctypes | An object to simplify the interaction of the array with the ctypes module.
data | Python buffer object pointing to the start of the array’s data.
dtype | Data-type of the array’s elements.
flags | Information about the memory layout of the array.
flat | A 1-D iterator over the array.
imag | The imaginary part of the array.
itemsize | Length of one array element in bytes.
nbytes | Total bytes consumed by the elements of the array.
ndim | Number of array dimensions.
real | The real part of the array.
shape | Tuple of array dimensions.
size | Number of elements in the array.
strides | Tuple of bytes to step in each dimension when traversing an array.

Methods

all([axis, out]) | Test whether all matrix elements along a given axis evaluate to True.
any([axis, out]) | Test whether any array element along a given axis evaluates to True.
argmax([axis, out]) | Indices of the maximum values along an axis.
argmin([axis, out]) | Return the indices of the minimum values along an axis.
argpartition(kth[, axis, kind, order]) | Returns the indices that would partition this array.
argsort([axis, kind, order]) | Returns the indices that would sort this array.
astype(dtype[, order, casting, subok, copy]) | Copy of the array, cast to a specified type.
byteswap(inplace) | Swap the bytes of the array elements
choose(choices[, out, mode]) | Use an index array to construct a new array from a set of choices.
clip(a_min, a_max[, out]) | Return an array whose values are limited to [a_min, a_max].
compress(condition[, axis, out]) | Return selected slices of this array along given axis.
conj() | Complex-conjugate all elements.
conjugate() | Return the complex conjugate, element-wise.
copy([order]) | Return a copy of the array.
cumprod([axis, dtype, out]) | Return the cumulative product of the elements along the given axis.
cumsum([axis, dtype, out]) | Return the cumulative sum of the elements along the given axis.
diagonal([offset, axis1, axis2]) | Return specified diagonals.
dot(b[, out]) | Dot product of two arrays.
dump(file) | Dump a pickle of the array to the specified file.
dumps() | Returns the pickle of the array as a string.
fill(value) | Fill the array with a scalar value.
flatten([order]) | Return a copy of the array collapsed into one dimension.
getA() | Return self as an ndarray object.
getA1() | Return self as a flattened ndarray.
getH() | Returns the (complex) conjugate transpose of self.
getI() | Returns the (multiplicative) inverse of invertible self.
getT() | Returns the transpose of the matrix.
getfield(dtype[, offset]) | Returns a field of the given array as a certain type.
item(*args) | Copy an element of an array to a standard Python scalar and return it.
itemset(*args) | Insert scalar into an array (scalar is cast to array’s dtype, if possible)
max([axis, out]) | Return the maximum value along an axis.
mean([axis, dtype, out]) | Returns the average of the matrix elements along the given axis.
min([axis, out]) | Return the minimum value along an axis.
newbyteorder([new_order]) | Return the array with the same data viewed with a different byte order.
nonzero() | Return the indices of the elements that are non-zero.
partition(kth[, axis, kind, order]) | Rearranges the elements in the array in such a way that value of the element in kth position is in the position it would be in a sorted array.
prod([axis, dtype, out]) | Return the product of the array elements over the given axis.
ptp([axis, out]) | Peak-to-peak (maximum - minimum) value along the given axis.
put(indices, values[, mode]) | Set a.flat[n] = values[n] for all n in indices.
ravel([order]) | Return a flattened array.
repeat(repeats[, axis]) | Repeat elements of an array.
reshape(shape[, order]) | Returns an array containing the same data with a new shape.
resize(new_shape[, refcheck]) | Change shape and size of array in-place.
round([decimals, out]) | Return a with each element rounded to the given number of decimals.
searchsorted(v[, side, sorter]) | Find indices where elements of v should be inserted in a to maintain order.
setfield(val, dtype[, offset]) | Put a value into a specified place in a field defined by a data-type.
setflags([write, align, uic]) | Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively.
sort([axis, kind, order]) | Sort an array, in-place.
squeeze([axis]) | Remove single-dimensional entries from the shape of a.
std([axis, dtype, out, ddof]) | Return the standard deviation of the array elements along the given axis.
sum([axis, dtype, out]) | Returns the sum of the matrix elements, along the given axis.
swapaxes(axis1, axis2) | Return a view of the array with axis1 and axis2 interchanged.
take(indices[, axis, out, mode]) | Return an array formed from the elements of a at the given indices.
tobytes([order]) | Construct Python bytes containing the raw data bytes in the array.
tofile(fid[, sep, format]) | Write array to a file as text or binary (default).
tolist() | Return the matrix as a (possibly nested) list.
tostring([order]) | Construct Python bytes containing the raw data bytes in the array.
trace([offset, axis1, axis2, dtype, out]) | Return the sum along diagonals of the array.
transpose(*axes) | Returns a view of the array with axes transposed.
var([axis, dtype, out, ddof]) | Returns the variance of the matrix elements, along the given axis.
view([dtype, type]) | New view of array with the same data.


numpy.matrix.A1

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.A

Next topic

numpy.matrix.H

numpy.matrix.A1

matrix.A1

Return self as a flattened ndarray.

Equivalent to np.asarray(x).ravel()

Parameters:

None
Returns:

ret : ndarray

self, 1-D, as an ndarray

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]])
>>> x.getA1()
array([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11])


numpy.matrix.base

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.T

Next topic

numpy.matrix.ctypes

numpy.matrix.base

matrix.base

Base object if memory is from some other object.

Examples

The base of an array that owns its memory is None:

>>> x = np.array([1,2,3,4])
>>> x.base is None
True

Slicing creates a view, whose memory is shared with x:

>>> y = x[2:]
>>> y.base is x
True


numpy.matrix.ctypes

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.base

Next topic

numpy.matrix.data

numpy.matrix.ctypes

matrix.ctypes

An object to simplify the interaction of the array with the ctypes module.

This attribute creates an object that makes it easier to use arrays when calling shared libraries with the ctypes module. The returned object has, among others, data, shape, and strides attributes (see Notes below) which themselves return ctypes objects that can be used as arguments to a shared library.

Parameters:

None
Returns:

c : Python object

Possessing attributes data, shape, strides, etc.

See also

numpy.ctypeslib

Notes

Below are the public attributes of this object which were documented in “Guide to NumPy” (we have omitted undocumented public attributes, as well as documented private attributes):

  • data: A pointer to the memory area of the array as a Python integer. This memory area may contain data that is not aligned, or not in correct byte-order. The memory area may not even be writeable. The array flags and data-type of this array should be respected when passing this attribute to arbitrary C-code to avoid trouble that can include Python crashing. User Beware! The value of this attribute is exactly the same as self._array_interface_[‘data’][0].
  • shape (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the C-integer corresponding to dtype(‘p’) on this platform. This base-type could be c_int, c_long, or c_longlong depending on the platform. The c_intp type is defined accordingly in numpy.ctypeslib. The ctypes array contains the shape of the underlying array.
  • strides (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the same as for the shape attribute. This ctypes array contains the strides information from the underlying array. This strides information is important for showing how many bytes must be jumped to get to the next element in the array.
  • data_as(obj): Return the data pointer cast to a particular c-types object. For example, calling self._as_parameter_ is equivalent to self.data_as(ctypes.c_void_p). Perhaps you want to use the data as a pointer to a ctypes array of floating-point data: self.data_as(ctypes.POINTER(ctypes.c_double)).
  • shape_as(obj): Return the shape tuple as an array of some other c-types type. For example: self.shape_as(ctypes.c_short).
  • strides_as(obj): Return the strides tuple as an array of some other c-types type. For example: self.strides_as(ctypes.c_longlong).

Be careful using the ctypes attribute - especially on temporary arrays or arrays constructed on the fly. For example, calling (a+b).ctypes.data_as(ctypes.c_void_p) returns a pointer to memory that is invalid because the array created as (a+b) is deallocated before the next Python statement. You can avoid this problem using either c=a+b or ct=(a+b).ctypes. In the latter case, ct will hold a reference to the array until ct is deleted or re-assigned.

If the ctypes module is not available, then the ctypes attribute of array objects still returns something useful, but ctypes objects are not returned and errors may be raised instead. In particular, the object will still have the as parameter attribute which will return an integer equal to the data attribute.

Examples

>>> import ctypes
>>> x
array([[0, 1],
       [2, 3]])
>>> x.ctypes.data
30439712
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long))
<ctypes.LP_c_long object at 0x01F01300>
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long)).contents
c_long(0)
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_longlong)).contents
c_longlong(4294967296L)
>>> x.ctypes.shape
<numpy.core._internal.c_long_Array_2 object at 0x01FFD580>
>>> x.ctypes.shape_as(ctypes.c_long)
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides_as(ctypes.c_longlong)
<numpy.core._internal.c_longlong_Array_2 object at 0x01F01300>


numpy.matrix.data

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.ctypes

Next topic

numpy.matrix.dtype

numpy.matrix.data

matrix.data

Python buffer object pointing to the start of the array’s data.


numpy.matrix.dtype

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.data

Next topic

numpy.matrix.flags

numpy.matrix.dtype

matrix.dtype

Data-type of the array’s elements.

Parameters: None
Returns: d : numpy dtype object

See also

numpy.dtype

Examples

>>> x
array([[0, 1],
       [2, 3]])
>>> x.dtype
dtype('int32')
>>> type(x.dtype)
<type 'numpy.dtype'>


numpy.matrix.flags

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.dtype

Next topic

numpy.matrix.flat

numpy.matrix.flags

matrix.flags

Information about the memory layout of the array.

Notes

The flags object can be accessed dictionary-like (as in a.flags['WRITEABLE']), or by using lowercased attribute names (as in a.flags.writeable). Short flag names are only supported in dictionary access.

Only the UPDATEIFCOPY, WRITEABLE, and ALIGNED flags can be changed by the user, via direct assignment to the attribute or dictionary entry, or by calling ndarray.setflags.

The array flags cannot be set arbitrarily:

  • UPDATEIFCOPY can only be set False.
  • ALIGNED can only be set True if the data is truly aligned.
  • WRITEABLE can only be set True if the array owns its own memory or the ultimate owner of the memory exposes a writeable buffer interface or is a string.

Arrays can be both C-style and Fortran-style contiguous simultaneously. This is clear for 1-dimensional arrays, but can also be true for higher dimensional arrays.

Even for contiguous arrays a stride for a given dimension arr.strides[dim] may be arbitrary if arr.shape[dim] == 1 or the array has no elements. It does not generally hold that self.strides[-1] == self.itemsize for C-style contiguous arrays or self.strides[0] == self.itemsize for Fortran-style contiguous arrays is true.

Attributes

C_CONTIGUOUS (C) | The data is in a single, C-style contiguous segment.
F_CONTIGUOUS (F) | The data is in a single, Fortran-style contiguous segment.
OWNDATA (O) | The array owns the memory it uses or borrows it from another object.
WRITEABLE (W) | The data area can be written to. Setting this to False locks the data, making it read-only. A view (slice, etc.) inherits WRITEABLE from its base array at creation time, but a view of a writeable array may be subsequently locked while the base array remains writeable. (The opposite is not true, in that a view of a locked array may not be made writeable. However, currently, locking a base object does not lock any views that already reference it, so under that circumstance it is possible to alter the contents of a locked array via a previously created writeable view onto it.) Attempting to change a non-writeable array raises a RuntimeError exception.
ALIGNED (A) | The data and all elements are aligned appropriately for the hardware.
UPDATEIFCOPY (U) | This array is a copy of some other array. When this array is deallocated, the base array will be updated with the contents of this array.
FNC | F_CONTIGUOUS and not C_CONTIGUOUS.
FORC | F_CONTIGUOUS or C_CONTIGUOUS (one-segment test).
BEHAVED (B) | ALIGNED and WRITEABLE.
CARRAY (CA) | BEHAVED and C_CONTIGUOUS.
FARRAY (FA) | BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS.


numpy.matrix.flat

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.flags

Next topic

numpy.matrix.imag

numpy.matrix.flat

matrix.flat

A 1-D iterator over the array.

This is a numpy.flatiter instance, which acts similarly to, but is not a subclass of, Python’s built-in iterator object.

See also

flatten
Return a copy of the array collapsed into one dimension.

flatiter

Examples

>>> x = np.arange(1, 7).reshape(2, 3)
>>> x
array([[1, 2, 3],
       [4, 5, 6]])
>>> x.flat[3]
4
>>> x.T
array([[1, 4],
       [2, 5],
       [3, 6]])
>>> x.T.flat[3]
5
>>> type(x.flat)
<type 'numpy.flatiter'>

An assignment example:

>>> x.flat = 3; x
array([[3, 3, 3],
       [3, 3, 3]])
>>> x.flat[[1,4]] = 1; x
array([[3, 1, 3],
       [3, 1, 3]])


numpy.matrix.imag

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.flat

Next topic

numpy.matrix.itemsize

numpy.matrix.imag

matrix.imag

The imaginary part of the array.

Examples

>>> x = np.sqrt([1+0j, 0+1j])
>>> x.imag
array([ 0.        ,  0.70710678])
>>> x.imag.dtype
dtype('float64')


numpy.matrix.itemsize

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.imag

Next topic

numpy.matrix.nbytes

numpy.matrix.itemsize

matrix.itemsize

Length of one array element in bytes.

Examples

>>> x = np.array([1,2,3], dtype=np.float64)
>>> x.itemsize
8
>>> x = np.array([1,2,3], dtype=np.complex128)
>>> x.itemsize
16


numpy.matrix.nbytes

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.itemsize

Next topic

numpy.matrix.ndim

numpy.matrix.nbytes

matrix.nbytes

Total bytes consumed by the elements of the array.

Notes

Does not include memory consumed by non-element attributes of the array object.

Examples

>>> x = np.zeros((3,5,2), dtype=np.complex128)
>>> x.nbytes
480
>>> np.prod(x.shape) * x.itemsize
480


numpy.matrix.ndim

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.nbytes

Next topic

numpy.matrix.real

numpy.matrix.ndim

matrix.ndim

Number of array dimensions.

Examples

>>> x = np.array([1, 2, 3])
>>> x.ndim
1
>>> y = np.zeros((2, 3, 4))
>>> y.ndim
3


numpy.matrix.real

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.ndim

Next topic

numpy.matrix.shape

numpy.matrix.real

matrix.real

The real part of the array.

See also

numpy.real
equivalent function

Examples

>>> x = np.sqrt([1+0j, 0+1j])
>>> x.real
array([ 1.        ,  0.70710678])
>>> x.real.dtype
dtype('float64')


numpy.matrix.shape

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.real

Next topic

numpy.matrix.size

numpy.matrix.shape

matrix.shape

Tuple of array dimensions.

Notes

May be used to “reshape” the array, as long as this would not require a change in the total number of elements

Examples

>>> x = np.array([1, 2, 3, 4])
>>> x.shape
(4,)
>>> y = np.zeros((2, 3, 4))
>>> y.shape
(2, 3, 4)
>>> y.shape = (3, 8)
>>> y
array([[ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])
>>> y.shape = (3, 6)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: total size of new array must be unchanged


numpy.matrix.size

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.shape

Next topic

numpy.matrix.strides

numpy.matrix.size

matrix.size

Number of elements in the array.

Equivalent to np.prod(a.shape), i.e., the product of the array’s dimensions.

Examples

>>> x = np.zeros((3, 5, 2), dtype=np.complex128)
>>> x.size
30
>>> np.prod(x.shape)
30


numpy.matrix.strides

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.size

Next topic

numpy.matrix.all

numpy.matrix.strides

matrix.strides

Tuple of bytes to step in each dimension when traversing an array.

The byte offset of element (i[0], i[1], ..., i[n]) in an array a is:

offset = sum(np.array(i) * a.strides)

A more detailed explanation of strides can be found in the “ndarray.rst” file in the NumPy reference guide.

See also

numpy.lib.stride_tricks.as_strided

Notes

Imagine an array of 32-bit integers (each 4 bytes):

x = np.array([[0, 1, 2, 3, 4],
              [5, 6, 7, 8, 9]], dtype=np.int32)

This array is stored in memory as 40 bytes, one after the other (known as a contiguous block of memory). The strides of an array tell us how many bytes we have to skip in memory to move to the next position along a certain axis. For example, we have to skip 4 bytes (1 value) to move to the next column, but 20 bytes (5 values) to get to the same position in the next row. As such, the strides for the array x will be (20, 4).

Examples

>>> y = np.reshape(np.arange(2*3*4), (2,3,4))
>>> y
array([[[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]],
       [[12, 13, 14, 15],
        [16, 17, 18, 19],
        [20, 21, 22, 23]]])
>>> y.strides
(48, 16, 4)
>>> y[1,1,1]
17
>>> offset=sum(y.strides * np.array((1,1,1)))
>>> offset/y.itemsize
17

>>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0)
>>> x.strides
(32, 4, 224, 1344)
>>> i = np.array([3,5,2,2])
>>> offset = sum(i * x.strides)
>>> x[3,5,2,2]
813
>>> offset / x.itemsize
813


numpy.matrix.all

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.strides

Next topic

numpy.matrix.any

numpy.matrix.all

matrix.all(axis=None, out=None) [source]

Test whether all matrix elements along a given axis evaluate to True.

Parameters: See `numpy.all` for complete descriptions

See also

numpy.all

Notes

This is the same as ndarray.all, but it returns a matrix object.

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]])
>>> y = x[0]; y
matrix([[0, 1, 2, 3]])
>>> (x == y)
matrix([[ True,  True,  True,  True],
        [False, False, False, False],
        [False, False, False, False]], dtype=bool)
>>> (x == y).all()
False
>>> (x == y).all(0)
matrix([[False, False, False, False]], dtype=bool)
>>> (x == y).all(1)
matrix([[ True],
        [False],
        [False]], dtype=bool)


numpy.matrix.any

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.all

Next topic

numpy.matrix.argmax

numpy.matrix.any

matrix.any(axis=None, out=None) [source]

Test whether any array element along a given axis evaluates to True.

Refer to numpy.any for full documentation.

Parameters:

axis : int, optional

Axis along which logical OR is performed

out : ndarray, optional

Output to existing array instead of creating new one, must have same shape as expected output
Returns:

any : bool, ndarray

Returns a single bool if axis is None; otherwise, returns ndarray


numpy.matrix.argmax

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.any

Next topic

numpy.matrix.argmin

numpy.matrix.argmax

matrix.argmax(axis=None, out=None) [source]

Indices of the maximum values along an axis.

Parameters: See `numpy.argmax` for complete descriptions

See also

numpy.argmax

Notes

This is the same as ndarray.argmax, but returns a matrix object where ndarray.argmax would return an ndarray.

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]])
>>> x.argmax()
11
>>> x.argmax(0)
matrix([[2, 2, 2, 2]])
>>> x.argmax(1)
matrix([[3],
        [3],
        [3]])


numpy.matrix.argmin

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.argmax

Next topic

numpy.matrix.argpartition

numpy.matrix.argmin

matrix.argmin(axis=None, out=None) [source]

Return the indices of the minimum values along an axis.

Parameters: See `numpy.argmin` for complete descriptions.

See also

numpy.argmin

Notes

This is the same as ndarray.argmin, but returns a matrix object where ndarray.argmin would return an ndarray.

Examples

>>> x = -np.matrix(np.arange(12).reshape((3,4))); x
matrix([[  0,  -1,  -2,  -3],
        [ -4,  -5,  -6,  -7],
        [ -8,  -9, -10, -11]])
>>> x.argmin()
11
>>> x.argmin(0)
matrix([[2, 2, 2, 2]])
>>> x.argmin(1)
matrix([[3],
        [3],
        [3]])


numpy.matrix.argpartition

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.argmin

Next topic

numpy.matrix.argsort

numpy.matrix.argpartition

matrix.argpartition(kth, axis=-1, kind='introselect', order=None)

Returns the indices that would partition this array.

Refer to numpy.argpartition for full documentation.

New in version 1.8.0.

See also

numpy.argpartition
equivalent function


numpy.matrix.argsort

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.argpartition

Next topic

numpy.matrix.astype

numpy.matrix.argsort

matrix.argsort(axis=-1, kind='quicksort', order=None)

Returns the indices that would sort this array.

Refer to numpy.argsort for full documentation.

See also

numpy.argsort
equivalent function


numpy.matrix.astype

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.argsort

Next topic

numpy.matrix.byteswap

numpy.matrix.astype

matrix.astype(dtype, order='K', casting='unsafe', subok=True, copy=True)

Copy of the array, cast to a specified type.

Parameters:

dtype : str or dtype

Typecode or data-type to which the array is cast.

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout order of the result. ‘C’ means C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran contiguous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements appear in memory as possible. Default is ‘K’.

casting : {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

Controls what kind of data casting may occur. Defaults to ‘unsafe’ for backwards compatibility.

  • ‘no’ means the data types should not be cast at all.
  • ‘equiv’ means only byte-order changes are allowed.
  • ‘safe’ means only casts which can preserve values are allowed.
  • ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.
  • ‘unsafe’ means any data conversions may be done.

subok : bool, optional

If True, then sub-classes will be passed-through (default), otherwise the returned array will be forced to be a base-class array.

copy : bool, optional

By default, astype always returns a newly allocated array. If this is set to false, and the dtype, order, and subok requirements are satisfied, the input array is returned instead of a copy.
Returns:

arr_t : ndarray

Unless copy is False and the other conditions for returning the input array are satisfied (see description for copy input paramter), arr_t is a new array of the same shape as the input array, with dtype, order given by dtype, order.
Raises:

ComplexWarning

When casting from complex to float or int. To avoid this, one should use a.real.astype(t).

Notes

Starting in NumPy 1.9, astype method now returns an error if the string dtype to cast to is not long enough in ‘safe’ casting mode to hold the max value of integer/float array that is being casted. Previously the casting was allowed even if the result was truncated.

Examples

>>> x = np.array([1, 2, 2.5])
>>> x
array([ 1. ,  2. ,  2.5])

>>> x.astype(int)
array([1, 2, 2])


numpy.matrix.byteswap

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.astype

Next topic

numpy.matrix.choose

numpy.matrix.byteswap

matrix.byteswap(inplace)

Swap the bytes of the array elements

Toggle between low-endian and big-endian data representation by returning a byteswapped array, optionally swapped in-place.

Parameters:

inplace : bool, optional

If True, swap bytes in-place, default is False.
Returns:

out : ndarray

The byteswapped array. If inplace is True, this is a view to self.

Examples

>>> A = np.array([1, 256, 8755], dtype=np.int16)
>>> map(hex, A)
['0x1', '0x100', '0x2233']
>>> A.byteswap(True)
array([  256,     1, 13090], dtype=int16)
>>> map(hex, A)
['0x100', '0x1', '0x3322']

Arrays of strings are not swapped

>>> A = np.array(['ceg', 'fac'])
>>> A.byteswap()
array(['ceg', 'fac'],
      dtype='|S3')


numpy.matrix.choose

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.byteswap

Next topic

numpy.matrix.clip

numpy.matrix.choose

matrix.choose(choices, out=None, mode='raise')

Use an index array to construct a new array from a set of choices.

Refer to numpy.choose for full documentation.

See also

numpy.choose
equivalent function


numpy.matrix.clip

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.choose

Next topic

numpy.matrix.compress

numpy.matrix.clip

matrix.clip(a_min, a_max, out=None)

Return an array whose values are limited to [a_min, a_max].

Refer to numpy.clip for full documentation.

See also

numpy.clip
equivalent function


numpy.matrix.compress

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.clip

Next topic

numpy.matrix.conj

numpy.matrix.compress

matrix.compress(condition, axis=None, out=None)

Return selected slices of this array along given axis.

Refer to numpy.compress for full documentation.

See also

numpy.compress
equivalent function


numpy.matrix.conj

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.compress

Next topic

numpy.matrix.conjugate

numpy.matrix.conj

matrix.conj()

Complex-conjugate all elements.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.matrix.conjugate

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.conj

Next topic

numpy.matrix.copy

numpy.matrix.conjugate

matrix.conjugate()

Return the complex conjugate, element-wise.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.matrix.copy

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.conjugate

Next topic

numpy.matrix.cumprod

numpy.matrix.copy

matrix.copy(order='C')

Return a copy of the array.

Parameters:

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout of the copy. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible. (Note that this function and :func:numpy.copy are very similar, but have different default values for their order= arguments.)

See also

numpy.copy, numpy.copyto

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
       [0, 0, 0]])

>>> y
array([[1, 2, 3],
       [4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True


numpy.matrix.cumprod

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.copy

Next topic

numpy.matrix.cumsum

numpy.matrix.cumprod

matrix.cumprod(axis=None, dtype=None, out=None)

Return the cumulative product of the elements along the given axis.

Refer to numpy.cumprod for full documentation.

See also

numpy.cumprod
equivalent function


numpy.matrix.cumsum

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.cumprod

Next topic

numpy.matrix.diagonal

numpy.matrix.cumsum

matrix.cumsum(axis=None, dtype=None, out=None)

Return the cumulative sum of the elements along the given axis.

Refer to numpy.cumsum for full documentation.

See also

numpy.cumsum
equivalent function


numpy.matrix.diagonal

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.cumsum

Next topic

numpy.matrix.dot

numpy.matrix.diagonal

matrix.diagonal(offset=0, axis1=0, axis2=1)

Return specified diagonals. In NumPy 1.9 the returned array is a read-only view instead of a copy as in previous NumPy versions. In NumPy 1.10 the read-only restriction will be removed.

Refer to numpy.diagonal for full documentation.

See also

numpy.diagonal
equivalent function


numpy.matrix.dot

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.diagonal

Next topic

numpy.matrix.dump

numpy.matrix.dot

matrix.dot(b, out=None)

Dot product of two arrays.

Refer to numpy.dot for full documentation.

See also

numpy.dot
equivalent function

Examples

>>> a = np.eye(2)
>>> b = np.ones((2, 2)) * 2
>>> a.dot(b)
array([[ 2.,  2.],
       [ 2.,  2.]])

This array method can be conveniently chained:

>>> a.dot(b).dot(b)
array([[ 8.,  8.],
       [ 8.,  8.]])


numpy.matrix.dump

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.dot

Next topic

numpy.matrix.dumps

numpy.matrix.dump

matrix.dump(file)

Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.

Parameters:

file : str

A string naming the dump file.


numpy.matrix.dumps

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.dump

Next topic

numpy.matrix.fill

numpy.matrix.dumps

matrix.dumps()

Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an array.

Parameters: None


numpy.matrix.fill

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.dumps

Next topic

numpy.matrix.flatten

numpy.matrix.fill

matrix.fill(value)

Fill the array with a scalar value.

Parameters:

value : scalar

All elements of a will be assigned this value.

Examples

>>> a = np.array([1, 2])
>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([ 1.,  1.])


numpy.matrix.flatten

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.fill

Next topic

numpy.matrix.getA

numpy.matrix.flatten

matrix.flatten(order='C')

Return a copy of the array collapsed into one dimension.

Parameters:

order : {‘C’, ‘F’, ‘A’}, optional

Whether to flatten in C (row-major), Fortran (column-major) order, or preserve the C/Fortran ordering from a. The default is ‘C’.
Returns:

y : ndarray

A copy of the input array, flattened to one dimension.

See also

ravel
Return a flattened array.
flat
A 1-D flat iterator over the array.

Examples

>>> a = np.array([[1,2], [3,4]])
>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten('F')
array([1, 3, 2, 4])


numpy.matrix.getA

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.flatten

Next topic

numpy.matrix.getA1

numpy.matrix.getA

matrix.getA() [source]

Return self as an ndarray object.

Equivalent to np.asarray(self).

Parameters:

None
Returns:

ret : ndarray

self as an ndarray

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]])
>>> x.getA()
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]])


numpy.matrix.getA1

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.getA

Next topic

numpy.matrix.getH

numpy.matrix.getA1

matrix.getA1() [source]

Return self as a flattened ndarray.

Equivalent to np.asarray(x).ravel()

Parameters:

None
Returns:

ret : ndarray

self, 1-D, as an ndarray

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]])
>>> x.getA1()
array([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11])


numpy.matrix.getH

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.getA1

Next topic

numpy.matrix.getI

numpy.matrix.getH

matrix.getH() [source]

Returns the (complex) conjugate transpose of self.

Equivalent to np.transpose(self) if self is real-valued.

Parameters:

None
Returns:

ret : matrix object

complex conjugate transpose of self

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4)))
>>> z = x - 1j*x; z
matrix([[  0. +0.j,   1. -1.j,   2. -2.j,   3. -3.j],
        [  4. -4.j,   5. -5.j,   6. -6.j,   7. -7.j],
        [  8. -8.j,   9. -9.j,  10.-10.j,  11.-11.j]])
>>> z.getH()
matrix([[  0. +0.j,   4. +4.j,   8. +8.j],
        [  1. +1.j,   5. +5.j,   9. +9.j],
        [  2. +2.j,   6. +6.j,  10.+10.j],
        [  3. +3.j,   7. +7.j,  11.+11.j]])


numpy.matrix.getI

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.getH

Next topic

numpy.matrix.getT

numpy.matrix.getI

matrix.getI() [source]

Returns the (multiplicative) inverse of invertible self.

Parameters:

None
Returns:

ret : matrix object

If self is non-singular, ret is such that ret * self == self * ret == np.matrix(np.eye(self[0,:].size) all return True.
Raises:

numpy.linalg.LinAlgError: Singular matrix

If self is singular.

See also

linalg.inv

Examples

>>> m = np.matrix('[1, 2; 3, 4]'); m
matrix([[1, 2],
        [3, 4]])
>>> m.getI()
matrix([[-2. ,  1. ],
        [ 1.5, -0.5]])
>>> m.getI() * m
matrix([[ 1.,  0.],
        [ 0.,  1.]])


numpy.matrix.getT

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.getI

Next topic

numpy.matrix.getfield

numpy.matrix.getT

matrix.getT() [source]

Returns the transpose of the matrix.

Does not conjugate! For the complex conjugate transpose, use .H.

Parameters:

None
Returns:

ret : matrix object

The (non-conjugated) transpose of the matrix.

See also

transpose, getH

Examples

>>> m = np.matrix('[1, 2; 3, 4]')
>>> m
matrix([[1, 2],
        [3, 4]])
>>> m.getT()
matrix([[1, 3],
        [2, 4]])


numpy.matrix.getfield

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.getT

Next topic

numpy.matrix.item

numpy.matrix.getfield

matrix.getfield(dtype, offset=0)

Returns a field of the given array as a certain type.

A field is a view of the array data with a given data-type. The values in the view are determined by the given type and the offset into the current array in bytes. The offset needs to be such that the view dtype fits in the array dtype; for example an array of dtype complex128 has 16-byte elements. If taking a view with a 32-bit integer (4 bytes), the offset needs to be between 0 and 12 bytes.

Parameters:

dtype : str or dtype

The data type of the view. The dtype size of the view can not be larger than that of the array itself.

offset : int

Number of bytes to skip before beginning the element view.

Examples

>>> x = np.diag([1.+1.j]*2)
>>> x[1, 1] = 2 + 4.j
>>> x
array([[ 1.+1.j,  0.+0.j],
       [ 0.+0.j,  2.+4.j]])
>>> x.getfield(np.float64)
array([[ 1.,  0.],
       [ 0.,  2.]])

By choosing an offset of 8 bytes we can select the complex part of the array for our view:

>>> x.getfield(np.float64, offset=8)
array([[ 1.,  0.],
   [ 0.,  4.]])


numpy.matrix.item

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.getfield

Next topic

numpy.matrix.itemset

numpy.matrix.item

matrix.item(*args)

Copy an element of an array to a standard Python scalar and return it.

Parameters:

*args : Arguments (variable number and type)

  • none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.
  • int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.
  • tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.
Returns:

z : Standard Python scalar object

A copy of the specified element of the array as a suitable Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.item(3)
2
>>> x.item(7)
5
>>> x.item((0, 1))
1
>>> x.item((2, 2))
3


numpy.matrix.itemset

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.item

Next topic

numpy.matrix.max

numpy.matrix.itemset

matrix.itemset(*args)

Insert scalar into an array (scalar is cast to array’s dtype, if possible)

There must be at least 1 argument, and define the last argument as item. Then, a.itemset(*args) is equivalent to but faster than a[args] = item. The item should be a scalar value and args must select a single item in the array a.

Parameters:

*args : Arguments

If one argument: a scalar, only used in case a is of size 1. If two arguments: the last argument is the value to be set and must be a scalar, the first argument specifies a single array element location. It is either an int or a tuple.

Notes

Compared to indexing syntax, itemset provides some speed increase for placing a scalar into a particular location in an ndarray, if you must do this. However, generally this is discouraged: among other problems, it complicates the appearance of the code. Also, when using itemset (and item) inside a loop, be sure to assign the methods to a local variable to avoid the attribute look-up at each loop iteration.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.itemset(4, 0)
>>> x.itemset((2, 2), 9)
>>> x
array([[3, 1, 7],
       [2, 0, 3],
       [8, 5, 9]])


numpy.matrix.max

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.itemset

Next topic

numpy.matrix.mean

numpy.matrix.max

matrix.max(axis=None, out=None) [source]

Return the maximum value along an axis.

Parameters: See `amax` for complete descriptions

See also

amax, ndarray.max

Notes

This is the same as ndarray.max, but returns a matrix object where ndarray.max would return an ndarray.

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]])
>>> x.max()
11
>>> x.max(0)
matrix([[ 8,  9, 10, 11]])
>>> x.max(1)
matrix([[ 3],
        [ 7],
        [11]])


numpy.matrix.mean

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.max

Next topic

numpy.matrix.min

numpy.matrix.mean

matrix.mean(axis=None, dtype=None, out=None) [source]

Returns the average of the matrix elements along the given axis.

Refer to numpy.mean for full documentation.

See also

numpy.mean

Notes

Same as ndarray.mean except that, where that returns an ndarray, this returns a matrix object.

Examples

>>> x = np.matrix(np.arange(12).reshape((3, 4)))
>>> x
matrix([[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]])
>>> x.mean()
5.5
>>> x.mean(0)
matrix([[ 4.,  5.,  6.,  7.]])
>>> x.mean(1)
matrix([[ 1.5],
        [ 5.5],
        [ 9.5]])


numpy.matrix.min

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.mean

Next topic

numpy.matrix.newbyteorder

numpy.matrix.min

matrix.min(axis=None, out=None) [source]

Return the minimum value along an axis.

Parameters: See `amin` for complete descriptions.

See also

amin, ndarray.min

Notes

This is the same as ndarray.min, but returns a matrix object where ndarray.min would return an ndarray.

Examples

>>> x = -np.matrix(np.arange(12).reshape((3,4))); x
matrix([[  0,  -1,  -2,  -3],
        [ -4,  -5,  -6,  -7],
        [ -8,  -9, -10, -11]])
>>> x.min()
-11
>>> x.min(0)
matrix([[ -8,  -9, -10, -11]])
>>> x.min(1)
matrix([[ -3],
        [ -7],
        [-11]])


numpy.matrix.newbyteorder

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.min

Next topic

numpy.matrix.nonzero

numpy.matrix.newbyteorder

matrix.newbyteorder(new_order='S')

Return the array with the same data viewed with a different byte order.

Equivalent to:

arr.view(arr.dtype.newbytorder(new_order))

Changes are also made in all fields and sub-arrays of the array data type.

Parameters:

new_order : string, optional

Byte order to force; a value from the byte order specifications above. new_order codes can be any of:

* 'S' - swap dtype from current to opposite endian
* {'<', 'L'} - little endian
* {'>', 'B'} - big endian
* {'=', 'N'} - native order
* {'|', 'I'} - ignore (no change to byte order)

The default value (‘S’) results in swapping the current byte order. The code does a case-insensitive check on the first letter of new_order for the alternatives above. For example, any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns:

new_arr : array

New array object with the dtype reflecting given change to the byte order.


numpy.matrix.nonzero

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.newbyteorder

Next topic

numpy.matrix.partition

numpy.matrix.nonzero

matrix.nonzero()

Return the indices of the elements that are non-zero.

Refer to numpy.nonzero for full documentation.

See also

numpy.nonzero
equivalent function


numpy.matrix.partition

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.nonzero

Next topic

numpy.matrix.prod

numpy.matrix.partition

matrix.partition(kth, axis=-1, kind='introselect', order=None)

Rearranges the elements in the array in such a way that value of the element in kth position is in the position it would be in a sorted array. All elements smaller than the kth element are moved before this element and all equal or greater are moved behind it. The ordering of the elements in the two partitions is undefined.

New in version 1.8.0.

Parameters:

kth : int or sequence of ints

Element index to partition by. The kth element value will be in its final sorted position and all smaller elements will be moved before it and all equal or greater elements behind it. The order all elements in the partitions is undefined. If provided with a sequence of kth it will partition all elements indexed by kth of them into their sorted position at once.

axis : int, optional

Axis along which to sort. Default is -1, which means sort along the last axis.

kind : {‘introselect’}, optional

Selection algorithm. Default is ‘introselect’.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.

See also

numpy.partition
Return a parititioned copy of an array.
argpartition
Indirect partition.
sort
Full sort.

Notes

See np.partition for notes on the different algorithms.

Examples

>>> a = np.array([3, 4, 2, 1])
>>> a.partition(a, 3)
>>> a
array([2, 1, 3, 4])

>>> a.partition((1, 3))
array([1, 2, 3, 4])


numpy.matrix.prod

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.partition

Next topic

numpy.matrix.ptp

numpy.matrix.prod

matrix.prod(axis=None, dtype=None, out=None) [source]

Return the product of the array elements over the given axis.

Refer to prod for full documentation.

See also

prod, ndarray.prod

Notes

Same as ndarray.prod, except, where that returns an ndarray, this returns a matrix object instead.

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]])
>>> x.prod()
0
>>> x.prod(0)
matrix([[  0,  45, 120, 231]])
>>> x.prod(1)
matrix([[   0],
        [ 840],
        [7920]])


numpy.matrix.ptp

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.prod

Next topic

numpy.matrix.put

numpy.matrix.ptp

matrix.ptp(axis=None, out=None) [source]

Peak-to-peak (maximum - minimum) value along the given axis.

Refer to numpy.ptp for full documentation.

See also

numpy.ptp

Notes

Same as ndarray.ptp, except, where that would return an ndarray object, this returns a matrix object.

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]])
>>> x.ptp()
11
>>> x.ptp(0)
matrix([[8, 8, 8, 8]])
>>> x.ptp(1)
matrix([[3],
        [3],
        [3]])


numpy.matrix.put

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.ptp

Next topic

numpy.matrix.ravel

numpy.matrix.put

matrix.put(indices, values, mode='raise')

Set a.flat[n] = values[n] for all n in indices.

Refer to numpy.put for full documentation.

See also

numpy.put
equivalent function


numpy.matrix.ravel

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.put

Next topic

numpy.matrix.repeat

numpy.matrix.ravel

matrix.ravel([order])

Return a flattened array.

Refer to numpy.ravel for full documentation.

See also

numpy.ravel
equivalent function
ndarray.flat
a flat iterator on the array.


numpy.matrix.repeat

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.ravel

Next topic

numpy.matrix.reshape

numpy.matrix.repeat

matrix.repeat(repeats, axis=None)

Repeat elements of an array.

Refer to numpy.repeat for full documentation.

See also

numpy.repeat
equivalent function


numpy.matrix.reshape

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.repeat

Next topic

numpy.matrix.resize

numpy.matrix.reshape

matrix.reshape(shape, order='C')

Returns an array containing the same data with a new shape.

Refer to numpy.reshape for full documentation.

See also

numpy.reshape
equivalent function


numpy.matrix.resize

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.reshape

Next topic

numpy.matrix.round

numpy.matrix.resize

matrix.resize(new_shape, refcheck=True)

Change shape and size of array in-place.

Parameters:

new_shape : tuple of ints, or n ints

Shape of resized array.

refcheck : bool, optional

If False, reference count will not be checked. Default is True.
Returns:

None
Raises:

ValueError

If a does not own its own data or references or views to it exist, and the data memory must be changed.

SystemError

If the order keyword argument is specified. This behaviour is a bug in NumPy.

See also

resize
Return a new array with the specified shape.

Notes

This reallocates space for the data area if necessary.

Only contiguous arrays (data elements consecutive in memory) can be resized.

The purpose of the reference count check is to make sure you do not use this array as a buffer for another Python object and then reallocate the memory. However, reference counts can increase in other ways so if you are sure that you have not shared the memory for this array with another Python object, then you may safely set refcheck to False.

Examples

Shrinking an array: array is flattened (in the order that the data are stored in memory), resized, and reshaped:

>>> a = np.array([[0, 1], [2, 3]], order='C')
>>> a.resize((2, 1))
>>> a
array([[0],
       [1]])

>>> a = np.array([[0, 1], [2, 3]], order='F')
>>> a.resize((2, 1))
>>> a
array([[0],
       [2]])

Enlarging an array: as above, but missing entries are filled with zeros:

>>> b = np.array([[0, 1], [2, 3]])
>>> b.resize(2, 3) # new_shape parameter doesn't have to be a tuple
>>> b
array([[0, 1, 2],
       [3, 0, 0]])

Referencing an array prevents resizing...

>>> c = a
>>> a.resize((1, 1))
Traceback (most recent call last):
...
ValueError: cannot resize an array that has been referenced ...

Unless refcheck is False:

>>> a.resize((1, 1), refcheck=False)
>>> a
array([[0]])
>>> c
array([[0]])


numpy.matrix.round

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.resize

Next topic

numpy.matrix.searchsorted

numpy.matrix.round

matrix.round(decimals=0, out=None)

Return a with each element rounded to the given number of decimals.

Refer to numpy.around for full documentation.

See also

numpy.around
equivalent function


numpy.matrix.searchsorted

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.round

Next topic

numpy.matrix.setfield

numpy.matrix.searchsorted

matrix.searchsorted(v, side='left', sorter=None)

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See also

numpy.searchsorted
equivalent function


numpy.matrix.setfield

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.searchsorted

Next topic

numpy.matrix.setflags

numpy.matrix.setfield

matrix.setfield(val, dtype, offset=0)

Put a value into a specified place in a field defined by a data-type.

Place val into a‘s field defined by dtype and beginning offset bytes into the field.

Parameters:

val : object

Value to be placed in field.

dtype : dtype object

Data-type of the field in which to place val.

offset : int, optional

The number of bytes into the field at which to place val.
Returns:

None

See also

getfield

Examples

>>> x = np.eye(3)
>>> x.getfield(np.float64)
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
>>> x.setfield(3, np.int32)
>>> x.getfield(np.int32)
array([[3, 3, 3],
       [3, 3, 3],
       [3, 3, 3]])
>>> x
array([[  1.00000000e+000,   1.48219694e-323,   1.48219694e-323],
       [  1.48219694e-323,   1.00000000e+000,   1.48219694e-323],
       [  1.48219694e-323,   1.48219694e-323,   1.00000000e+000]])
>>> x.setfield(np.eye(3), np.int32)
>>> x
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])


numpy.matrix.setflags

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.setfield

Next topic

numpy.matrix.sort

numpy.matrix.setflags

matrix.setflags(write=None, align=None, uic=None)

Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively.

These Boolean-valued flags affect how numpy interprets the memory area used by a (see Notes below). The ALIGNED flag can only be set to True if the data is actually aligned according to the type. The UPDATEIFCOPY flag can never be set to True. The flag WRITEABLE can only be set to True if the array owns its own memory, or the ultimate owner of the memory exposes a writeable buffer interface, or is a string. (The exception for string is made so that unpickling can be done without copying memory.)

Parameters:

write : bool, optional

Describes whether or not a can be written to.

align : bool, optional

Describes whether or not a is aligned properly for its type.

uic : bool, optional

Describes whether or not a is a copy of another “base” array.

Notes

Array flags provide information about how the memory area used for the array is to be interpreted. There are 6 Boolean flags in use, only three of which can be changed by the user: UPDATEIFCOPY, WRITEABLE, and ALIGNED.

WRITEABLE (W) the data area can be written to;

ALIGNED (A) the data and strides are aligned appropriately for the hardware (as determined by the compiler);

UPDATEIFCOPY (U) this array is a copy of some other array (referenced by .base). When this array is deallocated, the base array will be updated with the contents of this array.

All flags can be accessed using their first (upper case) letter as well as the full name.

Examples

>>> y
array([[3, 1, 7],
       [2, 0, 0],
       [8, 5, 9]])
>>> y.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : True
  WRITEABLE : True
  ALIGNED : True
  UPDATEIFCOPY : False
>>> y.setflags(write=0, align=0)
>>> y.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : True
  WRITEABLE : False
  ALIGNED : False
  UPDATEIFCOPY : False
>>> y.setflags(uic=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: cannot set UPDATEIFCOPY flag to True


numpy.matrix.sort

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.setflags

Next topic

numpy.matrix.squeeze

numpy.matrix.sort

matrix.sort(axis=-1, kind='quicksort', order=None)

Sort an array, in-place.

Parameters:

axis : int, optional

Axis along which to sort. Default is -1, which means sort along the last axis.

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm. Default is ‘quicksort’.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.

See also

numpy.sort
Return a sorted copy of an array.
argsort
Indirect sort.
lexsort
Indirect stable sort on multiple keys.
searchsorted
Find elements in sorted array.
partition
Partial sort.

Notes

See sort for notes on the different sorting algorithms.

Examples

>>> a = np.array([[1,4], [3,1]])
>>> a.sort(axis=1)
>>> a
array([[1, 4],
       [1, 3]])
>>> a.sort(axis=0)
>>> a
array([[1, 3],
       [1, 4]])

Use the order keyword to specify a field to use when sorting a structured array:

>>> a = np.array([('a', 2), ('c', 1)], dtype=[('x', 'S1'), ('y', int)])
>>> a.sort(order='y')
>>> a
array([('c', 1), ('a', 2)],
      dtype=[('x', '|S1'), ('y', '<i4')])


numpy.matrix.squeeze

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.sort

Next topic

numpy.matrix.std

numpy.matrix.squeeze

matrix.squeeze(axis=None)

Remove single-dimensional entries from the shape of a.

Refer to numpy.squeeze for full documentation.

See also

numpy.squeeze
equivalent function


numpy.matrix.std

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.squeeze

Next topic

numpy.matrix.sum

numpy.matrix.std

matrix.std(axis=None, dtype=None, out=None, ddof=0) [source]

Return the standard deviation of the array elements along the given axis.

Refer to numpy.std for full documentation.

See also

numpy.std

Notes

This is the same as ndarray.std, except that where an ndarray would be returned, a matrix object is returned instead.

Examples

>>> x = np.matrix(np.arange(12).reshape((3, 4)))
>>> x
matrix([[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]])
>>> x.std()
3.4520525295346629
>>> x.std(0)
matrix([[ 3.26598632,  3.26598632,  3.26598632,  3.26598632]])
>>> x.std(1)
matrix([[ 1.11803399],
        [ 1.11803399],
        [ 1.11803399]])


numpy.matrix.sum

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.std

Next topic

numpy.matrix.swapaxes

numpy.matrix.sum

matrix.sum(axis=None, dtype=None, out=None) [source]

Returns the sum of the matrix elements, along the given axis.

Refer to numpy.sum for full documentation.

See also

numpy.sum

Notes

This is the same as ndarray.sum, except that where an ndarray would be returned, a matrix object is returned instead.

Examples

>>> x = np.matrix([[1, 2], [4, 3]])
>>> x.sum()
10
>>> x.sum(axis=1)
matrix([[3],
        [7]])
>>> x.sum(axis=1, dtype='float')
matrix([[ 3.],
        [ 7.]])
>>> out = np.zeros((1, 2), dtype='float')
>>> x.sum(axis=1, dtype='float', out=out)
matrix([[ 3.],
        [ 7.]])


numpy.matrix.swapaxes

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.sum

Next topic

numpy.matrix.take

numpy.matrix.swapaxes

matrix.swapaxes(axis1, axis2)

Return a view of the array with axis1 and axis2 interchanged.

Refer to numpy.swapaxes for full documentation.

See also

numpy.swapaxes
equivalent function


numpy.matrix.take

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.swapaxes

Next topic

numpy.matrix.tobytes

numpy.matrix.take

matrix.take(indices, axis=None, out=None, mode='raise')

Return an array formed from the elements of a at the given indices.

Refer to numpy.take for full documentation.

See also

numpy.take
equivalent function


numpy.matrix.tobytes

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.take

Next topic

numpy.matrix.tofile

numpy.matrix.tobytes

matrix.tobytes(order='C')

Construct Python bytes containing the raw data bytes in the array.

Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.

New in version 1.9.0.

Parameters:

order : {‘C’, ‘F’, None}, optional

Order of the data for multidimensional arrays: C, Fortran, or the same as for the original array.
Returns:

s : bytes

Python bytes exhibiting a copy of a‘s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]])
>>> x.tobytes()
b'\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x03\x00\x00\x00'


numpy.matrix.tofile

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.tobytes

Next topic

numpy.matrix.tolist

numpy.matrix.tofile

matrix.tofile(fid, sep="", format="%s")

Write array to a file as text or binary (default).

Data is always written in ‘C’ order, independent of the order of a. The data produced by this method can be recovered using the function fromfile().

Parameters:

fid : file or str

An open file object, or a string containing a filename.

sep : str

Separator between array items for text output. If “” (empty), a binary file is written, equivalent to file.write(a.tobytes()).

format : str

Format string for text file output. Each entry in the array is formatted to text by first converting it to the closest Python type, and then using “format” % item.

Notes

This is a convenience function for quick storage of array data. Information on endianness and precision is lost, so this method is not a good choice for files intended to archive data or transport data between machines with different endianness. Some of these problems can be overcome by outputting the data as text files, at the expense of speed and file size.


numpy.matrix.tolist

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.tofile

Next topic

numpy.matrix.tostring

numpy.matrix.tolist

matrix.tolist() [source]

Return the matrix as a (possibly nested) list.

See ndarray.tolist for full documentation.

See also

ndarray.tolist

Examples

>>> x = np.matrix(np.arange(12).reshape((3,4))); x
matrix([[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]])
>>> x.tolist()
[[0, 1, 2, 3], [4, 5, 6, 7], [8, 9, 10, 11]]


numpy.matrix.tostring

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.tolist

Next topic

numpy.matrix.trace

numpy.matrix.tostring

matrix.tostring(order='C')

Construct Python bytes containing the raw data bytes in the array.

Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.

This function is a compatibility alias for tobytes. Despite its name it returns bytes not strings.

Parameters:

order : {‘C’, ‘F’, None}, optional

Order of the data for multidimensional arrays: C, Fortran, or the same as for the original array.
Returns:

s : bytes

Python bytes exhibiting a copy of a‘s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]])
>>> x.tobytes()
b'\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x03\x00\x00\x00'


numpy.matrix.trace

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.tostring

Next topic

numpy.matrix.transpose

numpy.matrix.trace

matrix.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)

Return the sum along diagonals of the array.

Refer to numpy.trace for full documentation.

See also

numpy.trace
equivalent function


numpy.matrix.transpose

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.trace

Next topic

numpy.matrix.var

numpy.matrix.transpose

matrix.transpose(*axes)

Returns a view of the array with axes transposed.

For a 1-D array, this has no effect. (To change between column and row vectors, first cast the 1-D array into a matrix object.) For a 2-D array, this is the usual matrix transpose. For an n-D array, if axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided and a.shape = (i[0], i[1], ... i[n-2], i[n-1]), then a.transpose().shape = (i[n-1], i[n-2], ... i[1], i[0]).

Parameters:

axes : None, tuple of ints, or n ints

  • None or no argument: reverses the order of the axes.
  • tuple of ints: i in the j-th place in the tuple means a‘s i-th axis becomes a.transpose()‘s j-th axis.
  • n ints: same as an n-tuple of the same ints (this form is intended simply as a “convenience” alternative to the tuple form)
Returns:

out : ndarray

View of a, with axes suitably permuted.

See also

ndarray.T
Array property returning the array transposed.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> a
array([[1, 2],
       [3, 4]])
>>> a.transpose()
array([[1, 3],
       [2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
       [2, 4]])
>>> a.transpose(1, 0)
array([[1, 3],
       [2, 4]])


numpy.matrix.var

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.transpose

Next topic

numpy.matrix.view

numpy.matrix.var

matrix.var(axis=None, dtype=None, out=None, ddof=0) [source]

Returns the variance of the matrix elements, along the given axis.

Refer to numpy.var for full documentation.

See also

numpy.var

Notes

This is the same as ndarray.var, except that where an ndarray would be returned, a matrix object is returned instead.

Examples

>>> x = np.matrix(np.arange(12).reshape((3, 4)))
>>> x
matrix([[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]])
>>> x.var()
11.916666666666666
>>> x.var(0)
matrix([[ 10.66666667,  10.66666667,  10.66666667,  10.66666667]])
>>> x.var(1)
matrix([[ 1.25],
        [ 1.25],
        [ 1.25]])


numpy.matrix.view

  • Array objects
  • Standard array subclasses
  • numpy.matrix
  • index
  • next
  • previous

Previous topic

numpy.matrix.var

Next topic

numpy.asmatrix

numpy.matrix.view

matrix.view(dtype=None, type=None)

New view of array with the same data.

Parameters:

dtype : data-type or ndarray sub-class, optional

Data-type descriptor of the returned view, e.g., float32 or int16. The default, None, results in the view having the same data-type as a. This argument can also be specified as an ndarray sub-class, which then specifies the type of the returned object (this is equivalent to setting the type parameter).

type : Python type, optional

Type of the returned view, e.g., ndarray or matrix. Again, the default None results in type preservation.

Notes

a.view() is used two different ways:

a.view(some_dtype) or a.view(dtype=some_dtype) constructs a view of the array’s memory with a different data-type. This can cause a reinterpretation of the bytes of memory.

a.view(ndarray_subclass) or a.view(type=ndarray_subclass) just returns an instance of ndarray_subclass that looks at the same array (same shape, dtype, etc.) This does not cause a reinterpretation of the memory.

For a.view(some_dtype), if some_dtype has a different number of bytes per entry than the previous dtype (for example, converting a regular array to a structured array), then the behavior of the view cannot be predicted just from the superficial appearance of a (shown by print(a)). It also depends on exactly how a is stored in memory. Therefore if a is C-ordered versus fortran-ordered, versus defined as a slice or transpose, etc., the view may give different results.

Examples

>>> x = np.array([(1, 2)], dtype=[('a', np.int8), ('b', np.int8)])

Viewing array data using a different type and dtype:

>>> y = x.view(dtype=np.int16, type=np.matrix)
>>> y
matrix([[513]], dtype=int16)
>>> print type(y)
<class 'numpy.matrixlib.defmatrix.matrix'>

Creating a view on a structured array so it can be used in calculations

>>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)])
>>> xv = x.view(dtype=np.int8).reshape(-1,2)
>>> xv
array([[1, 2],
       [3, 4]], dtype=int8)
>>> xv.mean(0)
array([ 2.,  3.])

Making changes to the view changes the underlying array

>>> xv[0,1] = 20
>>> print x
[(1, 20) (3, 4)]

Using a view to convert an array to a record array:

>>> z = x.view(np.recarray)
>>> z.a
array([1], dtype=int8)

Views share data:

>>> x[0] = (9, 10)
>>> z[0]
(9, 10)

Views that change the dtype size (bytes per entry) should normally be avoided on arrays defined by slices, transposes, fortran-ordering, etc.:

>>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16)
>>> y = x[:, 0:2]
>>> y
array([[1, 2],
       [4, 5]], dtype=int16)
>>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: new type not compatible with array.
>>> z = y.copy()
>>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
array([[(1, 2)],
       [(4, 5)]], dtype=[('width', '<i2'), ('length', '<i2')])


numpy.asmatrix

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.asanyarray

Next topic

numpy.asfarray

numpy.asmatrix

numpy.asmatrix(data, dtype=None) [source]

Interpret the input as a matrix.

Unlike matrix, asmatrix does not make a copy if the input is already a matrix or an ndarray. Equivalent to matrix(data, copy=False).

Parameters:

data : array_like

Input data.
Returns:

mat : matrix

data interpreted as a matrix.

Examples

>>> x = np.array([[1, 2], [3, 4]])

>>> m = np.asmatrix(x)

>>> x[0,0] = 5

>>> m
matrix([[5, 2],
        [3, 4]])


numpy.bmat

  • Array creation routines
  • next
  • previous

Previous topic

numpy.mat

Next topic

Array manipulation routines

numpy.bmat

numpy.bmat(obj, ldict=None, gdict=None) [source]

Build a matrix object from a string, nested sequence, or array.

Parameters:

obj : str or array_like

Input data. Names of variables in the current scope may be referenced, even if obj is a string.
Returns:

out : matrix

Returns a matrix object, which is a specialized 2-D array.

See also

matrix

Examples

>>> A = np.mat('1 1; 1 1')
>>> B = np.mat('2 2; 2 2')
>>> C = np.mat('3 4; 5 6')
>>> D = np.mat('7 8; 9 0')

All the following expressions construct the same block matrix:

>>> np.bmat([[A, B], [C, D]])
matrix([[1, 1, 2, 2],
        [1, 1, 2, 2],
        [3, 4, 7, 8],
        [5, 6, 9, 0]])
>>> np.bmat(np.r_[np.c_[A, B], np.c_[C, D]])
matrix([[1, 1, 2, 2],
        [1, 1, 2, 2],
        [3, 4, 7, 8],
        [5, 6, 9, 0]])
>>> np.bmat('A,B; C,D')
matrix([[1, 1, 2, 2],
        [1, 1, 2, 2],
        [3, 4, 7, 8],
        [5, 6, 9, 0]])


numpy.memmap

  • Input and output
  • next
  • previous

Previous topic

numpy.array_str

Next topic

numpy.memmap.flush

numpy.memmap

class numpy.memmap [source]

Create a memory-map to an array stored in a binary file on disk.

Memory-mapped files are used for accessing small segments of large files on disk, without reading the entire file into memory. Numpy’s memmap’s are array-like objects. This differs from Python’s mmap module, which uses file-like objects.

This subclass of ndarray has some unpleasant interactions with some operations, because it doesn’t quite fit properly as a subclass. An alternative to using this subclass is to create the mmap object yourself, then create an ndarray with ndarray.__new__ directly, passing the object created in its ‘buffer=’ parameter.

This class may at some point be turned into a factory function which returns a view into an mmap buffer.

Delete the memmap instance to close.

Parameters:

filename : str or file-like object

The file name or file object to be used as the array data buffer.

dtype : data-type, optional

The data-type used to interpret the file contents. Default is uint8.

mode : {‘r+’, ‘r’, ‘w+’, ‘c’}, optional

The file is opened in this mode:

‘r’ | Open existing file for reading only.
‘r+’ | Open existing file for reading and writing.
‘w+’ | Create or overwrite existing file for reading and writing.
‘c’ | Copy-on-write: assignments affect data in memory, but changes are not saved to disk. The file on disk is read-only.

Default is ‘r+’.

offset : int, optional

In the file, array data starts at this offset. Since offset is measured in bytes, it should normally be a multiple of the byte-size of dtype. When mode != 'r', even positive offsets beyond end of file are valid; The file will be extended to accommodate the additional data. By default, memmap will start at the beginning of the file, even if filename is a file pointer fp and fp.tell() != 0.

shape : tuple, optional

The desired shape of the array. If mode == 'r' and the number of remaining bytes after offset is not a multiple of the byte-size of dtype, you must specify shape. By default, the returned array will be 1-D with the number of elements determined by file size and data-type.

order : {‘C’, ‘F’}, optional

Specify the order of the ndarray memory layout: C (row-major) or Fortran (column-major). This only has an effect if the shape is greater than 1-D. The default order is ‘C’.

Notes

The memmap object can be used anywhere an ndarray is accepted. Given a memmap fp, isinstance(fp, numpy.ndarray) returns True.

Memory-mapped arrays use the Python memory-map object which (prior to Python 2.5) does not allow files to be larger than a certain size depending on the platform. This size is always < 2GB even on 64-bit systems.

Examples

>>> data = np.arange(12, dtype='float32')
>>> data.resize((3,4))

This example uses a temporary file so that doctest doesn’t write files to your directory. You would use a ‘normal’ filename.

>>> from tempfile import mkdtemp
>>> import os.path as path
>>> filename = path.join(mkdtemp(), 'newfile.dat')

Create a memmap with dtype and shape that matches our data:

>>> fp = np.memmap(filename, dtype='float32', mode='w+', shape=(3,4))
>>> fp
memmap([[ 0.,  0.,  0.,  0.],
        [ 0.,  0.,  0.,  0.],
        [ 0.,  0.,  0.,  0.]], dtype=float32)

Write data to memmap array:

>>> fp[:] = data[:]
>>> fp
memmap([[  0.,   1.,   2.,   3.],
        [  4.,   5.,   6.,   7.],
        [  8.,   9.,  10.,  11.]], dtype=float32)

>>> fp.filename == path.abspath(filename)
True

Deletion flushes memory changes to disk before removing the object:

>>> del fp

Load the memmap and verify data was stored:

>>> newfp = np.memmap(filename, dtype='float32', mode='r', shape=(3,4))
>>> newfp
memmap([[  0.,   1.,   2.,   3.],
        [  4.,   5.,   6.,   7.],
        [  8.,   9.,  10.,  11.]], dtype=float32)

Read-only memmap:

>>> fpr = np.memmap(filename, dtype='float32', mode='r', shape=(3,4))
>>> fpr.flags.writeable
False

Copy-on-write memmap:

>>> fpc = np.memmap(filename, dtype='float32', mode='c', shape=(3,4))
>>> fpc.flags.writeable
True

It’s possible to assign to copy-on-write array, but values are only written into the memory copy of the array, and not written to disk:

>>> fpc
memmap([[  0.,   1.,   2.,   3.],
        [  4.,   5.,   6.,   7.],
        [  8.,   9.,  10.,  11.]], dtype=float32)
>>> fpc[0,:] = 0
>>> fpc
memmap([[  0.,   0.,   0.,   0.],
        [  4.,   5.,   6.,   7.],
        [  8.,   9.,  10.,  11.]], dtype=float32)

File on disk is unchanged:

>>> fpr
memmap([[  0.,   1.,   2.,   3.],
        [  4.,   5.,   6.,   7.],
        [  8.,   9.,  10.,  11.]], dtype=float32)

Offset into a memmap:

>>> fpo = np.memmap(filename, dtype='float32', mode='r', offset=16)
>>> fpo
memmap([  4.,   5.,   6.,   7.,   8.,   9.,  10.,  11.], dtype=float32)

Attributes

filename | (str) Path to the mapped file.
offset | (int) Offset position in the file.
mode | (str) File mode.

Methods

flush() Write any changes in the array to the file on disk.


numpy.memmap.flush

  • Input and output
  • numpy.memmap
  • index
  • next
  • previous

Previous topic

numpy.memmap

Next topic

numpy.set_printoptions

numpy.memmap.flush

memmap.flush() [source]

Write any changes in the array to the file on disk.

For further information, see memmap.

Parameters: None

See also

memmap


numpy.chararray

  • Array objects
  • Standard array subclasses
  • index
  • next
  • previous

Previous topic

numpy.memmap.flush

Next topic

numpy.chararray.T

numpy.chararray

class numpy.chararray [source]

Provides a convenient view on arrays of string and unicode values.

Note

The chararray class exists for backwards compatibility with Numarray, it is not recommended for new development. Starting from numpy 1.4, if one needs arrays of strings, it is recommended to use arrays of dtype object_, string_ or unicode_, and use the free functions in the numpy.char module for fast vectorized string operations.

Versus a regular Numpy array of type str or unicode, this class adds the following functionality:

  1. values automatically have whitespace removed from the end when indexed
  2. comparison operators automatically remove whitespace from the end when comparing values
  3. vectorized string operations are provided as methods (e.g. endswith) and infix operators (e.g. "+", "*", "%")

chararrays should be created using numpy.char.array or numpy.char.asarray, rather than this constructor directly.

This constructor creates the array, using buffer (with offset and strides) if it is not None. If buffer is None, then constructs a new array with strides in “C order”, unless both len(shape) >= 2 and order='Fortran', in which case strides is in “Fortran order”.

Parameters:

shape : tuple

Shape of the array.

itemsize : int, optional

Length of each array element, in number of characters. Default is 1.

unicode : bool, optional

Are the array elements of type unicode (True) or string (False). Default is False.

buffer : int, optional

Memory address of the start of the array data. Default is None, in which case a new array is created.

offset : int, optional

Fixed stride displacement from the beginning of an axis? Default is 0. Needs to be >=0.

strides : array_like of ints, optional

Strides for the array (see ndarray.strides for full description). Default is None.

order : {‘C’, ‘F’}, optional

The order in which the array data is stored in memory: ‘C’ -> “row major” order (the default), ‘F’ -> “column major” (Fortran) order.

Examples

>>> charar = np.chararray((3, 3))
>>> charar[:] = 'a'
>>> charar
chararray([['a', 'a', 'a'],
       ['a', 'a', 'a'],
       ['a', 'a', 'a']],
      dtype='|S1')

>>> charar = np.chararray(charar.shape, itemsize=5)
>>> charar[:] = 'abc'
>>> charar
chararray([['abc', 'abc', 'abc'],
       ['abc', 'abc', 'abc'],
       ['abc', 'abc', 'abc']],
      dtype='|S5')

Attributes

T | Same as self.transpose(), except that self is returned if self.ndim < 2.
base | Base object if memory is from some other object.
ctypes | An object to simplify the interaction of the array with the ctypes module.
data | Python buffer object pointing to the start of the array’s data.
dtype | Data-type of the array’s elements.
flags | Information about the memory layout of the array.
flat | A 1-D iterator over the array.
imag | The imaginary part of the array.
itemsize | Length of one array element in bytes.
nbytes | Total bytes consumed by the elements of the array.
ndim | Number of array dimensions.
real | The real part of the array.
shape | Tuple of array dimensions.
size | Number of elements in the array.
strides | Tuple of bytes to step in each dimension when traversing an array.

Methods

astype(dtype[, order, casting, subok, copy]) | Copy of the array, cast to a specified type.
copy([order]) | Return a copy of the array.
count(sub[, start, end]) | Returns an array with the number of non-overlapping occurrences of substring sub in the range [start, end].
decode([encoding, errors]) | Calls str.decode element-wise.
dump(file) | Dump a pickle of the array to the specified file.
dumps() | Returns the pickle of the array as a string.
encode([encoding, errors]) | Calls str.encode element-wise.
endswith(suffix[, start, end]) | Returns a boolean array which is True where the string element in self ends with suffix, otherwise False.
expandtabs([tabsize]) | Return a copy of each string element where all tab characters are replaced by one or more spaces.
fill(value) | Fill the array with a scalar value.
find(sub[, start, end]) | For each element, return the lowest index in the string where substring sub is found.
flatten([order]) | Return a copy of the array collapsed into one dimension.
getfield(dtype[, offset]) | Returns a field of the given array as a certain type.
index(sub[, start, end]) | Like find, but raises ValueError when the substring is not found.
isalnum() | Returns true for each element if all characters in the string are alphanumeric and there is at least one character, false otherwise.
isalpha() | Returns true for each element if all characters in the string are alphabetic and there is at least one character, false otherwise.
isdecimal() | For each element in self, return True if there are only decimal characters in the element.
isdigit() | Returns true for each element if all characters in the string are digits and there is at least one character, false otherwise.
islower() | Returns true for each element if all cased characters in the string are lowercase and there is at least one cased character, false otherwise.
isnumeric() | For each element in self, return True if there are only numeric characters in the element.
isspace() | Returns true for each element if there are only whitespace characters in the string and there is at least one character, false otherwise.
istitle() | Returns true for each element if the element is a titlecased string and there is at least one character, false otherwise.
isupper() | Returns true for each element if all cased characters in the string are uppercase and there is at least one character, false otherwise.
item(*args) | Copy an element of an array to a standard Python scalar and return it.
join(seq) | Return a string which is the concatenation of the strings in the sequence seq.
ljust(width[, fillchar]) | Return an array with the elements of self left-justified in a string of length width.
lower() | Return an array with the elements of self converted to lowercase.
lstrip([chars]) | For each element in self, return a copy with the leading characters removed.
nonzero() | Return the indices of the elements that are non-zero.
put(indices, values[, mode]) | Set a.flat[n] = values[n] for all n in indices.
ravel([order]) | Return a flattened array.
repeat(repeats[, axis]) | Repeat elements of an array.
replace(old, new[, count]) | For each element in self, return a copy of the string with all occurrences of substring old replaced by new.
reshape(shape[, order]) | Returns an array containing the same data with a new shape.
resize(new_shape[, refcheck]) | Change shape and size of array in-place.
rfind(sub[, start, end]) | For each element in self, return the highest index in the string where substring sub is found, such that sub is contained within [start, end].
rindex(sub[, start, end]) | Like rfind, but raises ValueError when the substring sub is not found.
rjust(width[, fillchar]) | Return an array with the elements of self right-justified in a string of length width.
rsplit([sep, maxsplit]) | For each element in self, return a list of the words in the string, using sep as the delimiter string.
rstrip([chars]) | For each element in self, return a copy with the trailing characters removed.
searchsorted(v[, side, sorter]) | Find indices where elements of v should be inserted in a to maintain order.
setfield(val, dtype[, offset]) | Put a value into a specified place in a field defined by a data-type.
setflags([write, align, uic]) | Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively.
sort([axis, kind, order]) | Sort an array, in-place.
split([sep, maxsplit]) | For each element in self, return a list of the words in the string, using sep as the delimiter string.
splitlines([keepends]) | For each element in self, return a list of the lines in the element, breaking at line boundaries.
squeeze([axis]) | Remove single-dimensional entries from the shape of a.
startswith(prefix[, start, end]) | Returns a boolean array which is True where the string element in self starts with prefix, otherwise False.
strip([chars]) | For each element in self, return a copy with the leading and trailing characters removed.
swapaxes(axis1, axis2) | Return a view of the array with axis1 and axis2 interchanged.
swapcase() | For each element in self, return a copy of the string with uppercase characters converted to lowercase and vice versa.
take(indices[, axis, out, mode]) | Return an array formed from the elements of a at the given indices.
title() | For each element in self, return a titlecased version of the string: words start with uppercase characters, all remaining cased characters are lowercase.
tofile(fid[, sep, format]) | Write array to a file as text or binary (default).
tolist() | Return the array as a (possibly nested) list.
tostring([order]) | Construct Python bytes containing the raw data bytes in the array.
translate(table[, deletechars]) | For each element in self, return a copy of the string where all characters occurring in the optional argument deletechars are removed, and the remaining characters have been mapped through the given translation table.
transpose(*axes) | Returns a view of the array with axes transposed.
upper() | Return an array with the elements of self converted to uppercase.
view([dtype, type]) | New view of array with the same data.
zfill(width) | Return the numeric string left-filled with zeros in a string of length width.
argsort


numpy.chararray.T

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray

Next topic

numpy.chararray.base

numpy.chararray.T

chararray.T

Same as self.transpose(), except that self is returned if self.ndim < 2.

Examples

>>> x = np.array([[1.,2.],[3.,4.]])
>>> x
array([[ 1.,  2.],
       [ 3.,  4.]])
>>> x.T
array([[ 1.,  3.],
       [ 2.,  4.]])
>>> x = np.array([1.,2.,3.,4.])
>>> x
array([ 1.,  2.,  3.,  4.])
>>> x.T
array([ 1.,  2.,  3.,  4.])


numpy.chararray.base

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.T

Next topic

numpy.chararray.ctypes

numpy.chararray.base

chararray.base

Base object if memory is from some other object.

Examples

The base of an array that owns its memory is None:

>>> x = np.array([1,2,3,4])
>>> x.base is None
True

Slicing creates a view, whose memory is shared with x:

>>> y = x[2:]
>>> y.base is x
True


numpy.chararray.ctypes

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.base

Next topic

numpy.chararray.data

numpy.chararray.ctypes

chararray.ctypes

An object to simplify the interaction of the array with the ctypes module.

This attribute creates an object that makes it easier to use arrays when calling shared libraries with the ctypes module. The returned object has, among others, data, shape, and strides attributes (see Notes below) which themselves return ctypes objects that can be used as arguments to a shared library.

Parameters:

None
Returns:

c : Python object

Possessing attributes data, shape, strides, etc.

See also

numpy.ctypeslib

Notes

Below are the public attributes of this object which were documented in “Guide to NumPy” (we have omitted undocumented public attributes, as well as documented private attributes):

  • data: A pointer to the memory area of the array as a Python integer. This memory area may contain data that is not aligned, or not in correct byte-order. The memory area may not even be writeable. The array flags and data-type of this array should be respected when passing this attribute to arbitrary C-code to avoid trouble that can include Python crashing. User Beware! The value of this attribute is exactly the same as self._array_interface_[‘data’][0].
  • shape (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the C-integer corresponding to dtype(‘p’) on this platform. This base-type could be c_int, c_long, or c_longlong depending on the platform. The c_intp type is defined accordingly in numpy.ctypeslib. The ctypes array contains the shape of the underlying array.
  • strides (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the same as for the shape attribute. This ctypes array contains the strides information from the underlying array. This strides information is important for showing how many bytes must be jumped to get to the next element in the array.
  • data_as(obj): Return the data pointer cast to a particular c-types object. For example, calling self._as_parameter_ is equivalent to self.data_as(ctypes.c_void_p). Perhaps you want to use the data as a pointer to a ctypes array of floating-point data: self.data_as(ctypes.POINTER(ctypes.c_double)).
  • shape_as(obj): Return the shape tuple as an array of some other c-types type. For example: self.shape_as(ctypes.c_short).
  • strides_as(obj): Return the strides tuple as an array of some other c-types type. For example: self.strides_as(ctypes.c_longlong).

Be careful using the ctypes attribute - especially on temporary arrays or arrays constructed on the fly. For example, calling (a+b).ctypes.data_as(ctypes.c_void_p) returns a pointer to memory that is invalid because the array created as (a+b) is deallocated before the next Python statement. You can avoid this problem using either c=a+b or ct=(a+b).ctypes. In the latter case, ct will hold a reference to the array until ct is deleted or re-assigned.

If the ctypes module is not available, then the ctypes attribute of array objects still returns something useful, but ctypes objects are not returned and errors may be raised instead. In particular, the object will still have the as parameter attribute which will return an integer equal to the data attribute.

Examples

>>> import ctypes
>>> x
array([[0, 1],
       [2, 3]])
>>> x.ctypes.data
30439712
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long))
<ctypes.LP_c_long object at 0x01F01300>
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long)).contents
c_long(0)
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_longlong)).contents
c_longlong(4294967296L)
>>> x.ctypes.shape
<numpy.core._internal.c_long_Array_2 object at 0x01FFD580>
>>> x.ctypes.shape_as(ctypes.c_long)
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides_as(ctypes.c_longlong)
<numpy.core._internal.c_longlong_Array_2 object at 0x01F01300>


numpy.chararray.data

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.ctypes

Next topic

numpy.chararray.dtype

numpy.chararray.data

chararray.data

Python buffer object pointing to the start of the array’s data.


numpy.chararray.dtype

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.data

Next topic

numpy.chararray.flags

numpy.chararray.dtype

chararray.dtype

Data-type of the array’s elements.

Parameters: None
Returns: d : numpy dtype object

See also

numpy.dtype

Examples

>>> x
array([[0, 1],
       [2, 3]])
>>> x.dtype
dtype('int32')
>>> type(x.dtype)
<type 'numpy.dtype'>


numpy.chararray.flags

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.dtype

Next topic

numpy.chararray.flat

numpy.chararray.flags

chararray.flags

Information about the memory layout of the array.

Notes

The flags object can be accessed dictionary-like (as in a.flags['WRITEABLE']), or by using lowercased attribute names (as in a.flags.writeable). Short flag names are only supported in dictionary access.

Only the UPDATEIFCOPY, WRITEABLE, and ALIGNED flags can be changed by the user, via direct assignment to the attribute or dictionary entry, or by calling ndarray.setflags.

The array flags cannot be set arbitrarily:

  • UPDATEIFCOPY can only be set False.
  • ALIGNED can only be set True if the data is truly aligned.
  • WRITEABLE can only be set True if the array owns its own memory or the ultimate owner of the memory exposes a writeable buffer interface or is a string.

Arrays can be both C-style and Fortran-style contiguous simultaneously. This is clear for 1-dimensional arrays, but can also be true for higher dimensional arrays.

Even for contiguous arrays a stride for a given dimension arr.strides[dim] may be arbitrary if arr.shape[dim] == 1 or the array has no elements. It does not generally hold that self.strides[-1] == self.itemsize for C-style contiguous arrays or self.strides[0] == self.itemsize for Fortran-style contiguous arrays is true.

Attributes

C_CONTIGUOUS (C) | The data is in a single, C-style contiguous segment.
F_CONTIGUOUS (F) | The data is in a single, Fortran-style contiguous segment.
OWNDATA (O) | The array owns the memory it uses or borrows it from another object.
WRITEABLE (W) | The data area can be written to. Setting this to False locks the data, making it read-only. A view (slice, etc.) inherits WRITEABLE from its base array at creation time, but a view of a writeable array may be subsequently locked while the base array remains writeable. (The opposite is not true, in that a view of a locked array may not be made writeable. However, currently, locking a base object does not lock any views that already reference it, so under that circumstance it is possible to alter the contents of a locked array via a previously created writeable view onto it.) Attempting to change a non-writeable array raises a RuntimeError exception.
ALIGNED (A) | The data and all elements are aligned appropriately for the hardware.
UPDATEIFCOPY (U) | This array is a copy of some other array. When this array is deallocated, the base array will be updated with the contents of this array.
FNC | F_CONTIGUOUS and not C_CONTIGUOUS.
FORC | F_CONTIGUOUS or C_CONTIGUOUS (one-segment test).
BEHAVED (B) | ALIGNED and WRITEABLE.
CARRAY (CA) | BEHAVED and C_CONTIGUOUS.
FARRAY (FA) | BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS.


numpy.chararray.flat

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.flags

Next topic

numpy.chararray.imag

numpy.chararray.flat

chararray.flat

A 1-D iterator over the array.

This is a numpy.flatiter instance, which acts similarly to, but is not a subclass of, Python’s built-in iterator object.

See also

flatten
Return a copy of the array collapsed into one dimension.

flatiter

Examples

>>> x = np.arange(1, 7).reshape(2, 3)
>>> x
array([[1, 2, 3],
       [4, 5, 6]])
>>> x.flat[3]
4
>>> x.T
array([[1, 4],
       [2, 5],
       [3, 6]])
>>> x.T.flat[3]
5
>>> type(x.flat)
<type 'numpy.flatiter'>

An assignment example:

>>> x.flat = 3; x
array([[3, 3, 3],
       [3, 3, 3]])
>>> x.flat[[1,4]] = 1; x
array([[3, 1, 3],
       [3, 1, 3]])


numpy.chararray.imag

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.flat

Next topic

numpy.chararray.itemsize

numpy.chararray.imag

chararray.imag

The imaginary part of the array.

Examples

>>> x = np.sqrt([1+0j, 0+1j])
>>> x.imag
array([ 0.        ,  0.70710678])
>>> x.imag.dtype
dtype('float64')


numpy.chararray.itemsize

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.imag

Next topic

numpy.chararray.nbytes

numpy.chararray.itemsize

chararray.itemsize

Length of one array element in bytes.

Examples

>>> x = np.array([1,2,3], dtype=np.float64)
>>> x.itemsize
8
>>> x = np.array([1,2,3], dtype=np.complex128)
>>> x.itemsize
16


numpy.chararray.nbytes

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.itemsize

Next topic

numpy.chararray.ndim

numpy.chararray.nbytes

chararray.nbytes

Total bytes consumed by the elements of the array.

Notes

Does not include memory consumed by non-element attributes of the array object.

Examples

>>> x = np.zeros((3,5,2), dtype=np.complex128)
>>> x.nbytes
480
>>> np.prod(x.shape) * x.itemsize
480


numpy.chararray.ndim

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.nbytes

Next topic

numpy.chararray.real

numpy.chararray.ndim

chararray.ndim

Number of array dimensions.

Examples

>>> x = np.array([1, 2, 3])
>>> x.ndim
1
>>> y = np.zeros((2, 3, 4))
>>> y.ndim
3


numpy.chararray.real

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.ndim

Next topic

numpy.chararray.shape

numpy.chararray.real

chararray.real

The real part of the array.

See also

numpy.real
equivalent function

Examples

>>> x = np.sqrt([1+0j, 0+1j])
>>> x.real
array([ 1.        ,  0.70710678])
>>> x.real.dtype
dtype('float64')


numpy.chararray.shape

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.real

Next topic

numpy.chararray.size

numpy.chararray.shape

chararray.shape

Tuple of array dimensions.

Notes

May be used to “reshape” the array, as long as this would not require a change in the total number of elements

Examples

>>> x = np.array([1, 2, 3, 4])
>>> x.shape
(4,)
>>> y = np.zeros((2, 3, 4))
>>> y.shape
(2, 3, 4)
>>> y.shape = (3, 8)
>>> y
array([[ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])
>>> y.shape = (3, 6)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: total size of new array must be unchanged


numpy.chararray.size

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.shape

Next topic

numpy.chararray.strides

numpy.chararray.size

chararray.size

Number of elements in the array.

Equivalent to np.prod(a.shape), i.e., the product of the array’s dimensions.

Examples

>>> x = np.zeros((3, 5, 2), dtype=np.complex128)
>>> x.size
30
>>> np.prod(x.shape)
30


numpy.chararray.strides

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.size

Next topic

numpy.chararray.astype

numpy.chararray.strides

chararray.strides

Tuple of bytes to step in each dimension when traversing an array.

The byte offset of element (i[0], i[1], ..., i[n]) in an array a is:

offset = sum(np.array(i) * a.strides)

A more detailed explanation of strides can be found in the “ndarray.rst” file in the NumPy reference guide.

See also

numpy.lib.stride_tricks.as_strided

Notes

Imagine an array of 32-bit integers (each 4 bytes):

x = np.array([[0, 1, 2, 3, 4],
              [5, 6, 7, 8, 9]], dtype=np.int32)

This array is stored in memory as 40 bytes, one after the other (known as a contiguous block of memory). The strides of an array tell us how many bytes we have to skip in memory to move to the next position along a certain axis. For example, we have to skip 4 bytes (1 value) to move to the next column, but 20 bytes (5 values) to get to the same position in the next row. As such, the strides for the array x will be (20, 4).

Examples

>>> y = np.reshape(np.arange(2*3*4), (2,3,4))
>>> y
array([[[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]],
       [[12, 13, 14, 15],
        [16, 17, 18, 19],
        [20, 21, 22, 23]]])
>>> y.strides
(48, 16, 4)
>>> y[1,1,1]
17
>>> offset=sum(y.strides * np.array((1,1,1)))
>>> offset/y.itemsize
17

>>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0)
>>> x.strides
(32, 4, 224, 1344)
>>> i = np.array([3,5,2,2])
>>> offset = sum(i * x.strides)
>>> x[3,5,2,2]
813
>>> offset / x.itemsize
813


numpy.chararray.astype

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.strides

Next topic

numpy.chararray.copy

numpy.chararray.astype

chararray.astype(dtype, order='K', casting='unsafe', subok=True, copy=True)

Copy of the array, cast to a specified type.

Parameters:

dtype : str or dtype

Typecode or data-type to which the array is cast.

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout order of the result. ‘C’ means C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran contiguous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements appear in memory as possible. Default is ‘K’.

casting : {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

Controls what kind of data casting may occur. Defaults to ‘unsafe’ for backwards compatibility.

  • ‘no’ means the data types should not be cast at all.
  • ‘equiv’ means only byte-order changes are allowed.
  • ‘safe’ means only casts which can preserve values are allowed.
  • ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.
  • ‘unsafe’ means any data conversions may be done.

subok : bool, optional

If True, then sub-classes will be passed-through (default), otherwise the returned array will be forced to be a base-class array.

copy : bool, optional

By default, astype always returns a newly allocated array. If this is set to false, and the dtype, order, and subok requirements are satisfied, the input array is returned instead of a copy.
Returns:

arr_t : ndarray

Unless copy is False and the other conditions for returning the input array are satisfied (see description for copy input paramter), arr_t is a new array of the same shape as the input array, with dtype, order given by dtype, order.
Raises:

ComplexWarning

When casting from complex to float or int. To avoid this, one should use a.real.astype(t).

Notes

Starting in NumPy 1.9, astype method now returns an error if the string dtype to cast to is not long enough in ‘safe’ casting mode to hold the max value of integer/float array that is being casted. Previously the casting was allowed even if the result was truncated.

Examples

>>> x = np.array([1, 2, 2.5])
>>> x
array([ 1. ,  2. ,  2.5])

>>> x.astype(int)
array([1, 2, 2])


numpy.chararray.copy

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.astype

Next topic

numpy.chararray.count

numpy.chararray.copy

chararray.copy(order='C')

Return a copy of the array.

Parameters:

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout of the copy. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible. (Note that this function and :func:numpy.copy are very similar, but have different default values for their order= arguments.)

See also

numpy.copy, numpy.copyto

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
       [0, 0, 0]])

>>> y
array([[1, 2, 3],
       [4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True


numpy.chararray.count

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.copy

Next topic

numpy.chararray.decode

numpy.chararray.count

chararray.count(sub, start=0, end=None) [source]

Returns an array with the number of non-overlapping occurrences of substring sub in the range [start, end].

See also

char.count


numpy.chararray.decode

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.count

Next topic

numpy.chararray.dump

numpy.chararray.decode

chararray.decode(encoding=None, errors=None) [source]

Calls str.decode element-wise.

See also

char.decode


numpy.chararray.dump

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.decode

Next topic

numpy.chararray.dumps

numpy.chararray.dump

chararray.dump(file)

Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.

Parameters:

file : str

A string naming the dump file.


numpy.chararray.dumps

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.dump

Next topic

numpy.chararray.encode

numpy.chararray.dumps

chararray.dumps()

Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an array.

Parameters: None


numpy.chararray.encode

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.dumps

Next topic

numpy.chararray.endswith

numpy.chararray.encode

chararray.encode(encoding=None, errors=None) [source]

Calls str.encode element-wise.

See also

char.encode


numpy.chararray.endswith

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.encode

Next topic

numpy.chararray.expandtabs

numpy.chararray.endswith

chararray.endswith(suffix, start=0, end=None) [source]

Returns a boolean array which is True where the string element in self ends with suffix, otherwise False.

See also

char.endswith


numpy.chararray.expandtabs

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.endswith

Next topic

numpy.chararray.fill

numpy.chararray.expandtabs

chararray.expandtabs(tabsize=8) [source]

Return a copy of each string element where all tab characters are replaced by one or more spaces.

See also

char.expandtabs


numpy.chararray.fill

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.expandtabs

Next topic

numpy.chararray.find

numpy.chararray.fill

chararray.fill(value)

Fill the array with a scalar value.

Parameters:

value : scalar

All elements of a will be assigned this value.

Examples

>>> a = np.array([1, 2])
>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([ 1.,  1.])


numpy.chararray.find

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.fill

Next topic

numpy.chararray.flatten

numpy.chararray.find

chararray.find(sub, start=0, end=None) [source]

For each element, return the lowest index in the string where substring sub is found.

See also

char.find


numpy.chararray.flatten

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.find

Next topic

numpy.chararray.getfield

numpy.chararray.flatten

chararray.flatten(order='C')

Return a copy of the array collapsed into one dimension.

Parameters:

order : {‘C’, ‘F’, ‘A’}, optional

Whether to flatten in C (row-major), Fortran (column-major) order, or preserve the C/Fortran ordering from a. The default is ‘C’.
Returns:

y : ndarray

A copy of the input array, flattened to one dimension.

See also

ravel
Return a flattened array.
flat
A 1-D flat iterator over the array.

Examples

>>> a = np.array([[1,2], [3,4]])
>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten('F')
array([1, 3, 2, 4])


numpy.chararray.getfield

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.flatten

Next topic

numpy.chararray.index

numpy.chararray.getfield

chararray.getfield(dtype, offset=0)

Returns a field of the given array as a certain type.

A field is a view of the array data with a given data-type. The values in the view are determined by the given type and the offset into the current array in bytes. The offset needs to be such that the view dtype fits in the array dtype; for example an array of dtype complex128 has 16-byte elements. If taking a view with a 32-bit integer (4 bytes), the offset needs to be between 0 and 12 bytes.

Parameters:

dtype : str or dtype

The data type of the view. The dtype size of the view can not be larger than that of the array itself.

offset : int

Number of bytes to skip before beginning the element view.

Examples

>>> x = np.diag([1.+1.j]*2)
>>> x[1, 1] = 2 + 4.j
>>> x
array([[ 1.+1.j,  0.+0.j],
       [ 0.+0.j,  2.+4.j]])
>>> x.getfield(np.float64)
array([[ 1.,  0.],
       [ 0.,  2.]])

By choosing an offset of 8 bytes we can select the complex part of the array for our view:

>>> x.getfield(np.float64, offset=8)
array([[ 1.,  0.],
   [ 0.,  4.]])


numpy.chararray.index

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.getfield

Next topic

numpy.chararray.isalnum

numpy.chararray.index

chararray.index(sub, start=0, end=None) [source]

Like find, but raises ValueError when the substring is not found.

See also

char.index


numpy.chararray.isalnum

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.index

Next topic

numpy.chararray.isalpha

numpy.chararray.isalnum

chararray.isalnum() [source]

Returns true for each element if all characters in the string are alphanumeric and there is at least one character, false otherwise.

See also

char.isalnum


numpy.chararray.isalpha

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.isalnum

Next topic

numpy.chararray.isdecimal

numpy.chararray.isalpha

chararray.isalpha() [source]

Returns true for each element if all characters in the string are alphabetic and there is at least one character, false otherwise.

See also

char.isalpha


numpy.chararray.isdecimal

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.isalpha

Next topic

numpy.chararray.isdigit

numpy.chararray.isdecimal

chararray.isdecimal() [source]

For each element in self, return True if there are only decimal characters in the element.

See also

char.isdecimal


numpy.chararray.isdigit

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.isdecimal

Next topic

numpy.chararray.islower

numpy.chararray.isdigit

chararray.isdigit() [source]

Returns true for each element if all characters in the string are digits and there is at least one character, false otherwise.

See also

char.isdigit


numpy.chararray.islower

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.isdigit

Next topic

numpy.chararray.isnumeric

numpy.chararray.islower

chararray.islower() [source]

Returns true for each element if all cased characters in the string are lowercase and there is at least one cased character, false otherwise.

See also

char.islower


numpy.chararray.isnumeric

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.islower

Next topic

numpy.chararray.isspace

numpy.chararray.isnumeric

chararray.isnumeric() [source]

For each element in self, return True if there are only numeric characters in the element.

See also

char.isnumeric


numpy.chararray.isspace

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.isnumeric

Next topic

numpy.chararray.istitle

numpy.chararray.isspace

chararray.isspace() [source]

Returns true for each element if there are only whitespace characters in the string and there is at least one character, false otherwise.

See also

char.isspace


numpy.chararray.istitle

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.isspace

Next topic

numpy.chararray.isupper

numpy.chararray.istitle

chararray.istitle() [source]

Returns true for each element if the element is a titlecased string and there is at least one character, false otherwise.

See also

char.istitle


numpy.chararray.isupper

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.istitle

Next topic

numpy.chararray.item

numpy.chararray.isupper

chararray.isupper() [source]

Returns true for each element if all cased characters in the string are uppercase and there is at least one character, false otherwise.

See also

char.isupper


numpy.chararray.item

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.isupper

Next topic

numpy.chararray.join

numpy.chararray.item

chararray.item(*args)

Copy an element of an array to a standard Python scalar and return it.

Parameters:

*args : Arguments (variable number and type)

  • none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.
  • int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.
  • tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.
Returns:

z : Standard Python scalar object

A copy of the specified element of the array as a suitable Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.item(3)
2
>>> x.item(7)
5
>>> x.item((0, 1))
1
>>> x.item((2, 2))
3


numpy.chararray.join

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.item

Next topic

numpy.chararray.ljust

numpy.chararray.join

chararray.join(seq) [source]

Return a string which is the concatenation of the strings in the sequence seq.

See also

char.join


numpy.chararray.ljust

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.join

Next topic

numpy.chararray.lower

numpy.chararray.ljust

chararray.ljust(width, fillchar=' ') [source]

Return an array with the elements of self left-justified in a string of length width.

See also

char.ljust


numpy.chararray.lower

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.ljust

Next topic

numpy.chararray.lstrip

numpy.chararray.lower

chararray.lower() [source]

Return an array with the elements of self converted to lowercase.

See also

char.lower


numpy.chararray.lstrip

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.lower

Next topic

numpy.chararray.nonzero

numpy.chararray.lstrip

chararray.lstrip(chars=None) [source]

For each element in self, return a copy with the leading characters removed.

See also

char.lstrip


numpy.chararray.nonzero

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.lstrip

Next topic

numpy.chararray.put

numpy.chararray.nonzero

chararray.nonzero()

Return the indices of the elements that are non-zero.

Refer to numpy.nonzero for full documentation.

See also

numpy.nonzero
equivalent function


numpy.chararray.put

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.nonzero

Next topic

numpy.chararray.ravel

numpy.chararray.put

chararray.put(indices, values, mode='raise')

Set a.flat[n] = values[n] for all n in indices.

Refer to numpy.put for full documentation.

See also

numpy.put
equivalent function


numpy.chararray.ravel

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.put

Next topic

numpy.chararray.repeat

numpy.chararray.ravel

chararray.ravel([order])

Return a flattened array.

Refer to numpy.ravel for full documentation.

See also

numpy.ravel
equivalent function
ndarray.flat
a flat iterator on the array.


numpy.chararray.repeat

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.ravel

Next topic

numpy.chararray.replace

numpy.chararray.repeat

chararray.repeat(repeats, axis=None)

Repeat elements of an array.

Refer to numpy.repeat for full documentation.

See also

numpy.repeat
equivalent function


numpy.chararray.replace

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.repeat

Next topic

numpy.chararray.reshape

numpy.chararray.replace

chararray.replace(old, new, count=None) [source]

For each element in self, return a copy of the string with all occurrences of substring old replaced by new.

See also

char.replace


numpy.chararray.reshape

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.replace

Next topic

numpy.chararray.resize

numpy.chararray.reshape

chararray.reshape(shape, order='C')

Returns an array containing the same data with a new shape.

Refer to numpy.reshape for full documentation.

See also

numpy.reshape
equivalent function


numpy.chararray.resize

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.reshape

Next topic

numpy.chararray.rfind

numpy.chararray.resize

chararray.resize(new_shape, refcheck=True)

Change shape and size of array in-place.

Parameters:

new_shape : tuple of ints, or n ints

Shape of resized array.

refcheck : bool, optional

If False, reference count will not be checked. Default is True.
Returns:

None
Raises:

ValueError

If a does not own its own data or references or views to it exist, and the data memory must be changed.

SystemError

If the order keyword argument is specified. This behaviour is a bug in NumPy.

See also

resize
Return a new array with the specified shape.

Notes

This reallocates space for the data area if necessary.

Only contiguous arrays (data elements consecutive in memory) can be resized.

The purpose of the reference count check is to make sure you do not use this array as a buffer for another Python object and then reallocate the memory. However, reference counts can increase in other ways so if you are sure that you have not shared the memory for this array with another Python object, then you may safely set refcheck to False.

Examples

Shrinking an array: array is flattened (in the order that the data are stored in memory), resized, and reshaped:

>>> a = np.array([[0, 1], [2, 3]], order='C')
>>> a.resize((2, 1))
>>> a
array([[0],
       [1]])

>>> a = np.array([[0, 1], [2, 3]], order='F')
>>> a.resize((2, 1))
>>> a
array([[0],
       [2]])

Enlarging an array: as above, but missing entries are filled with zeros:

>>> b = np.array([[0, 1], [2, 3]])
>>> b.resize(2, 3) # new_shape parameter doesn't have to be a tuple
>>> b
array([[0, 1, 2],
       [3, 0, 0]])

Referencing an array prevents resizing...

>>> c = a
>>> a.resize((1, 1))
Traceback (most recent call last):
...
ValueError: cannot resize an array that has been referenced ...

Unless refcheck is False:

>>> a.resize((1, 1), refcheck=False)
>>> a
array([[0]])
>>> c
array([[0]])


numpy.chararray.rfind

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.resize

Next topic

numpy.chararray.rindex

numpy.chararray.rfind

chararray.rfind(sub, start=0, end=None) [source]

For each element in self, return the highest index in the string where substring sub is found, such that sub is contained within [start, end].

See also

char.rfind


numpy.chararray.rindex

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.rfind

Next topic

numpy.chararray.rjust

numpy.chararray.rindex

chararray.rindex(sub, start=0, end=None) [source]

Like rfind, but raises ValueError when the substring sub is not found.

See also

char.rindex


numpy.chararray.rjust

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.rindex

Next topic

numpy.chararray.rsplit

numpy.chararray.rjust

chararray.rjust(width, fillchar=' ') [source]

Return an array with the elements of self right-justified in a string of length width.

See also

char.rjust


numpy.chararray.rsplit

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.rjust

Next topic

numpy.chararray.rstrip

numpy.chararray.rsplit

chararray.rsplit(sep=None, maxsplit=None) [source]

For each element in self, return a list of the words in the string, using sep as the delimiter string.

See also

char.rsplit


numpy.chararray.rstrip

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.rsplit

Next topic

numpy.chararray.searchsorted

numpy.chararray.rstrip

chararray.rstrip(chars=None) [source]

For each element in self, return a copy with the trailing characters removed.

See also

char.rstrip


numpy.chararray.searchsorted

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.rstrip

Next topic

numpy.chararray.setfield

numpy.chararray.searchsorted

chararray.searchsorted(v, side='left', sorter=None)

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See also

numpy.searchsorted
equivalent function


numpy.chararray.setfield

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.searchsorted

Next topic

numpy.chararray.setflags

numpy.chararray.setfield

chararray.setfield(val, dtype, offset=0)

Put a value into a specified place in a field defined by a data-type.

Place val into a‘s field defined by dtype and beginning offset bytes into the field.

Parameters:

val : object

Value to be placed in field.

dtype : dtype object

Data-type of the field in which to place val.

offset : int, optional

The number of bytes into the field at which to place val.
Returns:

None

See also

getfield

Examples

>>> x = np.eye(3)
>>> x.getfield(np.float64)
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
>>> x.setfield(3, np.int32)
>>> x.getfield(np.int32)
array([[3, 3, 3],
       [3, 3, 3],
       [3, 3, 3]])
>>> x
array([[  1.00000000e+000,   1.48219694e-323,   1.48219694e-323],
       [  1.48219694e-323,   1.00000000e+000,   1.48219694e-323],
       [  1.48219694e-323,   1.48219694e-323,   1.00000000e+000]])
>>> x.setfield(np.eye(3), np.int32)
>>> x
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])


numpy.chararray.setflags

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.setfield

Next topic

numpy.chararray.sort

numpy.chararray.setflags

chararray.setflags(write=None, align=None, uic=None)

Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively.

These Boolean-valued flags affect how numpy interprets the memory area used by a (see Notes below). The ALIGNED flag can only be set to True if the data is actually aligned according to the type. The UPDATEIFCOPY flag can never be set to True. The flag WRITEABLE can only be set to True if the array owns its own memory, or the ultimate owner of the memory exposes a writeable buffer interface, or is a string. (The exception for string is made so that unpickling can be done without copying memory.)

Parameters:

write : bool, optional

Describes whether or not a can be written to.

align : bool, optional

Describes whether or not a is aligned properly for its type.

uic : bool, optional

Describes whether or not a is a copy of another “base” array.

Notes

Array flags provide information about how the memory area used for the array is to be interpreted. There are 6 Boolean flags in use, only three of which can be changed by the user: UPDATEIFCOPY, WRITEABLE, and ALIGNED.

WRITEABLE (W) the data area can be written to;

ALIGNED (A) the data and strides are aligned appropriately for the hardware (as determined by the compiler);

UPDATEIFCOPY (U) this array is a copy of some other array (referenced by .base). When this array is deallocated, the base array will be updated with the contents of this array.

All flags can be accessed using their first (upper case) letter as well as the full name.

Examples

>>> y
array([[3, 1, 7],
       [2, 0, 0],
       [8, 5, 9]])
>>> y.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : True
  WRITEABLE : True
  ALIGNED : True
  UPDATEIFCOPY : False
>>> y.setflags(write=0, align=0)
>>> y.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : True
  WRITEABLE : False
  ALIGNED : False
  UPDATEIFCOPY : False
>>> y.setflags(uic=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: cannot set UPDATEIFCOPY flag to True


numpy.chararray.sort

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.setflags

Next topic

numpy.chararray.split

numpy.chararray.sort

chararray.sort(axis=-1, kind='quicksort', order=None)

Sort an array, in-place.

Parameters:

axis : int, optional

Axis along which to sort. Default is -1, which means sort along the last axis.

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm. Default is ‘quicksort’.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.

See also

numpy.sort
Return a sorted copy of an array.
argsort
Indirect sort.
lexsort
Indirect stable sort on multiple keys.
searchsorted
Find elements in sorted array.
partition
Partial sort.

Notes

See sort for notes on the different sorting algorithms.

Examples

>>> a = np.array([[1,4], [3,1]])
>>> a.sort(axis=1)
>>> a
array([[1, 4],
       [1, 3]])
>>> a.sort(axis=0)
>>> a
array([[1, 3],
       [1, 4]])

Use the order keyword to specify a field to use when sorting a structured array:

>>> a = np.array([('a', 2), ('c', 1)], dtype=[('x', 'S1'), ('y', int)])
>>> a.sort(order='y')
>>> a
array([('c', 1), ('a', 2)],
      dtype=[('x', '|S1'), ('y', '<i4')])


numpy.chararray.split

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.sort

Next topic

numpy.chararray.splitlines

numpy.chararray.split

chararray.split(sep=None, maxsplit=None) [source]

For each element in self, return a list of the words in the string, using sep as the delimiter string.

See also

char.split


numpy.chararray.splitlines

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.split

Next topic

numpy.chararray.squeeze

numpy.chararray.splitlines

chararray.splitlines(keepends=None) [source]

For each element in self, return a list of the lines in the element, breaking at line boundaries.

See also

char.splitlines


numpy.chararray.squeeze

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.splitlines

Next topic

numpy.chararray.startswith

numpy.chararray.squeeze

chararray.squeeze(axis=None)

Remove single-dimensional entries from the shape of a.

Refer to numpy.squeeze for full documentation.

See also

numpy.squeeze
equivalent function


numpy.chararray.startswith

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.squeeze

Next topic

numpy.chararray.strip

numpy.chararray.startswith

chararray.startswith(prefix, start=0, end=None) [source]

Returns a boolean array which is True where the string element in self starts with prefix, otherwise False.

See also

char.startswith


numpy.chararray.strip

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.startswith

Next topic

numpy.chararray.swapaxes

numpy.chararray.strip

chararray.strip(chars=None) [source]

For each element in self, return a copy with the leading and trailing characters removed.

See also

char.strip


numpy.chararray.swapaxes

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.strip

Next topic

numpy.chararray.swapcase

numpy.chararray.swapaxes

chararray.swapaxes(axis1, axis2)

Return a view of the array with axis1 and axis2 interchanged.

Refer to numpy.swapaxes for full documentation.

See also

numpy.swapaxes
equivalent function


numpy.chararray.swapcase

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.swapaxes

Next topic

numpy.chararray.take

numpy.chararray.swapcase

chararray.swapcase() [source]

For each element in self, return a copy of the string with uppercase characters converted to lowercase and vice versa.

See also

char.swapcase


numpy.chararray.take

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.swapcase

Next topic

numpy.chararray.title

numpy.chararray.take

chararray.take(indices, axis=None, out=None, mode='raise')

Return an array formed from the elements of a at the given indices.

Refer to numpy.take for full documentation.

See also

numpy.take
equivalent function


numpy.chararray.title

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.take

Next topic

numpy.chararray.tofile

numpy.chararray.title

chararray.title() [source]

For each element in self, return a titlecased version of the string: words start with uppercase characters, all remaining cased characters are lowercase.

See also

char.title


numpy.chararray.tofile

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.title

Next topic

numpy.chararray.tolist

numpy.chararray.tofile

chararray.tofile(fid, sep="", format="%s")

Write array to a file as text or binary (default).

Data is always written in ‘C’ order, independent of the order of a. The data produced by this method can be recovered using the function fromfile().

Parameters:

fid : file or str

An open file object, or a string containing a filename.

sep : str

Separator between array items for text output. If “” (empty), a binary file is written, equivalent to file.write(a.tobytes()).

format : str

Format string for text file output. Each entry in the array is formatted to text by first converting it to the closest Python type, and then using “format” % item.

Notes

This is a convenience function for quick storage of array data. Information on endianness and precision is lost, so this method is not a good choice for files intended to archive data or transport data between machines with different endianness. Some of these problems can be overcome by outputting the data as text files, at the expense of speed and file size.


numpy.chararray.tolist

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.tofile

Next topic

numpy.chararray.tostring

numpy.chararray.tolist

chararray.tolist()

Return the array as a (possibly nested) list.

Return a copy of the array data as a (nested) Python list. Data items are converted to the nearest compatible Python type.

Parameters:

none
Returns:

y : list

The possibly nested list of array elements.

Notes

The array may be recreated, a = np.array(a.tolist()).

Examples

>>> a = np.array([1, 2])
>>> a.tolist()
[1, 2]
>>> a = np.array([[1, 2], [3, 4]])
>>> list(a)
[array([1, 2]), array([3, 4])]
>>> a.tolist()
[[1, 2], [3, 4]]


numpy.chararray.tostring

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.tolist

Next topic

numpy.chararray.translate

numpy.chararray.tostring

chararray.tostring(order='C')

Construct Python bytes containing the raw data bytes in the array.

Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.

This function is a compatibility alias for tobytes. Despite its name it returns bytes not strings.

Parameters:

order : {‘C’, ‘F’, None}, optional

Order of the data for multidimensional arrays: C, Fortran, or the same as for the original array.
Returns:

s : bytes

Python bytes exhibiting a copy of a‘s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]])
>>> x.tobytes()
b'\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x03\x00\x00\x00'


numpy.chararray.translate

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.tostring

Next topic

numpy.chararray.transpose

numpy.chararray.translate

chararray.translate(table, deletechars=None) [source]

For each element in self, return a copy of the string where all characters occurring in the optional argument deletechars are removed, and the remaining characters have been mapped through the given translation table.

See also

char.translate


numpy.chararray.transpose

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.translate

Next topic

numpy.chararray.upper

numpy.chararray.transpose

chararray.transpose(*axes)

Returns a view of the array with axes transposed.

For a 1-D array, this has no effect. (To change between column and row vectors, first cast the 1-D array into a matrix object.) For a 2-D array, this is the usual matrix transpose. For an n-D array, if axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided and a.shape = (i[0], i[1], ... i[n-2], i[n-1]), then a.transpose().shape = (i[n-1], i[n-2], ... i[1], i[0]).

Parameters:

axes : None, tuple of ints, or n ints

  • None or no argument: reverses the order of the axes.
  • tuple of ints: i in the j-th place in the tuple means a‘s i-th axis becomes a.transpose()‘s j-th axis.
  • n ints: same as an n-tuple of the same ints (this form is intended simply as a “convenience” alternative to the tuple form)
Returns:

out : ndarray

View of a, with axes suitably permuted.

See also

ndarray.T
Array property returning the array transposed.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> a
array([[1, 2],
       [3, 4]])
>>> a.transpose()
array([[1, 3],
       [2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
       [2, 4]])
>>> a.transpose(1, 0)
array([[1, 3],
       [2, 4]])


numpy.chararray.upper

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.transpose

Next topic

numpy.chararray.view

numpy.chararray.upper

chararray.upper() [source]

Return an array with the elements of self converted to uppercase.

See also

char.upper


numpy.chararray.view

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.upper

Next topic

numpy.chararray.zfill

numpy.chararray.view

chararray.view(dtype=None, type=None)

New view of array with the same data.

Parameters:

dtype : data-type or ndarray sub-class, optional

Data-type descriptor of the returned view, e.g., float32 or int16. The default, None, results in the view having the same data-type as a. This argument can also be specified as an ndarray sub-class, which then specifies the type of the returned object (this is equivalent to setting the type parameter).

type : Python type, optional

Type of the returned view, e.g., ndarray or matrix. Again, the default None results in type preservation.

Notes

a.view() is used two different ways:

a.view(some_dtype) or a.view(dtype=some_dtype) constructs a view of the array’s memory with a different data-type. This can cause a reinterpretation of the bytes of memory.

a.view(ndarray_subclass) or a.view(type=ndarray_subclass) just returns an instance of ndarray_subclass that looks at the same array (same shape, dtype, etc.) This does not cause a reinterpretation of the memory.

For a.view(some_dtype), if some_dtype has a different number of bytes per entry than the previous dtype (for example, converting a regular array to a structured array), then the behavior of the view cannot be predicted just from the superficial appearance of a (shown by print(a)). It also depends on exactly how a is stored in memory. Therefore if a is C-ordered versus fortran-ordered, versus defined as a slice or transpose, etc., the view may give different results.

Examples

>>> x = np.array([(1, 2)], dtype=[('a', np.int8), ('b', np.int8)])

Viewing array data using a different type and dtype:

>>> y = x.view(dtype=np.int16, type=np.matrix)
>>> y
matrix([[513]], dtype=int16)
>>> print type(y)
<class 'numpy.matrixlib.defmatrix.matrix'>

Creating a view on a structured array so it can be used in calculations

>>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)])
>>> xv = x.view(dtype=np.int8).reshape(-1,2)
>>> xv
array([[1, 2],
       [3, 4]], dtype=int8)
>>> xv.mean(0)
array([ 2.,  3.])

Making changes to the view changes the underlying array

>>> xv[0,1] = 20
>>> print x
[(1, 20) (3, 4)]

Using a view to convert an array to a record array:

>>> z = x.view(np.recarray)
>>> z.a
array([1], dtype=int8)

Views share data:

>>> x[0] = (9, 10)
>>> z[0]
(9, 10)

Views that change the dtype size (bytes per entry) should normally be avoided on arrays defined by slices, transposes, fortran-ordering, etc.:

>>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16)
>>> y = x[:, 0:2]
>>> y
array([[1, 2],
       [4, 5]], dtype=int16)
>>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: new type not compatible with array.
>>> z = y.copy()
>>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
array([[(1, 2)],
       [(4, 5)]], dtype=[('width', '<i2'), ('length', '<i2')])


numpy.chararray.zfill

  • Array objects
  • Standard array subclasses
  • numpy.chararray
  • index
  • next
  • previous

Previous topic

numpy.chararray.view

Next topic

numpy.core.defchararray.array

numpy.chararray.zfill

chararray.zfill(width) [source]

Return the numeric string left-filled with zeros in a string of length width.

See also

char.zfill


numpy.core.defchararray.array

  • Array creation routines
  • next
  • previous

Previous topic

numpy.core.records.fromfile

Next topic

numpy.core.defchararray.asarray

numpy.core.defchararray.array

numpy.core.defchararray.array(obj, itemsize=None, copy=True, unicode=None, order=None) [source]

Create a chararray.

Note

This class is provided for numarray backward-compatibility. New code (not concerned with numarray compatibility) should use arrays of type string_ or unicode_ and use the free functions in numpy.char for fast vectorized string operations instead.

Versus a regular Numpy array of type str or unicode, this class adds the following functionality:

  1. values automatically have whitespace removed from the end when indexed
  2. comparison operators automatically remove whitespace from the end when comparing values
  3. vectorized string operations are provided as methods (e.g. str.endswith) and infix operators (e.g. +, *, %)
Parameters:

obj : array of str or unicode-like

itemsize : int, optional

itemsize is the number of characters per scalar in the resulting array. If itemsize is None, and obj is an object array or a Python list, the itemsize will be automatically determined. If itemsize is provided and obj is of type str or unicode, then the obj string will be chunked into itemsize pieces.

copy : bool, optional

If true (default), then the object is copied. Otherwise, a copy will only be made if __array__ returns a copy, if obj is a nested sequence, or if a copy is needed to satisfy any of the other requirements (itemsize, unicode, order, etc.).

unicode : bool, optional

When true, the resulting chararray can contain Unicode characters, when false only 8-bit characters. If unicode is None and obj is one of the following:

  • a chararray,
  • an ndarray of type str or unicode
  • a Python str or unicode object,

then the unicode setting of the output array will be automatically determined.

order : {‘C’, ‘F’, ‘A’}, optional

Specify the order of the array. If order is ‘C’ (default), then the array will be in C-contiguous order (last-index varies the fastest). If order is ‘F’, then the returned array will be in Fortran-contiguous order (first-index varies the fastest). If order is ‘A’, then the returned array may be in any order (either C-, Fortran-contiguous, or even discontiguous).


numpy.recarray

  • Array objects
  • Standard array subclasses
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.array

Next topic

numpy.recarray.T

numpy.recarray

class numpy.recarray [source]

Construct an ndarray that allows field access using attributes.

Arrays may have a data-types containing fields, analogous to columns in a spread sheet. An example is [(x, int), (y, float)], where each entry in the array is a pair of (int, float). Normally, these attributes are accessed using dictionary lookups such as arr['x'] and arr['y']. Record arrays allow the fields to be accessed as members of the array, using arr.x and arr.y.

Parameters:

shape : tuple

Shape of output array.

dtype : data-type, optional

The desired data-type. By default, the data-type is determined from formats, names, titles, aligned and byteorder.

formats : list of data-types, optional

A list containing the data-types for the different columns, e.g. ['i4', 'f8', 'i4']. formats does not support the new convention of using types directly, i.e. (int, float, int). Note that formats must be a list, not a tuple. Given that formats is somewhat limited, we recommend specifying dtype instead.

names : tuple of str, optional

The name of each column, e.g. ('x', 'y', 'z').

buf : buffer, optional

By default, a new array is created of the given shape and data-type. If buf is specified and is an object exposing the buffer interface, the array will use the memory from the existing buffer. In this case, the offset and strides keywords are available.
Returns:

rec : recarray

Empty array of the given shape and type.
Other Parameters:

titles : tuple of str, optional

Aliases for column names. For example, if names were ('x', 'y', 'z') and titles is ('x_coordinate', 'y_coordinate', 'z_coordinate'), then arr['x'] is equivalent to both arr.x and arr.x_coordinate.

byteorder : {‘<’, ‘>’, ‘=’}, optional

Byte-order for all fields.

aligned : bool, optional

Align the fields in memory as the C-compiler would.

strides : tuple of ints, optional

Buffer (buf) is interpreted according to these strides (strides define how many bytes each array element, row, column, etc. occupy in memory).

offset : int, optional

Start reading buffer (buf) from this offset onwards.

order : {‘C’, ‘F’}, optional

Row-major or column-major order.

See also

rec.fromrecords
Construct a record array from data.
record
fundamental data-type for recarray.
format_parser
determine a data-type from formats, names, titles.

Notes

This constructor can be compared to empty: it creates a new record array but does not fill it with data. To create a record array from data, use one of the following methods:

  1. Create a standard ndarray and convert it to a record array, using arr.view(np.recarray)
  2. Use the buf keyword.
  3. Use np.rec.fromrecords.

Examples

Create an array with two fields, x and y:

>>> x = np.array([(1.0, 2), (3.0, 4)], dtype=[('x', float), ('y', int)])
>>> x
array([(1.0, 2), (3.0, 4)],
      dtype=[('x', '<f8'), ('y', '<i4')])

>>> x['x']
array([ 1.,  3.])

View the array as a record array:

>>> x = x.view(np.recarray)

>>> x.x
array([ 1.,  3.])

>>> x.y
array([2, 4])

Create a new, empty record array:

>>> np.recarray((2,),
... dtype=[('x', int), ('y', float), ('z', int)])
rec.array([(-1073741821, 1.2249118382103472e-301, 24547520),
       (3471280, 1.2134086255804012e-316, 0)],
      dtype=[('x', '<i4'), ('y', '<f8'), ('z', '<i4')])

Attributes

T | Same as self.transpose(), except that self is returned if self.ndim < 2.
base | Base object if memory is from some other object.
ctypes | An object to simplify the interaction of the array with the ctypes module.
data | Python buffer object pointing to the start of the array’s data.
dtype | Data-type of the array’s elements.
flags | Information about the memory layout of the array.
flat | A 1-D iterator over the array.
imag | The imaginary part of the array.
itemsize | Length of one array element in bytes.
nbytes | Total bytes consumed by the elements of the array.
ndim | Number of array dimensions.
real | The real part of the array.
shape | Tuple of array dimensions.
size | Number of elements in the array.
strides | Tuple of bytes to step in each dimension when traversing an array.

Methods

all([axis, out]) | Returns True if all elements evaluate to True.
any([axis, out]) | Returns True if any of the elements of a evaluate to True.
argmax([axis, out]) | Return indices of the maximum values along the given axis.
argmin([axis, out]) | Return indices of the minimum values along the given axis of a.
argpartition(kth[, axis, kind, order]) | Returns the indices that would partition this array.
argsort([axis, kind, order]) | Returns the indices that would sort this array.
astype(dtype[, order, casting, subok, copy]) | Copy of the array, cast to a specified type.
byteswap(inplace) | Swap the bytes of the array elements
choose(choices[, out, mode]) | Use an index array to construct a new array from a set of choices.
clip(a_min, a_max[, out]) | Return an array whose values are limited to [a_min, a_max].
compress(condition[, axis, out]) | Return selected slices of this array along given axis.
conj() | Complex-conjugate all elements.
conjugate() | Return the complex conjugate, element-wise.
copy([order]) | Return a copy of the array.
cumprod([axis, dtype, out]) | Return the cumulative product of the elements along the given axis.
cumsum([axis, dtype, out]) | Return the cumulative sum of the elements along the given axis.
diagonal([offset, axis1, axis2]) | Return specified diagonals.
dot(b[, out]) | Dot product of two arrays.
dump(file) | Dump a pickle of the array to the specified file.
dumps() | Returns the pickle of the array as a string.
field(attr[, val])
fill(value) | Fill the array with a scalar value.
flatten([order]) | Return a copy of the array collapsed into one dimension.
getfield(dtype[, offset]) | Returns a field of the given array as a certain type.
item(*args) | Copy an element of an array to a standard Python scalar and return it.
itemset(*args) | Insert scalar into an array (scalar is cast to array’s dtype, if possible)
max([axis, out]) | Return the maximum along a given axis.
mean([axis, dtype, out]) | Returns the average of the array elements along given axis.
min([axis, out]) | Return the minimum along a given axis.
newbyteorder([new_order]) | Return the array with the same data viewed with a different byte order.
nonzero() | Return the indices of the elements that are non-zero.
partition(kth[, axis, kind, order]) | Rearranges the elements in the array in such a way that value of the element in kth position is in the position it would be in a sorted array.
prod([axis, dtype, out]) | Return the product of the array elements over the given axis
ptp([axis, out]) | Peak to peak (maximum - minimum) value along a given axis.
put(indices, values[, mode]) | Set a.flat[n] = values[n] for all n in indices.
ravel([order]) | Return a flattened array.
repeat(repeats[, axis]) | Repeat elements of an array.
reshape(shape[, order]) | Returns an array containing the same data with a new shape.
resize(new_shape[, refcheck]) | Change shape and size of array in-place.
round([decimals, out]) | Return a with each element rounded to the given number of decimals.
searchsorted(v[, side, sorter]) | Find indices where elements of v should be inserted in a to maintain order.
setfield(val, dtype[, offset]) | Put a value into a specified place in a field defined by a data-type.
setflags([write, align, uic]) | Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively.
sort([axis, kind, order]) | Sort an array, in-place.
squeeze([axis]) | Remove single-dimensional entries from the shape of a.
std([axis, dtype, out, ddof]) | Returns the standard deviation of the array elements along given axis.
sum([axis, dtype, out]) | Return the sum of the array elements over the given axis.
swapaxes(axis1, axis2) | Return a view of the array with axis1 and axis2 interchanged.
take(indices[, axis, out, mode]) | Return an array formed from the elements of a at the given indices.
tobytes([order]) | Construct Python bytes containing the raw data bytes in the array.
tofile(fid[, sep, format]) | Write array to a file as text or binary (default).
tolist() | Return the array as a (possibly nested) list.
tostring([order]) | Construct Python bytes containing the raw data bytes in the array.
trace([offset, axis1, axis2, dtype, out]) | Return the sum along diagonals of the array.
transpose(*axes) | Returns a view of the array with axes transposed.
var([axis, dtype, out, ddof]) | Returns the variance of the array elements, along given axis.
view([dtype, type])


numpy.recarray.T

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray

Next topic

numpy.recarray.base

numpy.recarray.T

recarray.T

Same as self.transpose(), except that self is returned if self.ndim < 2.

Examples

>>> x = np.array([[1.,2.],[3.,4.]])
>>> x
array([[ 1.,  2.],
       [ 3.,  4.]])
>>> x.T
array([[ 1.,  3.],
       [ 2.,  4.]])
>>> x = np.array([1.,2.,3.,4.])
>>> x
array([ 1.,  2.,  3.,  4.])
>>> x.T
array([ 1.,  2.,  3.,  4.])


numpy.recarray.base

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.T

Next topic

numpy.recarray.ctypes

numpy.recarray.base

recarray.base

Base object if memory is from some other object.

Examples

The base of an array that owns its memory is None:

>>> x = np.array([1,2,3,4])
>>> x.base is None
True

Slicing creates a view, whose memory is shared with x:

>>> y = x[2:]
>>> y.base is x
True


numpy.recarray.ctypes

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.base

Next topic

numpy.recarray.data

numpy.recarray.ctypes

recarray.ctypes

An object to simplify the interaction of the array with the ctypes module.

This attribute creates an object that makes it easier to use arrays when calling shared libraries with the ctypes module. The returned object has, among others, data, shape, and strides attributes (see Notes below) which themselves return ctypes objects that can be used as arguments to a shared library.

Parameters:

None
Returns:

c : Python object

Possessing attributes data, shape, strides, etc.

See also

numpy.ctypeslib

Notes

Below are the public attributes of this object which were documented in “Guide to NumPy” (we have omitted undocumented public attributes, as well as documented private attributes):

  • data: A pointer to the memory area of the array as a Python integer. This memory area may contain data that is not aligned, or not in correct byte-order. The memory area may not even be writeable. The array flags and data-type of this array should be respected when passing this attribute to arbitrary C-code to avoid trouble that can include Python crashing. User Beware! The value of this attribute is exactly the same as self._array_interface_[‘data’][0].
  • shape (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the C-integer corresponding to dtype(‘p’) on this platform. This base-type could be c_int, c_long, or c_longlong depending on the platform. The c_intp type is defined accordingly in numpy.ctypeslib. The ctypes array contains the shape of the underlying array.
  • strides (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the same as for the shape attribute. This ctypes array contains the strides information from the underlying array. This strides information is important for showing how many bytes must be jumped to get to the next element in the array.
  • data_as(obj): Return the data pointer cast to a particular c-types object. For example, calling self._as_parameter_ is equivalent to self.data_as(ctypes.c_void_p). Perhaps you want to use the data as a pointer to a ctypes array of floating-point data: self.data_as(ctypes.POINTER(ctypes.c_double)).
  • shape_as(obj): Return the shape tuple as an array of some other c-types type. For example: self.shape_as(ctypes.c_short).
  • strides_as(obj): Return the strides tuple as an array of some other c-types type. For example: self.strides_as(ctypes.c_longlong).

Be careful using the ctypes attribute - especially on temporary arrays or arrays constructed on the fly. For example, calling (a+b).ctypes.data_as(ctypes.c_void_p) returns a pointer to memory that is invalid because the array created as (a+b) is deallocated before the next Python statement. You can avoid this problem using either c=a+b or ct=(a+b).ctypes. In the latter case, ct will hold a reference to the array until ct is deleted or re-assigned.

If the ctypes module is not available, then the ctypes attribute of array objects still returns something useful, but ctypes objects are not returned and errors may be raised instead. In particular, the object will still have the as parameter attribute which will return an integer equal to the data attribute.

Examples

>>> import ctypes
>>> x
array([[0, 1],
       [2, 3]])
>>> x.ctypes.data
30439712
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long))
<ctypes.LP_c_long object at 0x01F01300>
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long)).contents
c_long(0)
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_longlong)).contents
c_longlong(4294967296L)
>>> x.ctypes.shape
<numpy.core._internal.c_long_Array_2 object at 0x01FFD580>
>>> x.ctypes.shape_as(ctypes.c_long)
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides_as(ctypes.c_longlong)
<numpy.core._internal.c_longlong_Array_2 object at 0x01F01300>


numpy.recarray.data

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.ctypes

Next topic

numpy.recarray.dtype

numpy.recarray.data

recarray.data

Python buffer object pointing to the start of the array’s data.


numpy.recarray.dtype

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.data

Next topic

numpy.recarray.flags

numpy.recarray.dtype

recarray.dtype

Data-type of the array’s elements.

Parameters: None
Returns: d : numpy dtype object

See also

numpy.dtype

Examples

>>> x
array([[0, 1],
       [2, 3]])
>>> x.dtype
dtype('int32')
>>> type(x.dtype)
<type 'numpy.dtype'>


numpy.recarray.flags

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.dtype

Next topic

numpy.recarray.flat

numpy.recarray.flags

recarray.flags

Information about the memory layout of the array.

Notes

The flags object can be accessed dictionary-like (as in a.flags['WRITEABLE']), or by using lowercased attribute names (as in a.flags.writeable). Short flag names are only supported in dictionary access.

Only the UPDATEIFCOPY, WRITEABLE, and ALIGNED flags can be changed by the user, via direct assignment to the attribute or dictionary entry, or by calling ndarray.setflags.

The array flags cannot be set arbitrarily:

  • UPDATEIFCOPY can only be set False.
  • ALIGNED can only be set True if the data is truly aligned.
  • WRITEABLE can only be set True if the array owns its own memory or the ultimate owner of the memory exposes a writeable buffer interface or is a string.

Arrays can be both C-style and Fortran-style contiguous simultaneously. This is clear for 1-dimensional arrays, but can also be true for higher dimensional arrays.

Even for contiguous arrays a stride for a given dimension arr.strides[dim] may be arbitrary if arr.shape[dim] == 1 or the array has no elements. It does not generally hold that self.strides[-1] == self.itemsize for C-style contiguous arrays or self.strides[0] == self.itemsize for Fortran-style contiguous arrays is true.

Attributes

C_CONTIGUOUS (C) | The data is in a single, C-style contiguous segment.
F_CONTIGUOUS (F) | The data is in a single, Fortran-style contiguous segment.
OWNDATA (O) | The array owns the memory it uses or borrows it from another object.
WRITEABLE (W) | The data area can be written to. Setting this to False locks the data, making it read-only. A view (slice, etc.) inherits WRITEABLE from its base array at creation time, but a view of a writeable array may be subsequently locked while the base array remains writeable. (The opposite is not true, in that a view of a locked array may not be made writeable. However, currently, locking a base object does not lock any views that already reference it, so under that circumstance it is possible to alter the contents of a locked array via a previously created writeable view onto it.) Attempting to change a non-writeable array raises a RuntimeError exception.
ALIGNED (A) | The data and all elements are aligned appropriately for the hardware.
UPDATEIFCOPY (U) | This array is a copy of some other array. When this array is deallocated, the base array will be updated with the contents of this array.
FNC | F_CONTIGUOUS and not C_CONTIGUOUS.
FORC | F_CONTIGUOUS or C_CONTIGUOUS (one-segment test).
BEHAVED (B) | ALIGNED and WRITEABLE.
CARRAY (CA) | BEHAVED and C_CONTIGUOUS.
FARRAY (FA) | BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS.


numpy.recarray.flat

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.flags

Next topic

numpy.recarray.imag

numpy.recarray.flat

recarray.flat

A 1-D iterator over the array.

This is a numpy.flatiter instance, which acts similarly to, but is not a subclass of, Python’s built-in iterator object.

See also

flatten
Return a copy of the array collapsed into one dimension.

flatiter

Examples

>>> x = np.arange(1, 7).reshape(2, 3)
>>> x
array([[1, 2, 3],
       [4, 5, 6]])
>>> x.flat[3]
4
>>> x.T
array([[1, 4],
       [2, 5],
       [3, 6]])
>>> x.T.flat[3]
5
>>> type(x.flat)
<type 'numpy.flatiter'>

An assignment example:

>>> x.flat = 3; x
array([[3, 3, 3],
       [3, 3, 3]])
>>> x.flat[[1,4]] = 1; x
array([[3, 1, 3],
       [3, 1, 3]])


numpy.recarray.imag

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.flat

Next topic

numpy.recarray.itemsize

numpy.recarray.imag

recarray.imag

The imaginary part of the array.

Examples

>>> x = np.sqrt([1+0j, 0+1j])
>>> x.imag
array([ 0.        ,  0.70710678])
>>> x.imag.dtype
dtype('float64')


numpy.recarray.itemsize

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.imag

Next topic

numpy.recarray.nbytes

numpy.recarray.itemsize

recarray.itemsize

Length of one array element in bytes.

Examples

>>> x = np.array([1,2,3], dtype=np.float64)
>>> x.itemsize
8
>>> x = np.array([1,2,3], dtype=np.complex128)
>>> x.itemsize
16


numpy.recarray.nbytes

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.itemsize

Next topic

numpy.recarray.ndim

numpy.recarray.nbytes

recarray.nbytes

Total bytes consumed by the elements of the array.

Notes

Does not include memory consumed by non-element attributes of the array object.

Examples

>>> x = np.zeros((3,5,2), dtype=np.complex128)
>>> x.nbytes
480
>>> np.prod(x.shape) * x.itemsize
480


numpy.recarray.ndim

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.nbytes

Next topic

numpy.recarray.real

numpy.recarray.ndim

recarray.ndim

Number of array dimensions.

Examples

>>> x = np.array([1, 2, 3])
>>> x.ndim
1
>>> y = np.zeros((2, 3, 4))
>>> y.ndim
3


numpy.recarray.real

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.ndim

Next topic

numpy.recarray.shape

numpy.recarray.real

recarray.real

The real part of the array.

See also

numpy.real
equivalent function

Examples

>>> x = np.sqrt([1+0j, 0+1j])
>>> x.real
array([ 1.        ,  0.70710678])
>>> x.real.dtype
dtype('float64')


numpy.recarray.shape

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.real

Next topic

numpy.recarray.size

numpy.recarray.shape

recarray.shape

Tuple of array dimensions.

Notes

May be used to “reshape” the array, as long as this would not require a change in the total number of elements

Examples

>>> x = np.array([1, 2, 3, 4])
>>> x.shape
(4,)
>>> y = np.zeros((2, 3, 4))
>>> y.shape
(2, 3, 4)
>>> y.shape = (3, 8)
>>> y
array([[ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])
>>> y.shape = (3, 6)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: total size of new array must be unchanged


numpy.recarray.size

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.shape

Next topic

numpy.recarray.strides

numpy.recarray.size

recarray.size

Number of elements in the array.

Equivalent to np.prod(a.shape), i.e., the product of the array’s dimensions.

Examples

>>> x = np.zeros((3, 5, 2), dtype=np.complex128)
>>> x.size
30
>>> np.prod(x.shape)
30


numpy.recarray.strides

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.size

Next topic

numpy.recarray.all

numpy.recarray.strides

recarray.strides

Tuple of bytes to step in each dimension when traversing an array.

The byte offset of element (i[0], i[1], ..., i[n]) in an array a is:

offset = sum(np.array(i) * a.strides)

A more detailed explanation of strides can be found in the “ndarray.rst” file in the NumPy reference guide.

See also

numpy.lib.stride_tricks.as_strided

Notes

Imagine an array of 32-bit integers (each 4 bytes):

x = np.array([[0, 1, 2, 3, 4],
              [5, 6, 7, 8, 9]], dtype=np.int32)

This array is stored in memory as 40 bytes, one after the other (known as a contiguous block of memory). The strides of an array tell us how many bytes we have to skip in memory to move to the next position along a certain axis. For example, we have to skip 4 bytes (1 value) to move to the next column, but 20 bytes (5 values) to get to the same position in the next row. As such, the strides for the array x will be (20, 4).

Examples

>>> y = np.reshape(np.arange(2*3*4), (2,3,4))
>>> y
array([[[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]],
       [[12, 13, 14, 15],
        [16, 17, 18, 19],
        [20, 21, 22, 23]]])
>>> y.strides
(48, 16, 4)
>>> y[1,1,1]
17
>>> offset=sum(y.strides * np.array((1,1,1)))
>>> offset/y.itemsize
17

>>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0)
>>> x.strides
(32, 4, 224, 1344)
>>> i = np.array([3,5,2,2])
>>> offset = sum(i * x.strides)
>>> x[3,5,2,2]
813
>>> offset / x.itemsize
813


numpy.recarray.all

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.strides

Next topic

numpy.recarray.any

numpy.recarray.all

recarray.all(axis=None, out=None)

Returns True if all elements evaluate to True.

Refer to numpy.all for full documentation.

See also

numpy.all
equivalent function


numpy.recarray.any

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.all

Next topic

numpy.recarray.argmax

numpy.recarray.any

recarray.any(axis=None, out=None)

Returns True if any of the elements of a evaluate to True.

Refer to numpy.any for full documentation.

See also

numpy.any
equivalent function


numpy.recarray.argmax

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.any

Next topic

numpy.recarray.argmin

numpy.recarray.argmax

recarray.argmax(axis=None, out=None)

Return indices of the maximum values along the given axis.

Refer to numpy.argmax for full documentation.

See also

numpy.argmax
equivalent function


numpy.recarray.argmin

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.argmax

Next topic

numpy.recarray.argpartition

numpy.recarray.argmin

recarray.argmin(axis=None, out=None)

Return indices of the minimum values along the given axis of a.

Refer to numpy.argmin for detailed documentation.

See also

numpy.argmin
equivalent function


numpy.recarray.argpartition

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.argmin

Next topic

numpy.recarray.argsort

numpy.recarray.argpartition

recarray.argpartition(kth, axis=-1, kind='introselect', order=None)

Returns the indices that would partition this array.

Refer to numpy.argpartition for full documentation.

New in version 1.8.0.

See also

numpy.argpartition
equivalent function


numpy.recarray.argsort

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.argpartition

Next topic

numpy.recarray.astype

numpy.recarray.argsort

recarray.argsort(axis=-1, kind='quicksort', order=None)

Returns the indices that would sort this array.

Refer to numpy.argsort for full documentation.

See also

numpy.argsort
equivalent function


numpy.recarray.astype

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.argsort

Next topic

numpy.recarray.byteswap

numpy.recarray.astype

recarray.astype(dtype, order='K', casting='unsafe', subok=True, copy=True)

Copy of the array, cast to a specified type.

Parameters:

dtype : str or dtype

Typecode or data-type to which the array is cast.

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout order of the result. ‘C’ means C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran contiguous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements appear in memory as possible. Default is ‘K’.

casting : {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

Controls what kind of data casting may occur. Defaults to ‘unsafe’ for backwards compatibility.

  • ‘no’ means the data types should not be cast at all.
  • ‘equiv’ means only byte-order changes are allowed.
  • ‘safe’ means only casts which can preserve values are allowed.
  • ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.
  • ‘unsafe’ means any data conversions may be done.

subok : bool, optional

If True, then sub-classes will be passed-through (default), otherwise the returned array will be forced to be a base-class array.

copy : bool, optional

By default, astype always returns a newly allocated array. If this is set to false, and the dtype, order, and subok requirements are satisfied, the input array is returned instead of a copy.
Returns:

arr_t : ndarray

Unless copy is False and the other conditions for returning the input array are satisfied (see description for copy input paramter), arr_t is a new array of the same shape as the input array, with dtype, order given by dtype, order.
Raises:

ComplexWarning

When casting from complex to float or int. To avoid this, one should use a.real.astype(t).

Notes

Starting in NumPy 1.9, astype method now returns an error if the string dtype to cast to is not long enough in ‘safe’ casting mode to hold the max value of integer/float array that is being casted. Previously the casting was allowed even if the result was truncated.

Examples

>>> x = np.array([1, 2, 2.5])
>>> x
array([ 1. ,  2. ,  2.5])

>>> x.astype(int)
array([1, 2, 2])


numpy.recarray.byteswap

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.astype

Next topic

numpy.recarray.choose

numpy.recarray.byteswap

recarray.byteswap(inplace)

Swap the bytes of the array elements

Toggle between low-endian and big-endian data representation by returning a byteswapped array, optionally swapped in-place.

Parameters:

inplace : bool, optional

If True, swap bytes in-place, default is False.
Returns:

out : ndarray

The byteswapped array. If inplace is True, this is a view to self.

Examples

>>> A = np.array([1, 256, 8755], dtype=np.int16)
>>> map(hex, A)
['0x1', '0x100', '0x2233']
>>> A.byteswap(True)
array([  256,     1, 13090], dtype=int16)
>>> map(hex, A)
['0x100', '0x1', '0x3322']

Arrays of strings are not swapped

>>> A = np.array(['ceg', 'fac'])
>>> A.byteswap()
array(['ceg', 'fac'],
      dtype='|S3')


numpy.recarray.choose

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.byteswap

Next topic

numpy.recarray.clip

numpy.recarray.choose

recarray.choose(choices, out=None, mode='raise')

Use an index array to construct a new array from a set of choices.

Refer to numpy.choose for full documentation.

See also

numpy.choose
equivalent function


numpy.recarray.clip

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.choose

Next topic

numpy.recarray.compress

numpy.recarray.clip

recarray.clip(a_min, a_max, out=None)

Return an array whose values are limited to [a_min, a_max].

Refer to numpy.clip for full documentation.

See also

numpy.clip
equivalent function


numpy.recarray.compress

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.clip

Next topic

numpy.recarray.conj

numpy.recarray.compress

recarray.compress(condition, axis=None, out=None)

Return selected slices of this array along given axis.

Refer to numpy.compress for full documentation.

See also

numpy.compress
equivalent function


numpy.recarray.conj

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.compress

Next topic

numpy.recarray.conjugate

numpy.recarray.conj

recarray.conj()

Complex-conjugate all elements.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.recarray.conjugate

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.conj

Next topic

numpy.recarray.copy

numpy.recarray.conjugate

recarray.conjugate()

Return the complex conjugate, element-wise.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.recarray.copy

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.conjugate

Next topic

numpy.recarray.cumprod

numpy.recarray.copy

recarray.copy(order='C')

Return a copy of the array.

Parameters:

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout of the copy. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible. (Note that this function and :func:numpy.copy are very similar, but have different default values for their order= arguments.)

See also

numpy.copy, numpy.copyto

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
       [0, 0, 0]])

>>> y
array([[1, 2, 3],
       [4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True


numpy.recarray.cumprod

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.copy

Next topic

numpy.recarray.cumsum

numpy.recarray.cumprod

recarray.cumprod(axis=None, dtype=None, out=None)

Return the cumulative product of the elements along the given axis.

Refer to numpy.cumprod for full documentation.

See also

numpy.cumprod
equivalent function


numpy.recarray.cumsum

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.cumprod

Next topic

numpy.recarray.diagonal

numpy.recarray.cumsum

recarray.cumsum(axis=None, dtype=None, out=None)

Return the cumulative sum of the elements along the given axis.

Refer to numpy.cumsum for full documentation.

See also

numpy.cumsum
equivalent function


numpy.recarray.diagonal

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.cumsum

Next topic

numpy.recarray.dot

numpy.recarray.diagonal

recarray.diagonal(offset=0, axis1=0, axis2=1)

Return specified diagonals. In NumPy 1.9 the returned array is a read-only view instead of a copy as in previous NumPy versions. In NumPy 1.10 the read-only restriction will be removed.

Refer to numpy.diagonal for full documentation.

See also

numpy.diagonal
equivalent function


numpy.recarray.dot

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.diagonal

Next topic

numpy.recarray.dump

numpy.recarray.dot

recarray.dot(b, out=None)

Dot product of two arrays.

Refer to numpy.dot for full documentation.

See also

numpy.dot
equivalent function

Examples

>>> a = np.eye(2)
>>> b = np.ones((2, 2)) * 2
>>> a.dot(b)
array([[ 2.,  2.],
       [ 2.,  2.]])

This array method can be conveniently chained:

>>> a.dot(b).dot(b)
array([[ 8.,  8.],
       [ 8.,  8.]])


numpy.recarray.dump

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.dot

Next topic

numpy.recarray.dumps

numpy.recarray.dump

recarray.dump(file)

Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.

Parameters:

file : str

A string naming the dump file.


numpy.recarray.dumps

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.dump

Next topic

numpy.recarray.field

numpy.recarray.dumps

recarray.dumps()

Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an array.

Parameters: None


numpy.recarray.field

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.dumps

Next topic

numpy.recarray.fill

numpy.recarray.field

recarray.field(attr, val=None) [source]


numpy.recarray.fill

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.field

Next topic

numpy.recarray.flatten

numpy.recarray.fill

recarray.fill(value)

Fill the array with a scalar value.

Parameters:

value : scalar

All elements of a will be assigned this value.

Examples

>>> a = np.array([1, 2])
>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([ 1.,  1.])


numpy.recarray.flatten

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.fill

Next topic

numpy.recarray.getfield

numpy.recarray.flatten

recarray.flatten(order='C')

Return a copy of the array collapsed into one dimension.

Parameters:

order : {‘C’, ‘F’, ‘A’}, optional

Whether to flatten in C (row-major), Fortran (column-major) order, or preserve the C/Fortran ordering from a. The default is ‘C’.
Returns:

y : ndarray

A copy of the input array, flattened to one dimension.

See also

ravel
Return a flattened array.
flat
A 1-D flat iterator over the array.

Examples

>>> a = np.array([[1,2], [3,4]])
>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten('F')
array([1, 3, 2, 4])


numpy.recarray.getfield

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.flatten

Next topic

numpy.recarray.item

numpy.recarray.getfield

recarray.getfield(dtype, offset=0)

Returns a field of the given array as a certain type.

A field is a view of the array data with a given data-type. The values in the view are determined by the given type and the offset into the current array in bytes. The offset needs to be such that the view dtype fits in the array dtype; for example an array of dtype complex128 has 16-byte elements. If taking a view with a 32-bit integer (4 bytes), the offset needs to be between 0 and 12 bytes.

Parameters:

dtype : str or dtype

The data type of the view. The dtype size of the view can not be larger than that of the array itself.

offset : int

Number of bytes to skip before beginning the element view.

Examples

>>> x = np.diag([1.+1.j]*2)
>>> x[1, 1] = 2 + 4.j
>>> x
array([[ 1.+1.j,  0.+0.j],
       [ 0.+0.j,  2.+4.j]])
>>> x.getfield(np.float64)
array([[ 1.,  0.],
       [ 0.,  2.]])

By choosing an offset of 8 bytes we can select the complex part of the array for our view:

>>> x.getfield(np.float64, offset=8)
array([[ 1.,  0.],
   [ 0.,  4.]])


numpy.recarray.item

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.getfield

Next topic

numpy.recarray.itemset

numpy.recarray.item

recarray.item(*args)

Copy an element of an array to a standard Python scalar and return it.

Parameters:

*args : Arguments (variable number and type)

  • none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.
  • int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.
  • tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.
Returns:

z : Standard Python scalar object

A copy of the specified element of the array as a suitable Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.item(3)
2
>>> x.item(7)
5
>>> x.item((0, 1))
1
>>> x.item((2, 2))
3


numpy.recarray.itemset

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.item

Next topic

numpy.recarray.max

numpy.recarray.itemset

recarray.itemset(*args)

Insert scalar into an array (scalar is cast to array’s dtype, if possible)

There must be at least 1 argument, and define the last argument as item. Then, a.itemset(*args) is equivalent to but faster than a[args] = item. The item should be a scalar value and args must select a single item in the array a.

Parameters:

*args : Arguments

If one argument: a scalar, only used in case a is of size 1. If two arguments: the last argument is the value to be set and must be a scalar, the first argument specifies a single array element location. It is either an int or a tuple.

Notes

Compared to indexing syntax, itemset provides some speed increase for placing a scalar into a particular location in an ndarray, if you must do this. However, generally this is discouraged: among other problems, it complicates the appearance of the code. Also, when using itemset (and item) inside a loop, be sure to assign the methods to a local variable to avoid the attribute look-up at each loop iteration.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.itemset(4, 0)
>>> x.itemset((2, 2), 9)
>>> x
array([[3, 1, 7],
       [2, 0, 3],
       [8, 5, 9]])


numpy.recarray.max

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.itemset

Next topic

numpy.recarray.mean

numpy.recarray.max

recarray.max(axis=None, out=None)

Return the maximum along a given axis.

Refer to numpy.amax for full documentation.

See also

numpy.amax
equivalent function


numpy.recarray.mean

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.max

Next topic

numpy.recarray.min

numpy.recarray.mean

recarray.mean(axis=None, dtype=None, out=None)

Returns the average of the array elements along given axis.

Refer to numpy.mean for full documentation.

See also

numpy.mean
equivalent function


numpy.recarray.min

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.mean

Next topic

numpy.recarray.newbyteorder

numpy.recarray.min

recarray.min(axis=None, out=None)

Return the minimum along a given axis.

Refer to numpy.amin for full documentation.

See also

numpy.amin
equivalent function


numpy.recarray.newbyteorder

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.min

Next topic

numpy.recarray.nonzero

numpy.recarray.newbyteorder

recarray.newbyteorder(new_order='S')

Return the array with the same data viewed with a different byte order.

Equivalent to:

arr.view(arr.dtype.newbytorder(new_order))

Changes are also made in all fields and sub-arrays of the array data type.

Parameters:

new_order : string, optional

Byte order to force; a value from the byte order specifications above. new_order codes can be any of:

* 'S' - swap dtype from current to opposite endian
* {'<', 'L'} - little endian
* {'>', 'B'} - big endian
* {'=', 'N'} - native order
* {'|', 'I'} - ignore (no change to byte order)

The default value (‘S’) results in swapping the current byte order. The code does a case-insensitive check on the first letter of new_order for the alternatives above. For example, any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns:

new_arr : array

New array object with the dtype reflecting given change to the byte order.


numpy.recarray.nonzero

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.newbyteorder

Next topic

numpy.recarray.partition

numpy.recarray.nonzero

recarray.nonzero()

Return the indices of the elements that are non-zero.

Refer to numpy.nonzero for full documentation.

See also

numpy.nonzero
equivalent function


numpy.recarray.partition

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.nonzero

Next topic

numpy.recarray.prod

numpy.recarray.partition

recarray.partition(kth, axis=-1, kind='introselect', order=None)

Rearranges the elements in the array in such a way that value of the element in kth position is in the position it would be in a sorted array. All elements smaller than the kth element are moved before this element and all equal or greater are moved behind it. The ordering of the elements in the two partitions is undefined.

New in version 1.8.0.

Parameters:

kth : int or sequence of ints

Element index to partition by. The kth element value will be in its final sorted position and all smaller elements will be moved before it and all equal or greater elements behind it. The order all elements in the partitions is undefined. If provided with a sequence of kth it will partition all elements indexed by kth of them into their sorted position at once.

axis : int, optional

Axis along which to sort. Default is -1, which means sort along the last axis.

kind : {‘introselect’}, optional

Selection algorithm. Default is ‘introselect’.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.

See also

numpy.partition
Return a parititioned copy of an array.
argpartition
Indirect partition.
sort
Full sort.

Notes

See np.partition for notes on the different algorithms.

Examples

>>> a = np.array([3, 4, 2, 1])
>>> a.partition(a, 3)
>>> a
array([2, 1, 3, 4])

>>> a.partition((1, 3))
array([1, 2, 3, 4])


numpy.recarray.prod

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.partition

Next topic

numpy.recarray.ptp

numpy.recarray.prod

recarray.prod(axis=None, dtype=None, out=None)

Return the product of the array elements over the given axis

Refer to numpy.prod for full documentation.

See also

numpy.prod
equivalent function


numpy.recarray.ptp

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.prod

Next topic

numpy.recarray.put

numpy.recarray.ptp

recarray.ptp(axis=None, out=None)

Peak to peak (maximum - minimum) value along a given axis.

Refer to numpy.ptp for full documentation.

See also

numpy.ptp
equivalent function


numpy.recarray.put

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.ptp

Next topic

numpy.recarray.ravel

numpy.recarray.put

recarray.put(indices, values, mode='raise')

Set a.flat[n] = values[n] for all n in indices.

Refer to numpy.put for full documentation.

See also

numpy.put
equivalent function


numpy.recarray.ravel

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.put

Next topic

numpy.recarray.repeat

numpy.recarray.ravel

recarray.ravel([order])

Return a flattened array.

Refer to numpy.ravel for full documentation.

See also

numpy.ravel
equivalent function
ndarray.flat
a flat iterator on the array.


numpy.recarray.repeat

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.ravel

Next topic

numpy.recarray.reshape

numpy.recarray.repeat

recarray.repeat(repeats, axis=None)

Repeat elements of an array.

Refer to numpy.repeat for full documentation.

See also

numpy.repeat
equivalent function


numpy.recarray.reshape

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.repeat

Next topic

numpy.recarray.resize

numpy.recarray.reshape

recarray.reshape(shape, order='C')

Returns an array containing the same data with a new shape.

Refer to numpy.reshape for full documentation.

See also

numpy.reshape
equivalent function


numpy.recarray.resize

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.reshape

Next topic

numpy.recarray.round

numpy.recarray.resize

recarray.resize(new_shape, refcheck=True)

Change shape and size of array in-place.

Parameters:

new_shape : tuple of ints, or n ints

Shape of resized array.

refcheck : bool, optional

If False, reference count will not be checked. Default is True.
Returns:

None
Raises:

ValueError

If a does not own its own data or references or views to it exist, and the data memory must be changed.

SystemError

If the order keyword argument is specified. This behaviour is a bug in NumPy.

See also

resize
Return a new array with the specified shape.

Notes

This reallocates space for the data area if necessary.

Only contiguous arrays (data elements consecutive in memory) can be resized.

The purpose of the reference count check is to make sure you do not use this array as a buffer for another Python object and then reallocate the memory. However, reference counts can increase in other ways so if you are sure that you have not shared the memory for this array with another Python object, then you may safely set refcheck to False.

Examples

Shrinking an array: array is flattened (in the order that the data are stored in memory), resized, and reshaped:

>>> a = np.array([[0, 1], [2, 3]], order='C')
>>> a.resize((2, 1))
>>> a
array([[0],
       [1]])

>>> a = np.array([[0, 1], [2, 3]], order='F')
>>> a.resize((2, 1))
>>> a
array([[0],
       [2]])

Enlarging an array: as above, but missing entries are filled with zeros:

>>> b = np.array([[0, 1], [2, 3]])
>>> b.resize(2, 3) # new_shape parameter doesn't have to be a tuple
>>> b
array([[0, 1, 2],
       [3, 0, 0]])

Referencing an array prevents resizing...

>>> c = a
>>> a.resize((1, 1))
Traceback (most recent call last):
...
ValueError: cannot resize an array that has been referenced ...

Unless refcheck is False:

>>> a.resize((1, 1), refcheck=False)
>>> a
array([[0]])
>>> c
array([[0]])


numpy.recarray.round

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.resize

Next topic

numpy.recarray.searchsorted

numpy.recarray.round

recarray.round(decimals=0, out=None)

Return a with each element rounded to the given number of decimals.

Refer to numpy.around for full documentation.

See also

numpy.around
equivalent function


numpy.recarray.searchsorted

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.round

Next topic

numpy.recarray.setfield

numpy.recarray.searchsorted

recarray.searchsorted(v, side='left', sorter=None)

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See also

numpy.searchsorted
equivalent function


numpy.recarray.setfield

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.searchsorted

Next topic

numpy.recarray.setflags

numpy.recarray.setfield

recarray.setfield(val, dtype, offset=0)

Put a value into a specified place in a field defined by a data-type.

Place val into a‘s field defined by dtype and beginning offset bytes into the field.

Parameters:

val : object

Value to be placed in field.

dtype : dtype object

Data-type of the field in which to place val.

offset : int, optional

The number of bytes into the field at which to place val.
Returns:

None

See also

getfield

Examples

>>> x = np.eye(3)
>>> x.getfield(np.float64)
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
>>> x.setfield(3, np.int32)
>>> x.getfield(np.int32)
array([[3, 3, 3],
       [3, 3, 3],
       [3, 3, 3]])
>>> x
array([[  1.00000000e+000,   1.48219694e-323,   1.48219694e-323],
       [  1.48219694e-323,   1.00000000e+000,   1.48219694e-323],
       [  1.48219694e-323,   1.48219694e-323,   1.00000000e+000]])
>>> x.setfield(np.eye(3), np.int32)
>>> x
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])


numpy.recarray.setflags

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.setfield

Next topic

numpy.recarray.sort

numpy.recarray.setflags

recarray.setflags(write=None, align=None, uic=None)

Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively.

These Boolean-valued flags affect how numpy interprets the memory area used by a (see Notes below). The ALIGNED flag can only be set to True if the data is actually aligned according to the type. The UPDATEIFCOPY flag can never be set to True. The flag WRITEABLE can only be set to True if the array owns its own memory, or the ultimate owner of the memory exposes a writeable buffer interface, or is a string. (The exception for string is made so that unpickling can be done without copying memory.)

Parameters:

write : bool, optional

Describes whether or not a can be written to.

align : bool, optional

Describes whether or not a is aligned properly for its type.

uic : bool, optional

Describes whether or not a is a copy of another “base” array.

Notes

Array flags provide information about how the memory area used for the array is to be interpreted. There are 6 Boolean flags in use, only three of which can be changed by the user: UPDATEIFCOPY, WRITEABLE, and ALIGNED.

WRITEABLE (W) the data area can be written to;

ALIGNED (A) the data and strides are aligned appropriately for the hardware (as determined by the compiler);

UPDATEIFCOPY (U) this array is a copy of some other array (referenced by .base). When this array is deallocated, the base array will be updated with the contents of this array.

All flags can be accessed using their first (upper case) letter as well as the full name.

Examples

>>> y
array([[3, 1, 7],
       [2, 0, 0],
       [8, 5, 9]])
>>> y.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : True
  WRITEABLE : True
  ALIGNED : True
  UPDATEIFCOPY : False
>>> y.setflags(write=0, align=0)
>>> y.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : True
  WRITEABLE : False
  ALIGNED : False
  UPDATEIFCOPY : False
>>> y.setflags(uic=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: cannot set UPDATEIFCOPY flag to True


numpy.recarray.sort

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.setflags

Next topic

numpy.recarray.squeeze

numpy.recarray.sort

recarray.sort(axis=-1, kind='quicksort', order=None)

Sort an array, in-place.

Parameters:

axis : int, optional

Axis along which to sort. Default is -1, which means sort along the last axis.

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm. Default is ‘quicksort’.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.

See also

numpy.sort
Return a sorted copy of an array.
argsort
Indirect sort.
lexsort
Indirect stable sort on multiple keys.
searchsorted
Find elements in sorted array.
partition
Partial sort.

Notes

See sort for notes on the different sorting algorithms.

Examples

>>> a = np.array([[1,4], [3,1]])
>>> a.sort(axis=1)
>>> a
array([[1, 4],
       [1, 3]])
>>> a.sort(axis=0)
>>> a
array([[1, 3],
       [1, 4]])

Use the order keyword to specify a field to use when sorting a structured array:

>>> a = np.array([('a', 2), ('c', 1)], dtype=[('x', 'S1'), ('y', int)])
>>> a.sort(order='y')
>>> a
array([('c', 1), ('a', 2)],
      dtype=[('x', '|S1'), ('y', '<i4')])


numpy.recarray.squeeze

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.sort

Next topic

numpy.recarray.std

numpy.recarray.squeeze

recarray.squeeze(axis=None)

Remove single-dimensional entries from the shape of a.

Refer to numpy.squeeze for full documentation.

See also

numpy.squeeze
equivalent function


numpy.recarray.std

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.squeeze

Next topic

numpy.recarray.sum

numpy.recarray.std

recarray.std(axis=None, dtype=None, out=None, ddof=0)

Returns the standard deviation of the array elements along given axis.

Refer to numpy.std for full documentation.

See also

numpy.std
equivalent function


numpy.recarray.sum

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.std

Next topic

numpy.recarray.swapaxes

numpy.recarray.sum

recarray.sum(axis=None, dtype=None, out=None)

Return the sum of the array elements over the given axis.

Refer to numpy.sum for full documentation.

See also

numpy.sum
equivalent function


numpy.recarray.swapaxes

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.sum

Next topic

numpy.recarray.take

numpy.recarray.swapaxes

recarray.swapaxes(axis1, axis2)

Return a view of the array with axis1 and axis2 interchanged.

Refer to numpy.swapaxes for full documentation.

See also

numpy.swapaxes
equivalent function


numpy.recarray.take

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.swapaxes

Next topic

numpy.recarray.tobytes

numpy.recarray.take

recarray.take(indices, axis=None, out=None, mode='raise')

Return an array formed from the elements of a at the given indices.

Refer to numpy.take for full documentation.

See also

numpy.take
equivalent function


numpy.recarray.tobytes

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.take

Next topic

numpy.recarray.tofile

numpy.recarray.tobytes

recarray.tobytes(order='C')

Construct Python bytes containing the raw data bytes in the array.

Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.

New in version 1.9.0.

Parameters:

order : {‘C’, ‘F’, None}, optional

Order of the data for multidimensional arrays: C, Fortran, or the same as for the original array.
Returns:

s : bytes

Python bytes exhibiting a copy of a‘s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]])
>>> x.tobytes()
b'\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x03\x00\x00\x00'


numpy.recarray.tofile

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.tobytes

Next topic

numpy.recarray.tolist

numpy.recarray.tofile

recarray.tofile(fid, sep="", format="%s")

Write array to a file as text or binary (default).

Data is always written in ‘C’ order, independent of the order of a. The data produced by this method can be recovered using the function fromfile().

Parameters:

fid : file or str

An open file object, or a string containing a filename.

sep : str

Separator between array items for text output. If “” (empty), a binary file is written, equivalent to file.write(a.tobytes()).

format : str

Format string for text file output. Each entry in the array is formatted to text by first converting it to the closest Python type, and then using “format” % item.

Notes

This is a convenience function for quick storage of array data. Information on endianness and precision is lost, so this method is not a good choice for files intended to archive data or transport data between machines with different endianness. Some of these problems can be overcome by outputting the data as text files, at the expense of speed and file size.


numpy.recarray.tolist

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.tofile

Next topic

numpy.recarray.tostring

numpy.recarray.tolist

recarray.tolist()

Return the array as a (possibly nested) list.

Return a copy of the array data as a (nested) Python list. Data items are converted to the nearest compatible Python type.

Parameters:

none
Returns:

y : list

The possibly nested list of array elements.

Notes

The array may be recreated, a = np.array(a.tolist()).

Examples

>>> a = np.array([1, 2])
>>> a.tolist()
[1, 2]
>>> a = np.array([[1, 2], [3, 4]])
>>> list(a)
[array([1, 2]), array([3, 4])]
>>> a.tolist()
[[1, 2], [3, 4]]


numpy.recarray.tostring

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.tolist

Next topic

numpy.recarray.trace

numpy.recarray.tostring

recarray.tostring(order='C')

Construct Python bytes containing the raw data bytes in the array.

Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.

This function is a compatibility alias for tobytes. Despite its name it returns bytes not strings.

Parameters:

order : {‘C’, ‘F’, None}, optional

Order of the data for multidimensional arrays: C, Fortran, or the same as for the original array.
Returns:

s : bytes

Python bytes exhibiting a copy of a‘s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]])
>>> x.tobytes()
b'\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x03\x00\x00\x00'


numpy.recarray.trace

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.tostring

Next topic

numpy.recarray.transpose

numpy.recarray.trace

recarray.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)

Return the sum along diagonals of the array.

Refer to numpy.trace for full documentation.

See also

numpy.trace
equivalent function


numpy.recarray.transpose

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.trace

Next topic

numpy.recarray.var

numpy.recarray.transpose

recarray.transpose(*axes)

Returns a view of the array with axes transposed.

For a 1-D array, this has no effect. (To change between column and row vectors, first cast the 1-D array into a matrix object.) For a 2-D array, this is the usual matrix transpose. For an n-D array, if axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided and a.shape = (i[0], i[1], ... i[n-2], i[n-1]), then a.transpose().shape = (i[n-1], i[n-2], ... i[1], i[0]).

Parameters:

axes : None, tuple of ints, or n ints

  • None or no argument: reverses the order of the axes.
  • tuple of ints: i in the j-th place in the tuple means a‘s i-th axis becomes a.transpose()‘s j-th axis.
  • n ints: same as an n-tuple of the same ints (this form is intended simply as a “convenience” alternative to the tuple form)
Returns:

out : ndarray

View of a, with axes suitably permuted.

See also

ndarray.T
Array property returning the array transposed.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> a
array([[1, 2],
       [3, 4]])
>>> a.transpose()
array([[1, 3],
       [2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
       [2, 4]])
>>> a.transpose(1, 0)
array([[1, 3],
       [2, 4]])


numpy.recarray.var

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.transpose

Next topic

numpy.recarray.view

numpy.recarray.var

recarray.var(axis=None, dtype=None, out=None, ddof=0)

Returns the variance of the array elements, along given axis.

Refer to numpy.var for full documentation.

See also

numpy.var
equivalent function


numpy.recarray.view

  • Array objects
  • Standard array subclasses
  • numpy.recarray
  • index
  • next
  • previous

Previous topic

numpy.recarray.var

Next topic

numpy.record

numpy.recarray.view

recarray.view(dtype=None, type=None) [source]


numpy.record

  • Array objects
  • Standard array subclasses
  • index
  • next
  • previous

Previous topic

numpy.recarray.view

Next topic

numpy.record.T

numpy.record

class numpy.record [source]

A data-type scalar that allows field access as attribute lookup.

Attributes

T | transpose
base | base object
data | pointer to start of data
dtype | dtype object
flags | integer value of flags
flat | a 1-d view of scalar
imag | imaginary part of scalar
itemsize | length of one element in bytes
nbytes | length of item in bytes
ndim | number of array dimensions
real | real part of scalar
shape | tuple of array dimensions
size | number of elements in the gentype
strides | tuple of bytes steps in each dimension

Methods

all | Not implemented (virtual attribute)
any | Not implemented (virtual attribute)
argmax | Not implemented (virtual attribute)
argmin | Not implemented (virtual attribute)
argsort | Not implemented (virtual attribute)
astype | Not implemented (virtual attribute)
byteswap | Not implemented (virtual attribute)
choose | Not implemented (virtual attribute)
clip | Not implemented (virtual attribute)
compress | Not implemented (virtual attribute)
conj
conjugate | Not implemented (virtual attribute)
copy | Not implemented (virtual attribute)
cumprod | Not implemented (virtual attribute)
cumsum | Not implemented (virtual attribute)
diagonal | Not implemented (virtual attribute)
dump | Not implemented (virtual attribute)
dumps | Not implemented (virtual attribute)
fill | Not implemented (virtual attribute)
flatten | Not implemented (virtual attribute)
getfield
item | Not implemented (virtual attribute)
itemset | Not implemented (virtual attribute)
max | Not implemented (virtual attribute)
mean | Not implemented (virtual attribute)
min | Not implemented (virtual attribute)
newbyteorder([new_order]) | Return a new dtype with a different byte order.
nonzero | Not implemented (virtual attribute)
pprint() | Pretty-print all fields.
prod | Not implemented (virtual attribute)
ptp | Not implemented (virtual attribute)
put | Not implemented (virtual attribute)
ravel | Not implemented (virtual attribute)
repeat | Not implemented (virtual attribute)
reshape | Not implemented (virtual attribute)
resize | Not implemented (virtual attribute)
round | Not implemented (virtual attribute)
searchsorted | Not implemented (virtual attribute)
setfield
setflags | Not implemented (virtual attribute)
sort | Not implemented (virtual attribute)
squeeze | Not implemented (virtual attribute)
std | Not implemented (virtual attribute)
sum | Not implemented (virtual attribute)
swapaxes | Not implemented (virtual attribute)
take | Not implemented (virtual attribute)
tobytes
tofile | Not implemented (virtual attribute)
tolist | Not implemented (virtual attribute)
tostring | Not implemented (virtual attribute)
trace | Not implemented (virtual attribute)
transpose | Not implemented (virtual attribute)
var | Not implemented (virtual attribute)
view | Not implemented (virtual attribute)


numpy.record.T

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record

Next topic

numpy.record.base

numpy.record.T

record.T

transpose


numpy.record.base

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.T

Next topic

numpy.record.data

numpy.record.base

record.base

base object


numpy.record.data

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.base

Next topic

numpy.record.dtype

numpy.record.data

record.data

pointer to start of data


numpy.record.dtype

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.data

Next topic

numpy.record.flags

numpy.record.dtype

record.dtype

dtype object


numpy.record.flags

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.dtype

Next topic

numpy.record.flat

numpy.record.flags

record.flags

integer value of flags


numpy.record.flat

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.flags

Next topic

numpy.record.imag

numpy.record.flat

record.flat

a 1-d view of scalar


numpy.record.imag

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.flat

Next topic

numpy.record.itemsize

numpy.record.imag

record.imag

imaginary part of scalar


numpy.record.itemsize

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.imag

Next topic

numpy.record.nbytes

numpy.record.itemsize

record.itemsize

length of one element in bytes


numpy.record.nbytes

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.itemsize

Next topic

numpy.record.ndim

numpy.record.nbytes

record.nbytes

length of item in bytes


numpy.record.ndim

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.nbytes

Next topic

numpy.record.real

numpy.record.ndim

record.ndim

number of array dimensions


numpy.record.real

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.ndim

Next topic

numpy.record.shape

numpy.record.real

record.real

real part of scalar


numpy.record.shape

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.real

Next topic

numpy.record.size

numpy.record.shape

record.shape

tuple of array dimensions


numpy.record.size

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.shape

Next topic

numpy.record.strides

numpy.record.size

record.size

number of elements in the gentype


numpy.record.strides

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.size

Next topic

numpy.record.all

numpy.record.strides

record.strides

tuple of bytes steps in each dimension


numpy.record.all

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.strides

Next topic

numpy.record.any

numpy.record.all

record.all()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.any

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.all

Next topic

numpy.record.argmax

numpy.record.any

record.any()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.argmax

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.any

Next topic

numpy.record.argmin

numpy.record.argmax

record.argmax()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.argmin

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.argmax

Next topic

numpy.record.argsort

numpy.record.argmin

record.argmin()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.argsort

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.argmin

Next topic

numpy.record.astype

numpy.record.argsort

record.argsort()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.astype

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.argsort

Next topic

numpy.record.byteswap

numpy.record.astype

record.astype()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.byteswap

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.astype

Next topic

numpy.record.choose

numpy.record.byteswap

record.byteswap()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.choose

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.byteswap

Next topic

numpy.record.clip

numpy.record.choose

record.choose()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.clip

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.choose

Next topic

numpy.record.compress

numpy.record.clip

record.clip()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.compress

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.clip

Next topic

numpy.record.conj

numpy.record.compress

record.compress()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.conj

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.compress

Next topic

numpy.record.conjugate

numpy.record.conj

record.conj()


numpy.record.conjugate

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.conj

Next topic

numpy.record.copy

numpy.record.conjugate

record.conjugate()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.copy

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.conjugate

Next topic

numpy.record.cumprod

numpy.record.copy

record.copy()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.cumprod

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.copy

Next topic

numpy.record.cumsum

numpy.record.cumprod

record.cumprod()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.cumsum

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.cumprod

Next topic

numpy.record.diagonal

numpy.record.cumsum

record.cumsum()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.diagonal

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.cumsum

Next topic

numpy.record.dump

numpy.record.diagonal

record.diagonal()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.dump

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.diagonal

Next topic

numpy.record.dumps

numpy.record.dump

record.dump()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.dumps

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.dump

Next topic

numpy.record.fill

numpy.record.dumps

record.dumps()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.fill

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.dumps

Next topic

numpy.record.flatten

numpy.record.fill

record.fill()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.flatten

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.fill

Next topic

numpy.record.getfield

numpy.record.flatten

record.flatten()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.getfield

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.flatten

Next topic

numpy.record.item

numpy.record.getfield

record.getfield()


numpy.record.item

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.getfield

Next topic

numpy.record.itemset

numpy.record.item

record.item()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.itemset

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.item

Next topic

numpy.record.max

numpy.record.itemset

record.itemset()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.max

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.itemset

Next topic

numpy.record.mean

numpy.record.max

record.max()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.mean

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.max

Next topic

numpy.record.min

numpy.record.mean

record.mean()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.min

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.mean

Next topic

numpy.record.newbyteorder

numpy.record.min

record.min()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.newbyteorder

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.min

Next topic

numpy.record.nonzero

numpy.record.newbyteorder

record.newbyteorder(new_order='S')

Return a new dtype with a different byte order.

Changes are also made in all fields and sub-arrays of the data type.

The new_order code can be any from the following:

  • {‘<’, ‘L’} - little endian
  • {‘>’, ‘B’} - big endian
  • {‘=’, ‘N’} - native order
  • ‘S’ - swap dtype from current to opposite endian
  • {‘|’, ‘I’} - ignore (no change to byte order)
Parameters:

new_order : str, optional

Byte order to force; a value from the byte order specifications above. The default value (‘S’) results in swapping the current byte order. The code does a case-insensitive check on the first letter of new_order for the alternatives above. For example, any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns:

new_dtype : dtype

New dtype object with the given change to the byte order.


numpy.record.nonzero

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.newbyteorder

Next topic

numpy.record.pprint

numpy.record.nonzero

record.nonzero()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.pprint

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.nonzero

Next topic

numpy.record.prod

numpy.record.pprint

record.pprint() [source]

Pretty-print all fields.


numpy.record.prod

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.pprint

Next topic

numpy.record.ptp

numpy.record.prod

record.prod()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.ptp

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.prod

Next topic

numpy.record.put

numpy.record.ptp

record.ptp()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.put

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.ptp

Next topic

numpy.record.ravel

numpy.record.put

record.put()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.ravel

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.put

Next topic

numpy.record.repeat

numpy.record.ravel

record.ravel()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.repeat

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.ravel

Next topic

numpy.record.reshape

numpy.record.repeat

record.repeat()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.reshape

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.repeat

Next topic

numpy.record.resize

numpy.record.reshape

record.reshape()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.resize

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.reshape

Next topic

numpy.record.round

numpy.record.resize

record.resize()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.round

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.resize

Next topic

numpy.record.searchsorted

numpy.record.round

record.round()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.searchsorted

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.round

Next topic

numpy.record.setfield

numpy.record.searchsorted

record.searchsorted()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.setfield

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.searchsorted

Next topic

numpy.record.setflags

numpy.record.setfield

record.setfield()


numpy.record.setflags

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.setfield

Next topic

numpy.record.sort

numpy.record.setflags

record.setflags()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.sort

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.setflags

Next topic

numpy.record.squeeze

numpy.record.sort

record.sort()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.squeeze

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.sort

Next topic

numpy.record.std

numpy.record.squeeze

record.squeeze()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.std

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.squeeze

Next topic

numpy.record.sum

numpy.record.std

record.std()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.sum

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.std

Next topic

numpy.record.swapaxes

numpy.record.sum

record.sum()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.swapaxes

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.sum

Next topic

numpy.record.take

numpy.record.swapaxes

record.swapaxes()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.take

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.swapaxes

Next topic

numpy.record.tobytes

numpy.record.take

record.take()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.tobytes

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.take

Next topic

numpy.record.tofile

numpy.record.tobytes

record.tobytes()


numpy.record.tofile

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.tobytes

Next topic

numpy.record.tolist

numpy.record.tofile

record.tofile()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.tolist

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.tofile

Next topic

numpy.record.tostring

numpy.record.tolist

record.tolist()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.tostring

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.tolist

Next topic

numpy.record.trace

numpy.record.tostring

record.tostring()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.trace

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.tostring

Next topic

numpy.record.transpose

numpy.record.trace

record.trace()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.transpose

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.trace

Next topic

numpy.record.var

numpy.record.transpose

record.transpose()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.var

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.transpose

Next topic

numpy.record.view

numpy.record.var

record.var()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.record.view

  • Array objects
  • Standard array subclasses
  • numpy.record
  • index
  • next
  • previous

Previous topic

numpy.record.var

Next topic

numpy.lib.user_array.container

numpy.record.view

record.view()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.lib.user_array.container

  • Array objects
  • Standard array subclasses
  • index
  • next
  • previous

Previous topic

numpy.record.view

Next topic

numpy.lib.user_array.container.astype

numpy.lib.user_array.container

class numpy.lib.user_array.container(data, dtype=None, copy=True) [source]

Methods

astype(typecode)
byteswap()
copy()
tostring()


numpy.lib.user_array.container.astype

  • Array objects
  • Standard array subclasses
  • numpy.lib.user_array.container
  • index
  • next
  • previous

Previous topic

numpy.lib.user_array.container

Next topic

numpy.lib.user_array.container.byteswap

numpy.lib.user_array.container.astype

container.astype(typecode) [source]


numpy.lib.user_array.container.byteswap

  • Array objects
  • Standard array subclasses
  • numpy.lib.user_array.container
  • index
  • next
  • previous

Previous topic

numpy.lib.user_array.container.astype

Next topic

numpy.lib.user_array.container.copy

numpy.lib.user_array.container.byteswap

container.byteswap() [source]


numpy.lib.user_array.container.copy

  • Array objects
  • Standard array subclasses
  • numpy.lib.user_array.container
  • index
  • next
  • previous

Previous topic

numpy.lib.user_array.container.byteswap

Next topic

numpy.lib.user_array.container.tostring

numpy.lib.user_array.container.copy

container.copy() [source]


numpy.lib.user_array.container.tostring

  • Array objects
  • Standard array subclasses
  • numpy.lib.user_array.container
  • index
  • next
  • previous

Previous topic

numpy.lib.user_array.container.copy

Next topic

numpy.ndarray.flat

numpy.lib.user_array.container.tostring

container.tostring() [source]


numpy.ndenumerate

  • Indexing routines
  • next
  • previous

Previous topic

numpy.nditer.reset

Next topic

numpy.ndenumerate.next

numpy.ndenumerate

class numpy.ndenumerate(arr) [source]

Multidimensional index iterator.

Return an iterator yielding pairs of array coordinates and values.

Parameters:

a : ndarray

Input array.

See also

ndindex, flatiter

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> for index, x in np.ndenumerate(a):
...     print index, x
(0, 0) 1
(0, 1) 2
(1, 0) 3
(1, 1) 4

Methods

next() Standard iterator method, returns the index tuple and array value.


numpy.ndenumerate.next

  • Indexing routines
  • numpy.ndenumerate
  • index
  • next
  • previous

Previous topic

numpy.ndenumerate

Next topic

numpy.ndindex

numpy.ndenumerate.next

ndenumerate.next() [source]

Standard iterator method, returns the index tuple and array value.

Returns:

coords : tuple of ints

The indices of the current iteration.

val : scalar

The array element of the current iteration.


numpy.broadcast

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.atleast_3d

Next topic

numpy.broadcast.index

numpy.broadcast

class numpy.broadcast [source]

Produce an object that mimics broadcasting.

Parameters:

in1, in2, ... : array_like

Input parameters.
Returns:

b : broadcast object

Broadcast the input parameters against one another, and return an object that encapsulates the result. Amongst others, it has shape and nd properties, and may be used as an iterator.

Examples

Manually adding two vectors, using broadcasting:

>>> x = np.array([[1], [2], [3]])
>>> y = np.array([4, 5, 6])
>>> b = np.broadcast(x, y)

>>> out = np.empty(b.shape)
>>> out.flat = [u+v for (u,v) in b]
>>> out
array([[ 5.,  6.,  7.],
       [ 6.,  7.,  8.],
       [ 7.,  8.,  9.]])

Compare against built-in broadcasting:

>>> x + y
array([[5, 6, 7],
       [6, 7, 8],
       [7, 8, 9]])

Attributes

index | current index in broadcasted result
iters | tuple of iterators along self‘s “components.”
shape | Shape of broadcasted result.
size | Total size of broadcasted result.

Methods

next | x.next() -> the next value, or raise StopIteration
reset() | Reset the broadcasted result’s iterator(s).


numpy.broadcast.index

  • Array manipulation routines
  • numpy.broadcast
  • index
  • next
  • previous

Previous topic

numpy.broadcast

Next topic

numpy.broadcast.iters

numpy.broadcast.index

broadcast.index

current index in broadcasted result

Examples

>>> x = np.array([[1], [2], [3]])
>>> y = np.array([4, 5, 6])
>>> b = np.broadcast(x, y)
>>> b.index
0
>>> b.next(), b.next(), b.next()
((1, 4), (1, 5), (1, 6))
>>> b.index
3


numpy.broadcast.iters

  • Array manipulation routines
  • numpy.broadcast
  • index
  • next
  • previous

Previous topic

numpy.broadcast.index

Next topic

numpy.broadcast.shape

numpy.broadcast.iters

broadcast.iters

tuple of iterators along self‘s “components.”

Returns a tuple of numpy.flatiter objects, one for each “component” of self.

See also

numpy.flatiter

Examples

>>> x = np.array([1, 2, 3])
>>> y = np.array([[4], [5], [6]])
>>> b = np.broadcast(x, y)
>>> row, col = b.iters
>>> row.next(), col.next()
(1, 4)


numpy.broadcast.shape

  • Array manipulation routines
  • numpy.broadcast
  • index
  • next
  • previous

Previous topic

numpy.broadcast.iters

Next topic

numpy.broadcast.size

numpy.broadcast.shape

broadcast.shape

Shape of broadcasted result.

Examples

>>> x = np.array([1, 2, 3])
>>> y = np.array([[4], [5], [6]])
>>> b = np.broadcast(x, y)
>>> b.shape
(3, 3)


numpy.broadcast.size

  • Array manipulation routines
  • numpy.broadcast
  • index
  • next
  • previous

Previous topic

numpy.broadcast.shape

Next topic

numpy.broadcast.next

numpy.broadcast.size

broadcast.size

Total size of broadcasted result.

Examples

>>> x = np.array([1, 2, 3])
>>> y = np.array([[4], [5], [6]])
>>> b = np.broadcast(x, y)
>>> b.size
9


numpy.broadcast.next

  • Array manipulation routines
  • numpy.broadcast
  • index
  • next
  • previous

Previous topic

numpy.broadcast.size

Next topic

numpy.broadcast.reset

numpy.broadcast.next

broadcast.next

x.next() -> the next value, or raise StopIteration


numpy.broadcast.reset

  • Array manipulation routines
  • numpy.broadcast
  • index
  • next
  • previous

Previous topic

numpy.broadcast.next

Next topic

numpy.broadcast_arrays

numpy.broadcast.reset

broadcast.reset()

Reset the broadcasted result’s iterator(s).

Parameters: None
Returns: None

Examples

>>> x = np.array([1, 2, 3])
>>> y = np.array([[4], [5], [6]]
>>> b = np.broadcast(x, y)
>>> b.index
0
>>> b.next(), b.next(), b.next()
((1, 4), (2, 4), (3, 4))
>>> b.index
3
>>> b.reset()
>>> b.index
0


Masked arrays

  • Array objects
  • next
  • previous

Previous topic

numpy.broadcast.reset

Next topic

The numpy.ma module

Masked arrays

Masked arrays are arrays that may have missing or invalid entries. The numpy.ma module provides a nearly work-alike replacement for numpy that supports data arrays with masks.

  • The numpy.ma module
    • Rationale
    • What is a masked array?
    • The numpy.ma module
  • Using numpy.ma
    • Constructing masked arrays
    • Accessing the data
    • Accessing the mask
    • Accessing only the valid entries
    • Modifying the mask
    • Indexing and slicing
    • Operations on masked arrays
  • Examples
    • Data with a given value representing missing data
    • Filling in the missing data
    • Numerical operations
    • Ignoring extreme values
  • Constants of the numpy.ma module
  • The MaskedArray class
    • Attributes and properties of masked arrays
  • MaskedArray methods
    • Conversion
    • Shape manipulation
    • Item selection and manipulation
    • Pickling and copy
    • Calculations
    • Arithmetic and comparison operations
    • Representation
    • Special methods
    • Specific methods
  • Masked array operations
    • Constants
    • Creation
    • Inspecting the array
    • Manipulating a MaskedArray
    • Operations on masks
    • Conversion operations
    • Masked arrays arithmetics


The numpy.ma module

  • Array objects
  • Masked arrays
  • index
  • next
  • previous

Table Of Contents

  • The numpy.ma module
    • Rationale
    • What is a masked array?
    • The numpy.ma module
  • Using numpy.ma
    • Constructing masked arrays
    • Accessing the data
    • Accessing the mask
    • Accessing only the valid entries
    • Modifying the mask
      • Masking an entry
      • Unmasking an entry
    • Indexing and slicing
    • Operations on masked arrays
  • Examples
    • Data with a given value representing missing data
    • Filling in the missing data
    • Numerical operations
    • Ignoring extreme values

Previous topic

Masked arrays

Next topic

numpy.ma.array

The numpy.ma module

Rationale

Masked arrays are arrays that may have missing or invalid entries. The numpy.ma module provides a nearly work-alike replacement for numpy that supports data arrays with masks.

What is a masked array?

In many circumstances, datasets can be incomplete or tainted by the presence of invalid data. For example, a sensor may have failed to record a data, or recorded an invalid value. The numpy.ma module provides a convenient way to address this issue, by introducing masked arrays.

A masked array is the combination of a standard numpy.ndarray and a mask. A mask is either nomask, indicating that no value of the associated array is invalid, or an array of booleans that determines for each element of the associated array whether the value is valid or not. When an element of the mask is False, the corresponding element of the associated array is valid and is said to be unmasked. When an element of the mask is True, the corresponding element of the associated array is said to be masked (invalid).

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 array:

>>> mx = ma.masked_array(x, mask=[0, 0, 0, 1, 0])

We can now compute the mean of the dataset, without taking the invalid data into account:

>>> mx.mean()
2.75

The numpy.ma module

The main feature of the numpy.ma module is the MaskedArray class, which is a subclass of numpy.ndarray. The class, its attributes and methods are described in more details in the MaskedArray class section.

The numpy.ma module can be used as an addition to numpy:

>>> import numpy as np
>>> import numpy.ma as ma

To create an array with the second element invalid, we would do:

>>> y = ma.array([1, 2, 3], mask = [0, 1, 0])

To create a masked array where all values close to 1.e20 are invalid, we would do:

>>> z = masked_values([1.0, 1.e20, 3.0, 4.0], 1.e20)

For a complete discussion of creation methods for masked arrays please see section Constructing masked arrays.

Using numpy.ma

Constructing masked arrays

There are several ways to construct a masked array.

  • A first possibility is to directly invoke the MaskedArray class.

  • A second possibility is to use the two masked array constructors, array and masked_array.

    array(data[, dtype, copy, order, mask, ...]) | An array class with possibly masked values.
    masked_array | alias of MaskedArray

  • A third option is to take the view of an existing array. In that case, the mask of the view is set to nomask if the array has no named fields, or an array of boolean with the same structure as the array otherwise.

    >>> x = np.array([1, 2, 3])
>>> x.view(ma.MaskedArray)
masked_array(data = [1 2 3],
             mask = False,
       fill_value = 999999)
>>> x = np.array([(1, 1.), (2, 2.)], dtype=[('a',int), ('b', float)])
>>> x.view(ma.MaskedArray)
masked_array(data = [(1, 1.0) (2, 2.0)],
             mask = [(False, False) (False, False)],
       fill_value = (999999, 1e+20),
            dtype = [('a', '<i4'), ('b', '<f8')])

  • Yet another possibility is to use any of the following functions:

    asarray(a[, dtype, order]) | Convert the input to a masked array of the given data-type.
    asanyarray(a[, dtype]) | Convert the input to a masked array, conserving subclasses.
    fix_invalid(a[, mask, copy, fill_value]) | Return input with invalid data masked and replaced by a fill value.
    masked_equal(x, value[, copy]) | Mask an array where equal to a given value.
    masked_greater(x, value[, copy]) | Mask an array where greater than a given value.
    masked_greater_equal(x, value[, copy]) | Mask an array where greater than or equal to a given value.
    masked_inside(x, v1, v2[, copy]) | Mask an array inside a given interval.
    masked_invalid(a[, copy]) | Mask an array where invalid values occur (NaNs or infs).
    masked_less(x, value[, copy]) | Mask an array where less than a given value.
    masked_less_equal(x, value[, copy]) | Mask an array where less than or equal to a given value.
    masked_not_equal(x, value[, copy]) | Mask an array where not equal to a given value.
    masked_object(x, value[, copy, shrink]) | Mask the array x where the data are exactly equal to value.
    masked_outside(x, v1, v2[, copy]) | Mask an array outside a given interval.
    masked_values(x, value[, rtol, atol, copy, ...]) | Mask using floating point equality.
    masked_where(condition, a[, copy]) | Mask an array where a condition is met.

Accessing the data

The underlying data of a masked array can be accessed in several ways:

  • through the data attribute. The output is a view of the array as a numpy.ndarray or one of its subclasses, depending on the type of the underlying data at the masked array creation.
  • through the __array__ method. The output is then a numpy.ndarray.
  • by directly taking a view of the masked array as a numpy.ndarray or one of its subclass (which is actually what using the data attribute does).
  • by using the getdata function.

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 filled method.

Accessing the mask

The mask of a masked array is accessible through its mask attribute. We must keep in mind that a True entry in the mask indicates an invalid data.

Another possibility is to use the getmask and getmaskarray functions. getmask(x) outputs the mask of x if x is a masked array, and the special value nomask otherwise. getmaskarray(x) outputs the mask of x if x is a masked array. If x has no invalid entry or is not a masked array, the function outputs a boolean array of False with as many elements as x.

Accessing only the valid entries

To retrieve only the valid entries, we can use the inverse of the mask as an index. The inverse of the mask can be calculated with the numpy.logical_not function or simply with the ~ operator:

>>> x = ma.array([[1, 2], [3, 4]], mask=[[0, 1], [1, 0]])
>>> x[~x.mask]
masked_array(data = [1 4],
             mask = [False False],
       fill_value = 999999)

Another way to retrieve the valid data is to use the compressed method, which returns a one-dimensional ndarray (or one of its subclasses, depending on the value of the baseclass attribute):

>>> x.compressed()
array([1, 4])

Note that the output of compressed is always 1D.

Modifying the mask

Masking an entry

The recommended way to mark one or several specific entries of a masked array as invalid is to assign the special value masked to them:

>>> x = ma.array([1, 2, 3])
>>> x[0] = ma.masked
>>> x
masked_array(data = [-- 2 3],
             mask = [ True False False],
       fill_value = 999999)
>>> y = ma.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> y[(0, 1, 2), (1, 2, 0)] = ma.masked
>>> y
masked_array(data =
 [[1 -- 3]
  [4 5 --]
  [-- 8 9]],
             mask =
 [[False  True False]
  [False False  True]
  [ True False False]],
       fill_value = 999999)
>>> z = ma.array([1, 2, 3, 4])
>>> z[:-2] = ma.masked
>>> z
masked_array(data = [-- -- 3 4],
             mask = [ True  True False False],
       fill_value = 999999)

A second possibility is to modify the mask directly, but this usage is discouraged.

Note

When creating a new masked array with a simple, non-structured datatype, the mask is initially set to the special value nomask, that corresponds roughly to the boolean False. Trying to set an element of nomask will fail with a TypeError exception, as a boolean does not support item assignment.

All the entries of an array can be masked at once by assigning True to the mask:

>>> x = ma.array([1, 2, 3], mask=[0, 0, 1])
>>> x.mask = True
>>> x
masked_array(data = [-- -- --],
             mask = [ True  True  True],
       fill_value = 999999)

Finally, specific entries can be masked and/or unmasked by assigning to the mask a sequence of booleans:

>>> x = ma.array([1, 2, 3])
>>> x.mask = [0, 1, 0]
>>> x
masked_array(data = [1 -- 3],
             mask = [False  True False],
       fill_value = 999999)

Unmasking an entry

To unmask one or several specific entries, we can just assign one or several new valid values to them:

>>> x = ma.array([1, 2, 3], mask=[0, 0, 1])
>>> x
masked_array(data = [1 2 --],
             mask = [False False  True],
       fill_value = 999999)
>>> x[-1] = 5
>>> x
masked_array(data = [1 2 5],
             mask = [False False False],
       fill_value = 999999)

Note

Unmasking an entry by direct assignment will silently fail if the masked array has a hard mask, as shown by the 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 soften_mask method before the allocation. It can be re-hardened with 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],
       fill_value = 999999)
>>> x[-1] = 5
>>> x
masked_array(data = [1 2 --],
             mask = [False False  True],
       fill_value = 999999)
>>> x.soften_mask()
>>> x[-1] = 5
>>> x
masked_array(data = [1 2 5],
             mask = [False False  False],
       fill_value = 999999)
>>> x.harden_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 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 = ma.nomask
>>> x
masked_array(data = [1 2 3],
             mask = [False False False],
       fill_value = 999999)

Indexing and slicing

As a MaskedArray is a subclass of numpy.ndarray, it inherits its mechanisms for indexing and slicing.

When accessing a single entry of a masked array with no named fields, the output is either a scalar (if the corresponding entry of the mask is False) or the special value masked (if the corresponding entry of the mask is True):

>>> x = ma.array([1, 2, 3], mask=[0, 0, 1])
>>> x[0]
1
>>> x[-1]
masked_array(data = --,
             mask = True,
       fill_value = 1e+20)
>>> x[-1] is ma.masked
True

If the masked array has named fields, accessing a single entry returns a numpy.void object if none of the fields are masked, or a 0d masked array with the same dtype as the initial array if at least one of the fields is masked.

>>> y = ma.masked_array([(1,2), (3, 4)],
...                mask=[(0, 0), (0, 1)],
...               dtype=[('a', int), ('b', int)])
>>> y[0]
(1, 2)
>>> y[-1]
masked_array(data = (3, --),
             mask = (False, True),
       fill_value = (999999, 999999),
            dtype = [('a', '<i4'), ('b', '<i4')])

When accessing a slice, the output is a masked array whose data attribute is a view of the original data, and whose mask is either nomask (if there was no invalid entries in the original array) or a copy of the corresponding slice of the original mask. The copy is required to avoid propagation of any modification of the mask to the original.

>>> x = ma.array([1, 2, 3, 4, 5], mask=[0, 1, 0, 0, 1])
>>> mx = x[:3]
>>> mx
masked_array(data = [1 -- 3],
             mask = [False  True False],
       fill_value = 999999)
>>> mx[1] = -1
>>> mx
masked_array(data = [1 -1 3],
             mask = [False  True False],
       fill_value = 999999)
>>> x.mask
array([False,  True, False, False,  True], dtype=bool)
>>> x.data
array([ 1, -1,  3,  4,  5])

Accessing a field of a masked array with structured datatype returns a MaskedArray.

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 data entries should be the same before and after the operation.

Warning

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 numpy.ma module comes with a specific implementation of most ufuncs. Unary and binary functions that have a validity domain (such as log or divide) return the masked constant whenever the input is masked or falls outside the validity domain:

>>> ma.log([-1, 0, 1, 2])
masked_array(data = [-- -- 0.0 0.69314718056],
             mask = [ True  True False False],
       fill_value = 1e+20)

Masked arrays also support standard numpy ufuncs. The output is then a masked array. The result of a unary ufunc is masked wherever the input is masked. The result of a binary ufunc is masked wherever any of the input is masked. If the ufunc also returns the optional context output (a 3-element tuple containing the name of the ufunc, its arguments and its domain), the context is processed and entries of the output masked array are masked wherever the corresponding input fall outside the validity domain:

>>> x = ma.array([-1, 1, 0, 2, 3], mask=[0, 0, 0, 0, 1])
>>> np.log(x)
masked_array(data = [-- -- 0.0 0.69314718056 --],
             mask = [ True  True False False  True],
       fill_value = 1e+20)

Examples

Data with a given value representing missing data

Let’s consider a list of elements, x, where values of -9999. represent missing data. We wish to compute the average value of the data and the vector of anomalies (deviations from the average):

>>> import numpy.ma as ma
>>> x = [0.,1.,-9999.,3.,4.]
>>> mx = ma.masked_values (x, -9999.)
>>> print mx.mean()
2.0
>>> print mx - mx.mean()
[-2.0 -1.0 -- 1.0 2.0]
>>> print mx.anom()
[-2.0 -1.0 -- 1.0 2.0]

Filling in the missing data

Suppose now that we wish to print that same data, but with the missing values replaced by the average value.

>>> print mx.filled(mx.mean())
[ 0.  1.  2.  3.  4.]

Numerical operations

Numerical operations can be easily performed without worrying about missing values, dividing by zero, square roots of negative numbers, etc.:

>>> import numpy as np, numpy.ma as ma
>>> x = ma.array([1., -1., 3., 4., 5., 6.], mask=[0,0,0,0,1,0])
>>> y = ma.array([1., 2., 0., 4., 5., 6.], mask=[0,0,0,0,0,1])
>>> print np.sqrt(x/y)
[1.0 -- -- 1.0 -- --]

Four values of the output are invalid: the first one comes from taking the square root of a negative number, the second from the division by zero, and the last two where the inputs were masked.

Ignoring extreme values

Let’s consider an array d of random floats between 0 and 1. We wish to compute the average of the values of d while ignoring any data outside the range [0.1, 0.9]:

>>> print ma.masked_outside(d, 0.1, 0.9).mean()


numpy.ma.array

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_array

Next topic

numpy.ma.copy

numpy.ma.array

numpy.ma.array(data, dtype=None, copy=False, order=False, mask=False, fill_value=None, keep_mask=True, hard_mask=False, shrink=True, subok=True, ndmin=0) [source]

An array class with possibly masked values.

Masked values of True exclude the corresponding element from any computation.

Construction:

x = MaskedArray(data, mask=nomask, dtype=None,
                copy=False, subok=True, ndmin=0, fill_value=None,
                keep_mask=True, hard_mask=None, shrink=True)
Parameters:

data : array_like

Input data.

mask : sequence, optional

Mask. Must be convertible to an array of booleans with the same shape as data. True indicates a masked (i.e. invalid) data.

dtype : dtype, optional

Data type of the output. If dtype is None, the type of the data argument (data.dtype) is used. If dtype is not None and different from data.dtype, a copy is performed.

copy : bool, optional

Whether to copy the input data (True), or to use a reference instead. Default is False.

subok : bool, optional

Whether to return a subclass of MaskedArray if possible (True) or a plain MaskedArray. Default is True.

ndmin : int, optional

Minimum number of dimensions. Default is 0.

fill_value : scalar, optional

Value used to fill in the masked values when necessary. If None, a default based on the data-type is used.

keep_mask : bool, optional

Whether to combine mask with the mask of the input data, if any (True), or to use only mask for the output (False). Default is True.

hard_mask : bool, optional

Whether to use a hard mask or not. With a hard mask, masked values cannot be unmasked. Default is False.

shrink : bool, optional

Whether to force compression of an empty mask. Default is True.


numpy.ma.masked_array

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskType

Next topic

numpy.ma.array

numpy.ma.masked_array

numpy.ma.masked_array [source]

alias of MaskedArray


numpy.ma.asarray

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.unshare_mask

Next topic

numpy.ma.asanyarray

numpy.ma.asarray

numpy.ma.asarray(a, dtype=None, order=None) [source]

Convert the input to a masked array of the given data-type.

No copy is performed if the input is already an ndarray. If a is a subclass of MaskedArray, a base class MaskedArray is returned.

Parameters:

a : array_like

Input data, in any form that can be converted to a masked array. This includes lists, lists of tuples, tuples, tuples of tuples, tuples of lists, ndarrays and masked arrays.

dtype : dtype, optional

By default, the data-type is inferred from the input data.

order : {‘C’, ‘F’}, optional

Whether to use row-major (‘C’) or column-major (‘FORTRAN’) memory representation. Default is ‘C’.
Returns:

out : MaskedArray

Masked array interpretation of a.

See also

asanyarray
Similar to asarray, but conserves subclasses.

Examples

>>> x = np.arange(10.).reshape(2, 5)
>>> x
array([[ 0.,  1.,  2.,  3.,  4.],
       [ 5.,  6.,  7.,  8.,  9.]])
>>> np.ma.asarray(x)
masked_array(data =
 [[ 0.  1.  2.  3.  4.]
 [ 5.  6.  7.  8.  9.]],
             mask =
 False,
       fill_value = 1e+20)
>>> type(np.ma.asarray(x))
<class 'numpy.ma.core.MaskedArray'>


numpy.ma.asanyarray

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.asarray

Next topic

numpy.ma.fix_invalid

numpy.ma.asanyarray

numpy.ma.asanyarray(a, dtype=None) [source]

Convert the input to a masked array, conserving subclasses.

If a is a subclass of MaskedArray, its class is conserved. No copy is performed if the input is already an ndarray.

Parameters:

a : array_like

Input data, in any form that can be converted to an array.

dtype : dtype, optional

By default, the data-type is inferred from the input data.

order : {‘C’, ‘F’}, optional

Whether to use row-major (‘C’) or column-major (‘FORTRAN’) memory representation. Default is ‘C’.
Returns:

out : MaskedArray

MaskedArray interpretation of a.

See also

asarray
Similar to asanyarray, but does not conserve subclass.

Examples

>>> x = np.arange(10.).reshape(2, 5)
>>> x
array([[ 0.,  1.,  2.,  3.,  4.],
       [ 5.,  6.,  7.,  8.,  9.]])
>>> np.ma.asanyarray(x)
masked_array(data =
 [[ 0.  1.  2.  3.  4.]
 [ 5.  6.  7.  8.  9.]],
             mask =
 False,
       fill_value = 1e+20)
>>> type(np.ma.asanyarray(x))
<class 'numpy.ma.core.MaskedArray'>


numpy.ma.fix_invalid

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.asanyarray

Next topic

numpy.ma.masked_equal

numpy.ma.fix_invalid

numpy.ma.fix_invalid(a, mask=False, copy=True, fill_value=None) [source]

Return input with invalid data masked and replaced by a fill value.

Invalid data means values of nan, inf, etc.

Parameters:

a : array_like

Input array, a (subclass of) ndarray.

copy : bool, optional

Whether to use a copy of a (True) or to fix a in place (False). Default is True.

fill_value : scalar, optional

Value used for fixing invalid data. Default is None, in which case the a.fill_value is used.
Returns:

b : MaskedArray

The input array with invalid entries fixed.

Notes

A copy is performed by default.

Examples

>>> x = np.ma.array([1., -1, np.nan, np.inf], mask=[1] + [0]*3)
>>> x
masked_array(data = [-- -1.0 nan inf],
             mask = [ True False False False],
       fill_value = 1e+20)
>>> np.ma.fix_invalid(x)
masked_array(data = [-- -1.0 -- --],
             mask = [ True False  True  True],
       fill_value = 1e+20)

>>> fixed = np.ma.fix_invalid(x)
>>> fixed.data
array([  1.00000000e+00,  -1.00000000e+00,   1.00000000e+20,
         1.00000000e+20])
>>> x.data
array([  1.,  -1.,  NaN,  Inf])


numpy.ma.masked_equal

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.fix_invalid

Next topic

numpy.ma.masked_greater

numpy.ma.masked_equal

numpy.ma.masked_equal(x, value, copy=True) [source]

Mask an array where equal to a given value.

This function is a shortcut to masked_where, with condition = (x == value). For floating point arrays, consider using masked_values(x, value).

See also

masked_where
Mask where a condition is met.
masked_values
Mask using floating point equality.

Examples

>>> import numpy.ma as ma
>>> a = np.arange(4)
>>> a
array([0, 1, 2, 3])
>>> ma.masked_equal(a, 2)
masked_array(data = [0 1 -- 3],
      mask = [False False  True False],
      fill_value=999999)


numpy.ma.masked_greater

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_equal

Next topic

numpy.ma.masked_greater_equal

numpy.ma.masked_greater

numpy.ma.masked_greater(x, value, copy=True) [source]

Mask an array where greater than a given value.

This function is a shortcut to masked_where, with condition = (x > value).

See also

masked_where
Mask where a condition is met.

Examples

>>> import numpy.ma as ma
>>> a = np.arange(4)
>>> a
array([0, 1, 2, 3])
>>> ma.masked_greater(a, 2)
masked_array(data = [0 1 2 --],
      mask = [False False False  True],
      fill_value=999999)


numpy.ma.masked_greater_equal

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_greater

Next topic

numpy.ma.masked_inside

numpy.ma.masked_greater_equal

numpy.ma.masked_greater_equal(x, value, copy=True) [source]

Mask an array where greater than or equal to a given value.

This function is a shortcut to masked_where, with condition = (x >= value).

See also

masked_where
Mask where a condition is met.

Examples

>>> import numpy.ma as ma
>>> a = np.arange(4)
>>> a
array([0, 1, 2, 3])
>>> ma.masked_greater_equal(a, 2)
masked_array(data = [0 1 -- --],
      mask = [False False  True  True],
      fill_value=999999)


numpy.ma.masked_inside

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_greater_equal

Next topic

numpy.ma.masked_invalid

numpy.ma.masked_inside

numpy.ma.masked_inside(x, v1, v2, copy=True) [source]

Mask an array inside a given interval.

Shortcut to masked_where, where condition is True for x inside the interval [v1,v2] (v1 <= x <= v2). The boundaries v1 and v2 can be given in either order.

See also

masked_where
Mask where a condition is met.

Notes

The array x is prefilled with its filling value.

Examples

>>> import numpy.ma as ma
>>> x = [0.31, 1.2, 0.01, 0.2, -0.4, -1.1]
>>> ma.masked_inside(x, -0.3, 0.3)
masked_array(data = [0.31 1.2 -- -- -0.4 -1.1],
      mask = [False False  True  True False False],
      fill_value=1e+20)

The order of v1 and v2 doesn’t matter.

>>> ma.masked_inside(x, 0.3, -0.3)
masked_array(data = [0.31 1.2 -- -- -0.4 -1.1],
      mask = [False False  True  True False False],
      fill_value=1e+20)


numpy.ma.masked_invalid

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_inside

Next topic

numpy.ma.masked_less

numpy.ma.masked_invalid

numpy.ma.masked_invalid(a, copy=True) [source]

Mask an array where invalid values occur (NaNs or infs).

This function is a shortcut to masked_where, with condition = ~(np.isfinite(a)). Any pre-existing mask is conserved. Only applies to arrays with a dtype where NaNs or infs make sense (i.e. floating point types), but accepts any array_like object.

See also

masked_where
Mask where a condition is met.

Examples

>>> import numpy.ma as ma
>>> a = np.arange(5, dtype=np.float)
>>> a[2] = np.NaN
>>> a[3] = np.PINF
>>> a
array([  0.,   1.,  NaN,  Inf,   4.])
>>> ma.masked_invalid(a)
masked_array(data = [0.0 1.0 -- -- 4.0],
      mask = [False False  True  True False],
      fill_value=1e+20)


numpy.ma.masked_less

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_invalid

Next topic

numpy.ma.masked_less_equal

numpy.ma.masked_less

numpy.ma.masked_less(x, value, copy=True) [source]

Mask an array where less than a given value.

This function is a shortcut to masked_where, with condition = (x < value).

See also

masked_where
Mask where a condition is met.

Examples

>>> import numpy.ma as ma
>>> a = np.arange(4)
>>> a
array([0, 1, 2, 3])
>>> ma.masked_less(a, 2)
masked_array(data = [-- -- 2 3],
      mask = [ True  True False False],
      fill_value=999999)


numpy.ma.masked_less_equal

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_less

Next topic

numpy.ma.masked_not_equal

numpy.ma.masked_less_equal

numpy.ma.masked_less_equal(x, value, copy=True) [source]

Mask an array where less than or equal to a given value.

This function is a shortcut to masked_where, with condition = (x <= value).

See also

masked_where
Mask where a condition is met.

Examples

>>> import numpy.ma as ma
>>> a = np.arange(4)
>>> a
array([0, 1, 2, 3])
>>> ma.masked_less_equal(a, 2)
masked_array(data = [-- -- -- 3],
      mask = [ True  True  True False],
      fill_value=999999)


numpy.ma.masked_not_equal

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_less_equal

Next topic

numpy.ma.masked_object

numpy.ma.masked_not_equal

numpy.ma.masked_not_equal(x, value, copy=True) [source]

Mask an array where not equal to a given value.

This function is a shortcut to masked_where, with condition = (x != value).

See also

masked_where
Mask where a condition is met.

Examples

>>> import numpy.ma as ma
>>> a = np.arange(4)
>>> a
array([0, 1, 2, 3])
>>> ma.masked_not_equal(a, 2)
masked_array(data = [-- -- 2 --],
      mask = [ True  True False  True],
      fill_value=999999)


numpy.ma.masked_object

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_not_equal

Next topic

numpy.ma.masked_outside

numpy.ma.masked_object

numpy.ma.masked_object(x, value, copy=True, shrink=True) [source]

Mask the array x where the data are exactly equal to value.

This function is similar to masked_values, but only suitable for object arrays: for floating point, use masked_values instead.

Parameters:

x : array_like

Array to mask

value : object

Comparison value

copy : {True, False}, optional

Whether to return a copy of x.

shrink : {True, False}, optional

Whether to collapse a mask full of False to nomask
Returns:

result : MaskedArray

The result of masking x where equal to value.

See also

masked_where
Mask where a condition is met.
masked_equal
Mask where equal to a given value (integers).
masked_values
Mask using floating point equality.

Examples

>>> import numpy.ma as ma
>>> food = np.array(['green_eggs', 'ham'], dtype=object)
>>> # don't eat spoiled food
>>> eat = ma.masked_object(food, 'green_eggs')
>>> print eat
[-- ham]
>>> # plain ol` ham is boring
>>> fresh_food = np.array(['cheese', 'ham', 'pineapple'], dtype=object)
>>> eat = ma.masked_object(fresh_food, 'green_eggs')
>>> print eat
[cheese ham pineapple]

Note that mask is set to nomask if possible.

>>> eat
masked_array(data = [cheese ham pineapple],
      mask = False,
      fill_value=?)


numpy.ma.masked_outside

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_object

Next topic

numpy.ma.masked_values

numpy.ma.masked_outside

numpy.ma.masked_outside(x, v1, v2, copy=True) [source]

Mask an array outside a given interval.

Shortcut to masked_where, where condition is True for x outside the interval [v1,v2] (x < v1)|(x > v2). The boundaries v1 and v2 can be given in either order.

See also

masked_where
Mask where a condition is met.

Notes

The array x is prefilled with its filling value.

Examples

>>> import numpy.ma as ma
>>> x = [0.31, 1.2, 0.01, 0.2, -0.4, -1.1]
>>> ma.masked_outside(x, -0.3, 0.3)
masked_array(data = [-- -- 0.01 0.2 -- --],
      mask = [ True  True False False  True  True],
      fill_value=1e+20)

The order of v1 and v2 doesn’t matter.

>>> ma.masked_outside(x, 0.3, -0.3)
masked_array(data = [-- -- 0.01 0.2 -- --],
      mask = [ True  True False False  True  True],
      fill_value=1e+20)


numpy.ma.masked_values

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_outside

Next topic

numpy.ma.masked_where

numpy.ma.masked_values

numpy.ma.masked_values(x, value, rtol=1e-05, atol=1e-08, copy=True, shrink=True) [source]

Mask using floating point equality.

Return a MaskedArray, masked where the data in array x are approximately equal to value, i.e. where the following condition is True

(abs(x - value) <= atol+rtol*abs(value))

The fill_value is set to value and the mask is set to nomask if possible. For integers, consider using masked_equal.

Parameters:

x : array_like

Array to mask.

value : float

Masking value.

rtol : float, optional

Tolerance parameter.

atol : float, optional

Tolerance parameter (1e-8).

copy : bool, optional

Whether to return a copy of x.

shrink : bool, optional

Whether to collapse a mask full of False to nomask.
Returns:

result : MaskedArray

The result of masking x where approximately equal to value.

See also

masked_where
Mask where a condition is met.
masked_equal
Mask where equal to a given value (integers).

Examples

>>> import numpy.ma as ma
>>> x = np.array([1, 1.1, 2, 1.1, 3])
>>> ma.masked_values(x, 1.1)
masked_array(data = [1.0 -- 2.0 -- 3.0],
      mask = [False  True False  True False],
      fill_value=1.1)

Note that mask is set to nomask if possible.

>>> ma.masked_values(x, 1.5)
masked_array(data = [ 1.   1.1  2.   1.1  3. ],
      mask = False,
      fill_value=1.5)

For integers, the fill value will be different in general to the result of masked_equal.

>>> x = np.arange(5)
>>> x
array([0, 1, 2, 3, 4])
>>> ma.masked_values(x, 2)
masked_array(data = [0 1 -- 3 4],
      mask = [False False  True False False],
      fill_value=2)
>>> ma.masked_equal(x, 2)
masked_array(data = [0 1 -- 3 4],
      mask = [False False  True False False],
      fill_value=999999)


numpy.ma.masked_where

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_values

Next topic

numpy.ma.compress_cols

numpy.ma.masked_where

numpy.ma.masked_where(condition, a, copy=True) [source]

Mask an array where a condition is met.

Return a as an array masked where condition is True. Any masked values of a or condition are also masked in the output.

Parameters:

condition : array_like

Masking condition. When condition tests floating point values for equality, consider using masked_values instead.

a : array_like

Array to mask.

copy : bool

If True (default) make a copy of a in the result. If False modify a in place and return a view.
Returns:

result : MaskedArray

The result of masking a where condition is True.

See also

masked_values
Mask using floating point equality.
masked_equal
Mask where equal to a given value.
masked_not_equal
Mask where not equal to a given value.
masked_less_equal
Mask where less than or equal to a given value.
masked_greater_equal
Mask where greater than or equal to a given value.
masked_less
Mask where less than a given value.
masked_greater
Mask where greater than a given value.
masked_inside
Mask inside a given interval.
masked_outside
Mask outside a given interval.
masked_invalid
Mask invalid values (NaNs or infs).

Examples

>>> import numpy.ma as ma
>>> a = np.arange(4)
>>> a
array([0, 1, 2, 3])
>>> ma.masked_where(a <= 2, a)
masked_array(data = [-- -- -- 3],
      mask = [ True  True  True False],
      fill_value=999999)

Mask array b conditional on a.

>>> b = ['a', 'b', 'c', 'd']
>>> ma.masked_where(a == 2, b)
masked_array(data = [a b -- d],
      mask = [False False  True False],
      fill_value=N/A)

Effect of the copy argument.

>>> c = ma.masked_where(a <= 2, a)
>>> c
masked_array(data = [-- -- -- 3],
      mask = [ True  True  True False],
      fill_value=999999)
>>> c[0] = 99
>>> c
masked_array(data = [99 -- -- 3],
      mask = [False  True  True False],
      fill_value=999999)
>>> a
array([0, 1, 2, 3])
>>> c = ma.masked_where(a <= 2, a, copy=False)
>>> c[0] = 99
>>> c
masked_array(data = [99 -- -- 3],
      mask = [False  True  True False],
      fill_value=999999)
>>> a
array([99,  1,  2,  3])

When condition or a contain masked values.

>>> a = np.arange(4)
>>> a = ma.masked_where(a == 2, a)
>>> a
masked_array(data = [0 1 -- 3],
      mask = [False False  True False],
      fill_value=999999)
>>> b = np.arange(4)
>>> b = ma.masked_where(b == 0, b)
>>> b
masked_array(data = [-- 1 2 3],
      mask = [ True False False False],
      fill_value=999999)
>>> ma.masked_where(a == 3, b)
masked_array(data = [-- 1 -- --],
      mask = [ True False  True  True],
      fill_value=999999)


Constants of the numpy.ma module

  • Array objects
  • Masked arrays
  • index
  • next
  • previous

Table Of Contents

  • Constants of the numpy.ma module
  • The MaskedArray class
    • Attributes and properties of masked arrays
  • MaskedArray methods
    • Conversion
    • Shape manipulation
    • Item selection and manipulation
    • Pickling and copy
    • Calculations
    • Arithmetic and comparison operations
      • Comparison operators:
      • Truth value of an array (bool):
      • Arithmetic:
      • Arithmetic, in-place:
    • Representation
    • Special methods
    • Specific methods
      • Handling the mask
      • Handling the fill_value
      • Counting the missing elements

Previous topic

numpy.ma.masked_where

Next topic

numpy.ma.MaskedArray.base

Constants of the numpy.ma module

In addition to the MaskedArray class, the numpy.ma module defines several constants.

numpy.ma.masked

The masked constant is a special case of MaskedArray, with a float datatype and a null shape. It is used to test whether a specific entry of a masked array is masked, or to mask one or several entries of a masked array:

>>> x = ma.array([1, 2, 3], mask=[0, 1, 0])
>>> x[1] is ma.masked
True
>>> x[-1] = ma.masked
>>> x
masked_array(data = [1 -- --],
             mask = [False  True  True],
       fill_value = 999999)
numpy.ma.nomask

Value indicating that a masked array has no invalid entry. nomask is used internally to speed up computations when the mask is not needed.

numpy.ma.masked_print_options

String used in lieu of missing data when a masked array is printed. By default, this string is '--'.

The MaskedArray class

class numpy.ma.MaskedArray [source]
A subclass of ndarray designed to manipulate numerical arrays with missing data.

An instance of MaskedArray can be thought as the combination of several elements:

  • The data, as a regular numpy.ndarray of any shape or datatype (the data).
  • A boolean mask with the same shape as the data, where a True value indicates that the corresponding element of the data is invalid. The special value nomask is also acceptable for arrays without named fields, and indicates that no data is invalid.
  • A fill_value, a value that may be used to replace the invalid entries in order to return a standard numpy.ndarray.

Attributes and properties of masked arrays

See also

Array Attributes

MaskedArray.data

Returns the underlying data, as a view of the masked array. If the underlying data is a subclass of numpy.ndarray, it is returned as such.

>>> x = ma.array(np.matrix([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])
>>> x.data
matrix([[1, 2],
        [3, 4]])

The type of the data can be accessed through the baseclass attribute.

MaskedArray.mask

Returns the underlying mask, as an array with the same shape and structure as the data, but where all fields are atomically booleans. A value of True indicates an invalid entry.

MaskedArray.recordmask

Returns the mask of the array if it has no named fields. For structured arrays, returns a ndarray of booleans where entries are True if all the fields are masked, False otherwise:

>>> x = ma.array([(1, 1), (2, 2), (3, 3), (4, 4), (5, 5)],
...         mask=[(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)],
...        dtype=[('a', int), ('b', int)])
>>> x.recordmask
array([False, False,  True, False, False], dtype=bool)
MaskedArray.fill_value

Returns the value used to fill the invalid entries of a masked array. The value is either a scalar (if the masked array has no named fields), or a 0-D ndarray with the same dtype as the masked array if it has named fields.

The default filling value depends on the datatype of the array:

datatype | default
bool | True
int | 999999
float | 1.e20
complex | 1.e20+0j
object ‘?’
string | ‘N/A’
MaskedArray.baseclass

Returns the class of the underlying data.

>>> x =  ma.array(np.matrix([[1, 2], [3, 4]]), mask=[[0, 0], [1, 0]])
>>> x.baseclass
<class 'numpy.matrixlib.defmatrix.matrix'>
MaskedArray.sharedmask

Returns whether the mask of the array is shared between several masked arrays. If this is the case, any modification to the mask of one array will be propagated to the others.

MaskedArray.hardmask

Returns whether the mask is hard (True) or soft (False). When the mask is hard, masked entries cannot be unmasked.

As MaskedArray is a subclass of ndarray, a masked array also inherits all the attributes and properties of a ndarray instance.

MaskedArray.base | Base object if memory is from some other object.
MaskedArray.ctypes | An object to simplify the interaction of the array with the ctypes module.
MaskedArray.dtype | Data-type of the array’s elements.
MaskedArray.flags | Information about the memory layout of the array.
MaskedArray.itemsize | Length of one array element in bytes.
MaskedArray.nbytes | Total bytes consumed by the elements of the array.
MaskedArray.ndim | Number of array dimensions.
MaskedArray.shape | Tuple of array dimensions.
MaskedArray.size | Number of elements in the array.
MaskedArray.strides | Tuple of bytes to step in each dimension when traversing an array.
MaskedArray.imag | Imaginary part.
MaskedArray.real | Real part
MaskedArray.flat | Flat version of the array.
MaskedArray.__array_priority__ |

MaskedArray methods

See also

Array methods

Conversion

MaskedArray.__float__() | Convert to float.
MaskedArray.__hex__() <==> hex(x) |
MaskedArray.__int__() | Convert to int.
MaskedArray.__long__() <==> long(x) |
MaskedArray.__oct__() <==> oct(x) |
MaskedArray.view([dtype, type]) | New view of array with the same data.
MaskedArray.astype(newtype) | Returns a copy of the MaskedArray cast to given newtype.
MaskedArray.byteswap(inplace) | Swap the bytes of the array elements
MaskedArray.compressed() | Return all the non-masked data as a 1-D array.
MaskedArray.filled([fill_value]) | Return a copy of self, with masked values filled with a given value.
MaskedArray.tofile(fid[, sep, format]) | Save a masked array to a file in binary format.
MaskedArray.toflex() | Transforms a masked array into a flexible-type array.
MaskedArray.tolist([fill_value]) | Return the data portion of the masked array as a hierarchical Python list.
MaskedArray.torecords() | Transforms a masked array into a flexible-type array.
MaskedArray.tostring([fill_value, order]) | This function is a compatibility alias for tobytes.
MaskedArray.tobytes([fill_value, order]) | Return the array data as a string containing the raw bytes in the array.

Shape manipulation

For reshape, resize, and transpose, the single tuple argument may be replaced with n integers which will be interpreted as an n-tuple.

MaskedArray.flatten([order]) | Return a copy of the array collapsed into one dimension.
MaskedArray.ravel() | Returns a 1D version of self, as a view.
MaskedArray.reshape(*s, **kwargs) | Give a new shape to the array without changing its data.
MaskedArray.resize(newshape[, refcheck, order]) |
MaskedArray.squeeze([axis]) | Remove single-dimensional entries from the shape of a.
MaskedArray.swapaxes(axis1, axis2) | Return a view of the array with axis1 and axis2 interchanged.
MaskedArray.transpose(*axes) | Returns a view of the array with axes transposed.
MaskedArray.T |

Item selection and manipulation

For array methods that take an axis keyword, it defaults to None. If axis is None, then the array is treated as a 1-D array. Any other value for axis represents the dimension along which the operation should proceed.

MaskedArray.argmax([axis, fill_value, out]) | Returns array of indices of the maximum values along the given axis.
MaskedArray.argmin([axis, fill_value, out]) | Return array of indices to the minimum values along the given axis.
MaskedArray.argsort([axis, kind, order, ...]) | Return an ndarray of indices that sort the array along the specified axis.
MaskedArray.choose(choices[, out, mode]) | Use an index array to construct a new array from a set of choices.
MaskedArray.compress(condition[, axis, out]) | Return a where condition is True.
MaskedArray.diagonal([offset, axis1, axis2]) | Return specified diagonals.
MaskedArray.fill(value) | Fill the array with a scalar value.
MaskedArray.item(*args) | Copy an element of an array to a standard Python scalar and return it.
MaskedArray.nonzero() | Return the indices of unmasked elements that are not zero.
MaskedArray.put(indices, values[, mode]) | Set storage-indexed locations to corresponding values.
MaskedArray.repeat(repeats[, axis]) | Repeat elements of an array.
MaskedArray.searchsorted(v[, side, sorter]) | Find indices where elements of v should be inserted in a to maintain order.
MaskedArray.sort([axis, kind, order, ...]) | Sort the array, in-place
MaskedArray.take(indices[, axis, out, mode]) |

Pickling and copy

MaskedArray.copy([order]) | Return a copy of the array.
MaskedArray.dump(file) | Dump a pickle of the array to the specified file.
MaskedArray.dumps() | Returns the pickle of the array as a string.

Calculations

MaskedArray.all([axis, out]) | Check if all of the elements of a are true.
MaskedArray.anom([axis, dtype]) | Compute the anomalies (deviations from the arithmetic mean) along the given axis.
MaskedArray.any([axis, out]) | Check if any of the elements of a are true.
MaskedArray.clip(a_min, a_max[, out]) | Return an array whose values are limited to [a_min, a_max].
MaskedArray.conj() | Complex-conjugate all elements.
MaskedArray.conjugate() | Return the complex conjugate, element-wise.
MaskedArray.cumprod([axis, dtype, out]) | Return the cumulative product of the elements along the given axis.
MaskedArray.cumsum([axis, dtype, out]) | Return the cumulative sum of the elements along the given axis.
MaskedArray.max([axis, out, fill_value]) | Return the maximum along a given axis.
MaskedArray.mean([axis, dtype, out]) | Returns the average of the array elements.
MaskedArray.min([axis, out, fill_value]) | Return the minimum along a given axis.
MaskedArray.prod([axis, dtype, out]) | Return the product of the array elements over the given axis.
MaskedArray.product([axis, dtype, out]) | Return the product of the array elements over the given axis.
MaskedArray.ptp([axis, out, fill_value]) | Return (maximum - minimum) along the the given dimension (i.e.
MaskedArray.round([decimals, out]) | Return a with each element rounded to the given number of decimals.
MaskedArray.std([axis, dtype, out, ddof]) | Compute the standard deviation along the specified axis.
MaskedArray.sum([axis, dtype, out]) | Return the sum of the array elements over the given axis.
MaskedArray.trace([offset, axis1, axis2, ...]) | Return the sum along diagonals of the array.
MaskedArray.var([axis, dtype, out, ddof]) | Compute the variance along the specified axis.

Arithmetic and comparison operations

Comparison operators:

MaskedArray.__lt__ | x.__lt__(y) <==> x<y
MaskedArray.__le__ | x.__le__(y) <==> x<=y
MaskedArray.__gt__ | x.__gt__(y) <==> x>y
MaskedArray.__ge__ | x.__ge__(y) <==> x>=y
MaskedArray.__eq__(other) | Check whether other equals self elementwise
MaskedArray.__ne__(other) | Check whether other doesn’t equal self elementwise

Truth value of an array (bool):

MaskedArray.__nonzero__ x.__nonzero__() <==> x != 0

Arithmetic:

MaskedArray.__abs__() <==> abs(x) |
MaskedArray.__add__(other) | Add other to self, and return a new masked array.
MaskedArray.__radd__(other) | Add other to self, and return a new masked array.
MaskedArray.__sub__(other) | Subtract other to self, and return a new masked array.
MaskedArray.__rsub__(other) | Subtract other to self, and return a new masked array.
MaskedArray.__mul__(other) | Multiply other by self, and return a new masked array.
MaskedArray.__rmul__(other) | Multiply other by self, and return a new masked array.
MaskedArray.__div__(other) | Divide other into self, and return a new masked array.
MaskedArray.__rdiv__ | x.__rdiv__(y) <==> y/x
MaskedArray.__truediv__(other) | Divide other into self, and return a new masked array.
MaskedArray.__rtruediv__(other) | Divide other into self, and return a new masked array.
MaskedArray.__floordiv__(other) | Divide other into self, and return a new masked array.
MaskedArray.__rfloordiv__(other) | Divide other into self, and return a new masked array.
MaskedArray.__mod__ | x.__mod__(y) <==> x%y
MaskedArray.__rmod__ | x.__rmod__(y) <==> y%x
MaskedArray.__divmod__(y) <==> divmod(x, y) |
MaskedArray.__rdivmod__(y) <==> divmod(y, x) |
MaskedArray.__pow__(other) | Raise self to the power other, masking the potential NaNs/Infs
MaskedArray.__rpow__(other) | Raise self to the power other, masking the potential NaNs/Infs
MaskedArray.__lshift__ | x.__lshift__(y) <==> x<<y
MaskedArray.__rlshift__ | x.__rlshift__(y) <==> y<<x
MaskedArray.__rshift__ | x.__rshift__(y) <==> x>>y
MaskedArray.__rrshift__ | x.__rrshift__(y) <==> y>>x
MaskedArray.__and__ | x.__and__(y) <==> x&y
MaskedArray.__rand__ | x.__rand__(y) <==> y&x
MaskedArray.__or__ | x.__or__(y) <==> x|y
MaskedArray.__ror__ | x.__ror__(y) <==> y|x
MaskedArray.__xor__ | x.__xor__(y) <==> x^y
MaskedArray.__rxor__ | x.__rxor__(y) <==> y^x

Arithmetic, in-place:

MaskedArray.__iadd__(other) | Add other to self in-place.
MaskedArray.__isub__(other) | Subtract other from self in-place.
MaskedArray.__imul__(other) | Multiply self by other in-place.
MaskedArray.__idiv__(other) | Divide self by other in-place.
MaskedArray.__itruediv__(other) | True divide self by other in-place.
MaskedArray.__ifloordiv__(other) | Floor divide self by other in-place.
MaskedArray.__imod__ | x.__imod__(y) <==> x%=y
MaskedArray.__ipow__(other) | Raise self to the power other, in place.
MaskedArray.__ilshift__ | x.__ilshift__(y) <==> x<<=y
MaskedArray.__irshift__ | x.__irshift__(y) <==> x>>=y
MaskedArray.__iand__ | x.__iand__(y) <==> x&=y
MaskedArray.__ior__ | x.__ior__(y) <==> x|=y
MaskedArray.__ixor__ | x.__ixor__(y) <==> x^=y

Representation

MaskedArray.__repr__() | Literal string representation.
MaskedArray.__str__() | String representation.
MaskedArray.ids() | Return the addresses of the data and mask areas.
MaskedArray.iscontiguous() | Return a boolean indicating whether the data is contiguous.

Special methods

For standard library functions:

MaskedArray.__copy__([order]) | Return a copy of the array.
MaskedArray.__deepcopy__([memo]) |
MaskedArray.__getstate__() | Return the internal state of the masked array, for pickling purposes.
MaskedArray.__reduce__() | Return a 3-tuple for pickling a MaskedArray.
MaskedArray.__setstate__(state) | Restore the internal state of the masked array, for pickling purposes.

Basic customization:

MaskedArray.__new__([data, mask, dtype, ...]) | Create a new masked array from scratch.
MaskedArray.__array__(...) | Returns either a new reference to self if dtype is not given or a new array of provided data type if dtype is different from the current dtype of the array.
MaskedArray.__array_wrap__(obj[, context]) | Special hook for ufuncs.

Container customization: (see Indexing)

MaskedArray.__len__() <==> len(x) |
MaskedArray.__getitem__(indx) | x.__getitem__(y) <==> x[y]
MaskedArray.__setitem__(indx, value) | x.__setitem__(i, y) <==> x[i]=y
MaskedArray.__delitem__ | x.__delitem__(y) <==> del x[y]
MaskedArray.__getslice__(i, j) | x.__getslice__(i, j) <==> x[i:j]
MaskedArray.__setslice__(i, j, value) | x.__setslice__(i, j, value) <==> x[i:j]=value
MaskedArray.__contains__ | x.__contains__(y) <==> y in x

Specific methods

Handling the mask

The following methods can be used to access information about the mask or to manipulate the mask.

MaskedArray.__setmask__(mask[, copy]) | Set the mask.
MaskedArray.harden_mask() | Force the mask to hard.
MaskedArray.soften_mask() | Force the mask to soft.
MaskedArray.unshare_mask() | Copy the mask and set the sharedmask flag to False.
MaskedArray.shrink_mask() | Reduce a mask to nomask when possible.

Handling the fill_value

MaskedArray.get_fill_value() | Return the filling value of the masked array.
MaskedArray.set_fill_value([value]) | Set the filling value of the masked array.

Counting the missing elements

MaskedArray.count([axis]) Count the non-masked elements of the array along the given axis.


numpy.ma.MaskedArray.base

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.count

Next topic

numpy.ma.MaskedArray.ctypes

numpy.ma.MaskedArray.base

MaskedArray.base

Base object if memory is from some other object.

Examples

The base of an array that owns its memory is None:

>>> x = np.array([1,2,3,4])
>>> x.base is None
True

Slicing creates a view, whose memory is shared with x:

>>> y = x[2:]
>>> y.base is x
True


numpy.ma.MaskedArray.ctypes

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.base

Next topic

numpy.ma.MaskedArray.dtype

numpy.ma.MaskedArray.ctypes

MaskedArray.ctypes

An object to simplify the interaction of the array with the ctypes module.

This attribute creates an object that makes it easier to use arrays when calling shared libraries with the ctypes module. The returned object has, among others, data, shape, and strides attributes (see Notes below) which themselves return ctypes objects that can be used as arguments to a shared library.

Parameters:

None
Returns:

c : Python object

Possessing attributes data, shape, strides, etc.

See also

numpy.ctypeslib

Notes

Below are the public attributes of this object which were documented in “Guide to NumPy” (we have omitted undocumented public attributes, as well as documented private attributes):

  • data: A pointer to the memory area of the array as a Python integer. This memory area may contain data that is not aligned, or not in correct byte-order. The memory area may not even be writeable. The array flags and data-type of this array should be respected when passing this attribute to arbitrary C-code to avoid trouble that can include Python crashing. User Beware! The value of this attribute is exactly the same as self._array_interface_[‘data’][0].
  • shape (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the C-integer corresponding to dtype(‘p’) on this platform. This base-type could be c_int, c_long, or c_longlong depending on the platform. The c_intp type is defined accordingly in numpy.ctypeslib. The ctypes array contains the shape of the underlying array.
  • strides (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the same as for the shape attribute. This ctypes array contains the strides information from the underlying array. This strides information is important for showing how many bytes must be jumped to get to the next element in the array.
  • data_as(obj): Return the data pointer cast to a particular c-types object. For example, calling self._as_parameter_ is equivalent to self.data_as(ctypes.c_void_p). Perhaps you want to use the data as a pointer to a ctypes array of floating-point data: self.data_as(ctypes.POINTER(ctypes.c_double)).
  • shape_as(obj): Return the shape tuple as an array of some other c-types type. For example: self.shape_as(ctypes.c_short).
  • strides_as(obj): Return the strides tuple as an array of some other c-types type. For example: self.strides_as(ctypes.c_longlong).

Be careful using the ctypes attribute - especially on temporary arrays or arrays constructed on the fly. For example, calling (a+b).ctypes.data_as(ctypes.c_void_p) returns a pointer to memory that is invalid because the array created as (a+b) is deallocated before the next Python statement. You can avoid this problem using either c=a+b or ct=(a+b).ctypes. In the latter case, ct will hold a reference to the array until ct is deleted or re-assigned.

If the ctypes module is not available, then the ctypes attribute of array objects still returns something useful, but ctypes objects are not returned and errors may be raised instead. In particular, the object will still have the as parameter attribute which will return an integer equal to the data attribute.

Examples

>>> import ctypes
>>> x
array([[0, 1],
       [2, 3]])
>>> x.ctypes.data
30439712
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long))
<ctypes.LP_c_long object at 0x01F01300>
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long)).contents
c_long(0)
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_longlong)).contents
c_longlong(4294967296L)
>>> x.ctypes.shape
<numpy.core._internal.c_long_Array_2 object at 0x01FFD580>
>>> x.ctypes.shape_as(ctypes.c_long)
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides_as(ctypes.c_longlong)
<numpy.core._internal.c_longlong_Array_2 object at 0x01F01300>


numpy.ma.MaskedArray.dtype

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.ctypes

Next topic

numpy.ma.MaskedArray.flags

numpy.ma.MaskedArray.dtype

MaskedArray.dtype

Data-type of the array’s elements.

Parameters: None
Returns: d : numpy dtype object

See also

numpy.dtype

Examples

>>> x
array([[0, 1],
       [2, 3]])
>>> x.dtype
dtype('int32')
>>> type(x.dtype)
<type 'numpy.dtype'>


numpy.ma.MaskedArray.flags

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.dtype

Next topic

numpy.ma.MaskedArray.itemsize

numpy.ma.MaskedArray.flags

MaskedArray.flags

Information about the memory layout of the array.

Notes

The flags object can be accessed dictionary-like (as in a.flags['WRITEABLE']), or by using lowercased attribute names (as in a.flags.writeable). Short flag names are only supported in dictionary access.

Only the UPDATEIFCOPY, WRITEABLE, and ALIGNED flags can be changed by the user, via direct assignment to the attribute or dictionary entry, or by calling ndarray.setflags.

The array flags cannot be set arbitrarily:

  • UPDATEIFCOPY can only be set False.
  • ALIGNED can only be set True if the data is truly aligned.
  • WRITEABLE can only be set True if the array owns its own memory or the ultimate owner of the memory exposes a writeable buffer interface or is a string.

Arrays can be both C-style and Fortran-style contiguous simultaneously. This is clear for 1-dimensional arrays, but can also be true for higher dimensional arrays.

Even for contiguous arrays a stride for a given dimension arr.strides[dim] may be arbitrary if arr.shape[dim] == 1 or the array has no elements. It does not generally hold that self.strides[-1] == self.itemsize for C-style contiguous arrays or self.strides[0] == self.itemsize for Fortran-style contiguous arrays is true.

Attributes

C_CONTIGUOUS (C) | The data is in a single, C-style contiguous segment.
F_CONTIGUOUS (F) | The data is in a single, Fortran-style contiguous segment.
OWNDATA (O) | The array owns the memory it uses or borrows it from another object.
WRITEABLE (W) | The data area can be written to. Setting this to False locks the data, making it read-only. A view (slice, etc.) inherits WRITEABLE from its base array at creation time, but a view of a writeable array may be subsequently locked while the base array remains writeable. (The opposite is not true, in that a view of a locked array may not be made writeable. However, currently, locking a base object does not lock any views that already reference it, so under that circumstance it is possible to alter the contents of a locked array via a previously created writeable view onto it.) Attempting to change a non-writeable array raises a RuntimeError exception.
ALIGNED (A) | The data and all elements are aligned appropriately for the hardware.
UPDATEIFCOPY (U) | This array is a copy of some other array. When this array is deallocated, the base array will be updated with the contents of this array.
FNC | F_CONTIGUOUS and not C_CONTIGUOUS.
FORC | F_CONTIGUOUS or C_CONTIGUOUS (one-segment test).
BEHAVED (B) | ALIGNED and WRITEABLE.
CARRAY (CA) | BEHAVED and C_CONTIGUOUS.
FARRAY (FA) | BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS.


numpy.ma.MaskedArray.itemsize

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.flags

Next topic

numpy.ma.MaskedArray.nbytes

numpy.ma.MaskedArray.itemsize

MaskedArray.itemsize

Length of one array element in bytes.

Examples

>>> x = np.array([1,2,3], dtype=np.float64)
>>> x.itemsize
8
>>> x = np.array([1,2,3], dtype=np.complex128)
>>> x.itemsize
16


numpy.ma.MaskedArray.nbytes

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.itemsize

Next topic

numpy.ma.MaskedArray.ndim

numpy.ma.MaskedArray.nbytes

MaskedArray.nbytes

Total bytes consumed by the elements of the array.

Notes

Does not include memory consumed by non-element attributes of the array object.

Examples

>>> x = np.zeros((3,5,2), dtype=np.complex128)
>>> x.nbytes
480
>>> np.prod(x.shape) * x.itemsize
480


numpy.ma.MaskedArray.ndim

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.nbytes

Next topic

numpy.ma.MaskedArray.shape

numpy.ma.MaskedArray.ndim

MaskedArray.ndim

Number of array dimensions.

Examples

>>> x = np.array([1, 2, 3])
>>> x.ndim
1
>>> y = np.zeros((2, 3, 4))
>>> y.ndim
3


numpy.ma.MaskedArray.shape

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.ndim

Next topic

numpy.ma.MaskedArray.size

numpy.ma.MaskedArray.shape

MaskedArray.shape

Tuple of array dimensions.

Notes

May be used to “reshape” the array, as long as this would not require a change in the total number of elements

Examples

>>> x = np.array([1, 2, 3, 4])
>>> x.shape
(4,)
>>> y = np.zeros((2, 3, 4))
>>> y.shape
(2, 3, 4)
>>> y.shape = (3, 8)
>>> y
array([[ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])
>>> y.shape = (3, 6)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: total size of new array must be unchanged


numpy.ma.MaskedArray.size

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.shape

Next topic

numpy.ma.MaskedArray.strides

numpy.ma.MaskedArray.size

MaskedArray.size

Number of elements in the array.

Equivalent to np.prod(a.shape), i.e., the product of the array’s dimensions.

Examples

>>> x = np.zeros((3, 5, 2), dtype=np.complex128)
>>> x.size
30
>>> np.prod(x.shape)
30


numpy.ma.MaskedArray.strides

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.size

Next topic

numpy.ma.MaskedArray.imag

numpy.ma.MaskedArray.strides

MaskedArray.strides

Tuple of bytes to step in each dimension when traversing an array.

The byte offset of element (i[0], i[1], ..., i[n]) in an array a is:

offset = sum(np.array(i) * a.strides)

A more detailed explanation of strides can be found in the “ndarray.rst” file in the NumPy reference guide.

See also

numpy.lib.stride_tricks.as_strided

Notes

Imagine an array of 32-bit integers (each 4 bytes):

x = np.array([[0, 1, 2, 3, 4],
              [5, 6, 7, 8, 9]], dtype=np.int32)

This array is stored in memory as 40 bytes, one after the other (known as a contiguous block of memory). The strides of an array tell us how many bytes we have to skip in memory to move to the next position along a certain axis. For example, we have to skip 4 bytes (1 value) to move to the next column, but 20 bytes (5 values) to get to the same position in the next row. As such, the strides for the array x will be (20, 4).

Examples

>>> y = np.reshape(np.arange(2*3*4), (2,3,4))
>>> y
array([[[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]],
       [[12, 13, 14, 15],
        [16, 17, 18, 19],
        [20, 21, 22, 23]]])
>>> y.strides
(48, 16, 4)
>>> y[1,1,1]
17
>>> offset=sum(y.strides * np.array((1,1,1)))
>>> offset/y.itemsize
17

>>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0)
>>> x.strides
(32, 4, 224, 1344)
>>> i = np.array([3,5,2,2])
>>> offset = sum(i * x.strides)
>>> x[3,5,2,2]
813
>>> offset / x.itemsize
813


numpy.ma.MaskedArray.imag

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.strides

Next topic

numpy.ma.MaskedArray.real

numpy.ma.MaskedArray.imag

MaskedArray.imag

Imaginary part.


numpy.ma.MaskedArray.real

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.imag

Next topic

numpy.ma.MaskedArray.flat

numpy.ma.MaskedArray.real

MaskedArray.real

Real part


numpy.ma.MaskedArray.flat

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.real

Next topic

numpy.ma.MaskedArray.__array_priority__

numpy.ma.MaskedArray.flat

MaskedArray.flat

Flat version of the array.


numpy.ma.MaskedArray.__array_priority__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.flat

Next topic

numpy.ma.MaskedArray.__float__

numpy.ma.MaskedArray.__array_priority__

MaskedArray.__array_priority__ = 15


numpy.ma.MaskedArray.__float__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__array_priority__

Next topic

numpy.ma.MaskedArray.__hex__

numpy.ma.MaskedArray.__float__

MaskedArray.__float__() [source]

Convert to float.


numpy.ma.MaskedArray.__hex__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__float__

Next topic

numpy.ma.MaskedArray.__int__

numpy.ma.MaskedArray.__hex__

MaskedArray.__hex__() <==> hex(x)


numpy.ma.MaskedArray.__int__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__hex__

Next topic

numpy.ma.MaskedArray.__long__

numpy.ma.MaskedArray.__int__

MaskedArray.__int__() [source]

Convert to int.


numpy.ma.MaskedArray.__long__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__int__

Next topic

numpy.ma.MaskedArray.__oct__

numpy.ma.MaskedArray.__long__

MaskedArray.__long__() <==> long(x)


numpy.ma.MaskedArray.__oct__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__long__

Next topic

numpy.ma.MaskedArray.view

numpy.ma.MaskedArray.__oct__

MaskedArray.__oct__() <==> oct(x)


numpy.ma.MaskedArray.view

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__oct__

Next topic

numpy.ma.MaskedArray.astype

numpy.ma.MaskedArray.view

MaskedArray.view(dtype=None, type=None) [source]

New view of array with the same data.

Parameters:

dtype : data-type or ndarray sub-class, optional

Data-type descriptor of the returned view, e.g., float32 or int16. The default, None, results in the view having the same data-type as a. This argument can also be specified as an ndarray sub-class, which then specifies the type of the returned object (this is equivalent to setting the type parameter).

type : Python type, optional

Type of the returned view, e.g., ndarray or matrix. Again, the default None results in type preservation.

Notes

a.view() is used two different ways:

a.view(some_dtype) or a.view(dtype=some_dtype) constructs a view of the array’s memory with a different data-type. This can cause a reinterpretation of the bytes of memory.

a.view(ndarray_subclass) or a.view(type=ndarray_subclass) just returns an instance of ndarray_subclass that looks at the same array (same shape, dtype, etc.) This does not cause a reinterpretation of the memory.

For a.view(some_dtype), if some_dtype has a different number of bytes per entry than the previous dtype (for example, converting a regular array to a structured array), then the behavior of the view cannot be predicted just from the superficial appearance of a (shown by print(a)). It also depends on exactly how a is stored in memory. Therefore if a is C-ordered versus fortran-ordered, versus defined as a slice or transpose, etc., the view may give different results.

Examples

>>> x = np.array([(1, 2)], dtype=[('a', np.int8), ('b', np.int8)])

Viewing array data using a different type and dtype:

>>> y = x.view(dtype=np.int16, type=np.matrix)
>>> y
matrix([[513]], dtype=int16)
>>> print type(y)
<class 'numpy.matrixlib.defmatrix.matrix'>

Creating a view on a structured array so it can be used in calculations

>>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)])
>>> xv = x.view(dtype=np.int8).reshape(-1,2)
>>> xv
array([[1, 2],
       [3, 4]], dtype=int8)
>>> xv.mean(0)
array([ 2.,  3.])

Making changes to the view changes the underlying array

>>> xv[0,1] = 20
>>> print x
[(1, 20) (3, 4)]

Using a view to convert an array to a record array:

>>> z = x.view(np.recarray)
>>> z.a
array([1], dtype=int8)

Views share data:

>>> x[0] = (9, 10)
>>> z[0]
(9, 10)

Views that change the dtype size (bytes per entry) should normally be avoided on arrays defined by slices, transposes, fortran-ordering, etc.:

>>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16)
>>> y = x[:, 0:2]
>>> y
array([[1, 2],
       [4, 5]], dtype=int16)
>>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: new type not compatible with array.
>>> z = y.copy()
>>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
array([[(1, 2)],
       [(4, 5)]], dtype=[('width', '<i2'), ('length', '<i2')])


numpy.ma.MaskedArray.astype

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.view

Next topic

numpy.ma.MaskedArray.byteswap

numpy.ma.MaskedArray.astype

MaskedArray.astype(newtype) [source]

Returns a copy of the MaskedArray cast to given newtype.

Returns:

output : MaskedArray

A copy of self cast to input newtype. The returned record shape matches self.shape.

Examples

>>> x = np.ma.array([[1,2,3.1],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1.0 -- 3.1]
 [-- 5.0 --]
 [7.0 -- 9.0]]
>>> print x.astype(int32)
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]


numpy.ma.MaskedArray.byteswap

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.astype

Next topic

numpy.ma.MaskedArray.compressed

numpy.ma.MaskedArray.byteswap

MaskedArray.byteswap(inplace)

Swap the bytes of the array elements

Toggle between low-endian and big-endian data representation by returning a byteswapped array, optionally swapped in-place.

Parameters:

inplace : bool, optional

If True, swap bytes in-place, default is False.
Returns:

out : ndarray

The byteswapped array. If inplace is True, this is a view to self.

Examples

>>> A = np.array([1, 256, 8755], dtype=np.int16)
>>> map(hex, A)
['0x1', '0x100', '0x2233']
>>> A.byteswap(True)
array([  256,     1, 13090], dtype=int16)
>>> map(hex, A)
['0x100', '0x1', '0x3322']

Arrays of strings are not swapped

>>> A = np.array(['ceg', 'fac'])
>>> A.byteswap()
array(['ceg', 'fac'],
      dtype='|S3')


numpy.ma.MaskedArray.compressed

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.filled

Next topic

numpy.ma.MaskedArray.filled

numpy.ma.MaskedArray.compressed

MaskedArray.compressed() [source]

Return all the non-masked data as a 1-D array.

Returns:

data : ndarray

A new ndarray holding the non-masked data is returned.

Notes

The result is not a MaskedArray!

Examples

>>> x = np.ma.array(np.arange(5), mask=[0]*2 + [1]*3)
>>> x.compressed()
array([0, 1])
>>> type(x.compressed())
<type 'numpy.ndarray'>


numpy.ma.MaskedArray.filled

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.compressed

Next topic

numpy.ma.MaskedArray.tofile

numpy.ma.MaskedArray.filled

MaskedArray.filled(fill_value=None) [source]

Return a copy of self, with masked values filled with a given value.

Parameters:

fill_value : scalar, optional

The value to use for invalid entries (None by default). If None, the fill_value attribute of the array is used instead.
Returns:

filled_array : ndarray

A copy of self with invalid entries replaced by fill_value (be it the function argument or the attribute of self.

Notes

The result is not a MaskedArray!

Examples

>>> x = np.ma.array([1,2,3,4,5], mask=[0,0,1,0,1], fill_value=-999)
>>> x.filled()
array([1, 2, -999, 4, -999])
>>> type(x.filled())
<type 'numpy.ndarray'>

Subclassing is preserved. This means that if the data part of the masked array is a matrix, filled returns a matrix:

>>> x = np.ma.array(np.matrix([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])
>>> x.filled()
matrix([[     1, 999999],
        [999999,      4]])


numpy.ma.MaskedArray.tofile

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.filled

Next topic

numpy.ma.MaskedArray.tolist

numpy.ma.MaskedArray.tofile

MaskedArray.tofile(fid, sep='', format='%s') [source]

Save a masked array to a file in binary format.

Warning

This function is not implemented yet.

Raises:

NotImplementedError

When tofile is called.


numpy.ma.MaskedArray.toflex

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.tofile

Next topic

numpy.ma.MaskedArray.tolist

numpy.ma.MaskedArray.toflex

MaskedArray.toflex() [source]

Transforms a masked array into a flexible-type array.

The flexible type array that is returned will have two fields:

  • the _data field stores the _data part of the array.
  • the _mask field stores the _mask part of the array.
Parameters:

None
Returns:

record : ndarray

A new flexible-type ndarray with two fields: the first element containing a value, the second element containing the corresponding mask boolean. The returned record shape matches self.shape.

Notes

A side-effect of transforming a masked array into a flexible ndarray is that meta information (fill_value, ...) will be lost.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]
>>> print x.toflex()
[[(1, False) (2, True) (3, False)]
 [(4, True) (5, False) (6, True)]
 [(7, False) (8, True) (9, False)]]


numpy.ma.MaskedArray.tolist

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.tofile

Next topic

numpy.ma.MaskedArray.torecords

numpy.ma.MaskedArray.tolist

MaskedArray.tolist(fill_value=None) [source]

Return the data portion of the masked array as a hierarchical Python list.

Data items are converted to the nearest compatible Python type. Masked values are converted to fill_value. If fill_value is None, the corresponding entries in the output list will be None.

Parameters:

fill_value : scalar, optional

The value to use for invalid entries. Default is None.
Returns:

result : list

The Python list representation of the masked array.

Examples

>>> x = np.ma.array([[1,2,3], [4,5,6], [7,8,9]], mask=[0] + [1,0]*4)
>>> x.tolist()
[[1, None, 3], [None, 5, None], [7, None, 9]]
>>> x.tolist(-999)
[[1, -999, 3], [-999, 5, -999], [7, -999, 9]]


numpy.ma.MaskedArray.torecords

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.tolist

Next topic

numpy.ma.MaskedArray.tobytes

numpy.ma.MaskedArray.torecords

MaskedArray.torecords() [source]

Transforms a masked array into a flexible-type array.

The flexible type array that is returned will have two fields:

  • the _data field stores the _data part of the array.
  • the _mask field stores the _mask part of the array.
Parameters:

None
Returns:

record : ndarray

A new flexible-type ndarray with two fields: the first element containing a value, the second element containing the corresponding mask boolean. The returned record shape matches self.shape.

Notes

A side-effect of transforming a masked array into a flexible ndarray is that meta information (fill_value, ...) will be lost.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]
>>> print x.toflex()
[[(1, False) (2, True) (3, False)]
 [(4, True) (5, False) (6, True)]
 [(7, False) (8, True) (9, False)]]


numpy.ma.MaskedArray.tostring

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.torecords

Next topic

numpy.ma.MaskedArray.tobytes

numpy.ma.MaskedArray.tostring

MaskedArray.tostring(fill_value=None, order='C') [source]

This function is a compatibility alias for tobytes. Despite its name it returns bytes not strings.


numpy.ma.MaskedArray.tobytes

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.torecords

Next topic

numpy.ma.dump

numpy.ma.MaskedArray.tobytes

MaskedArray.tobytes(fill_value=None, order='C') [source]

Return the array data as a string containing the raw bytes in the array.

The array is filled with a fill value before the string conversion.

New in version 1.9.0.

Parameters:

fill_value : scalar, optional

Value used to fill in the masked values. Deafult is None, in which case MaskedArray.fill_value is used.

order : {‘C’,’F’,’A’}, optional

Order of the data item in the copy. Default is ‘C’.

  • ‘C’ – C order (row major).
  • ‘F’ – Fortran order (column major).
  • ‘A’ – Any, current order of array.
  • None – Same as ‘A’.

See also

ndarray.tobytes, tolist, tofile

Notes

As for ndarray.tobytes, information about the shape, dtype, etc., but also about fill_value, will be lost.

Examples

>>> x = np.ma.array(np.array([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])
>>> x.tobytes()
'\x01\x00\x00\x00?B\x0f\x00?B\x0f\x00\x04\x00\x00\x00'


numpy.ma.MaskedArray.flatten

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.resize

Next topic

numpy.ma.MaskedArray.ravel

numpy.ma.MaskedArray.flatten

MaskedArray.flatten(order='C')

Return a copy of the array collapsed into one dimension.

Parameters:

order : {‘C’, ‘F’, ‘A’}, optional

Whether to flatten in C (row-major), Fortran (column-major) order, or preserve the C/Fortran ordering from a. The default is ‘C’.
Returns:

y : ndarray

A copy of the input array, flattened to one dimension.

See also

ravel
Return a flattened array.
flat
A 1-D flat iterator over the array.

Examples

>>> a = np.array([[1,2], [3,4]])
>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten('F')
array([1, 3, 2, 4])


numpy.ma.MaskedArray.ravel

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.flatten

Next topic

numpy.ma.MaskedArray.reshape

numpy.ma.MaskedArray.ravel

MaskedArray.ravel() [source]

Returns a 1D version of self, as a view.

Returns:

MaskedArray

Output view is of shape (self.size,) (or (np.ma.product(self.shape),)).

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]
>>> print x.ravel()
[1 -- 3 -- 5 -- 7 -- 9]


numpy.ma.MaskedArray.reshape

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.ravel

Next topic

numpy.ma.MaskedArray.resize

numpy.ma.MaskedArray.reshape

MaskedArray.reshape(*s, **kwargs) [source]

Give a new shape to the array without changing its data.

Returns a masked array containing the same data, but with a new shape. The result is a view on the original array; if this is not possible, a ValueError is raised.

Parameters:

shape : int or tuple of ints

The new shape should be compatible with the original shape. If an integer is supplied, then the result will be a 1-D array of that length.

order : {‘C’, ‘F’}, optional

Determines whether the array data should be viewed as in C (row-major) or FORTRAN (column-major) order.
Returns:

reshaped_array : array

A new view on the array.

See also

reshape
Equivalent function in the masked array module.
numpy.ndarray.reshape
Equivalent method on ndarray object.
numpy.reshape
Equivalent function in the NumPy module.

Notes

The reshaping operation cannot guarantee that a copy will not be made, to modify the shape in place, use a.shape = s

Examples

>>> x = np.ma.array([[1,2],[3,4]], mask=[1,0,0,1])
>>> print x
[[-- 2]
 [3 --]]
>>> x = x.reshape((4,1))
>>> print x
[[--]
 [2]
 [3]
 [--]]


numpy.ma.MaskedArray.resize

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.reshape

Next topic

numpy.ma.swapaxes

numpy.ma.MaskedArray.resize

MaskedArray.resize(newshape, refcheck=True, order=False) [source]

Warning

This method does nothing, except raise a ValueError exception. A masked array does not own its data and therefore cannot safely be resized in place. Use the numpy.ma.resize function instead.

This method is difficult to implement safely and may be deprecated in future releases of NumPy.


numpy.ma.MaskedArray.squeeze

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.squeeze

Next topic

numpy.ma.column_stack

numpy.ma.MaskedArray.squeeze

MaskedArray.squeeze(axis=None)

Remove single-dimensional entries from the shape of a.

Refer to numpy.squeeze for full documentation.

See also

numpy.squeeze
equivalent function


numpy.ma.MaskedArray.swapaxes

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.transpose

Next topic

numpy.ma.MaskedArray.transpose

numpy.ma.MaskedArray.swapaxes

MaskedArray.swapaxes(axis1, axis2)

Return a view of the array with axis1 and axis2 interchanged.

Refer to numpy.swapaxes for full documentation.

See also

numpy.swapaxes
equivalent function


numpy.ma.MaskedArray.transpose

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.trace

Next topic

numpy.ma.vander

numpy.ma.MaskedArray.transpose

MaskedArray.transpose(*axes)

Returns a view of the array with axes transposed.

For a 1-D array, this has no effect. (To change between column and row vectors, first cast the 1-D array into a matrix object.) For a 2-D array, this is the usual matrix transpose. For an n-D array, if axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided and a.shape = (i[0], i[1], ... i[n-2], i[n-1]), then a.transpose().shape = (i[n-1], i[n-2], ... i[1], i[0]).

Parameters:

axes : None, tuple of ints, or n ints

  • None or no argument: reverses the order of the axes.
  • tuple of ints: i in the j-th place in the tuple means a‘s i-th axis becomes a.transpose()‘s j-th axis.
  • n ints: same as an n-tuple of the same ints (this form is intended simply as a “convenience” alternative to the tuple form)
Returns:

out : ndarray

View of a, with axes suitably permuted.

See also

ndarray.T
Array property returning the array transposed.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> a
array([[1, 2],
       [3, 4]])
>>> a.transpose()
array([[1, 3],
       [2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
       [2, 4]])
>>> a.transpose(1, 0)
array([[1, 3],
       [2, 4]])


numpy.ma.MaskedArray.T

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.transpose

Next topic

numpy.ma.MaskedArray.argmax

numpy.ma.MaskedArray.T

MaskedArray.T


numpy.ma.MaskedArray.argmax

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.ptp

Next topic

numpy.ma.MaskedArray.argmin

numpy.ma.MaskedArray.argmax

MaskedArray.argmax(axis=None, fill_value=None, out=None) [source]

Returns array of indices of the maximum values along the given axis. Masked values are treated as if they had the value fill_value.

Parameters:

axis : {None, integer}

If None, the index is into the flattened array, otherwise along the specified axis

fill_value : {var}, optional

Value used to fill in the masked values. If None, the output of maximum_fill_value(self._data) is used instead.

out : {None, array}, optional

Array into which the result can be placed. Its type is preserved and it must be of the right shape to hold the output.
Returns:

index_array : {integer_array}

Examples

>>> a = np.arange(6).reshape(2,3)
>>> a.argmax()
5
>>> a.argmax(0)
array([1, 1, 1])
>>> a.argmax(1)
array([2, 2])


numpy.ma.MaskedArray.argmin

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.argmax

Next topic

numpy.ma.MaskedArray.max

numpy.ma.MaskedArray.argmin

MaskedArray.argmin(axis=None, fill_value=None, out=None) [source]

Return array of indices to the minimum values along the given axis.

Parameters:

axis : {None, integer}

If None, the index is into the flattened array, otherwise along the specified axis

fill_value : {var}, optional

Value used to fill in the masked values. If None, the output of minimum_fill_value(self._data) is used instead.

out : {None, array}, optional

Array into which the result can be placed. Its type is preserved and it must be of the right shape to hold the output.
Returns:

{ndarray, scalar}

If multi-dimension input, returns a new ndarray of indices to the minimum values along the given axis. Otherwise, returns a scalar of index to the minimum values along the given axis.

Examples

>>> x = np.ma.array(arange(4), mask=[1,1,0,0])
>>> x.shape = (2,2)
>>> print x
[[-- --]
 [2 3]]
>>> print x.argmin(axis=0, fill_value=-1)
[0 0]
>>> print x.argmin(axis=0, fill_value=9)
[1 1]


numpy.ma.MaskedArray.argsort

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.sort

Next topic

numpy.ma.MaskedArray.sort

numpy.ma.MaskedArray.argsort

MaskedArray.argsort(axis=None, kind='quicksort', order=None, fill_value=None) [source]

Return an ndarray of indices that sort the array along the specified axis. Masked values are filled beforehand to fill_value.

Parameters:

axis : int, optional

Axis along which to sort. The default is -1 (last axis). If None, the flattened array is used.

fill_value : var, optional

Value used to fill the array before sorting. The default is the fill_value attribute of the input array.

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.
Returns:

index_array : ndarray, int

Array of indices that sort a along the specified axis. In other words, a[index_array] yields a sorted a.

See also

sort
Describes sorting algorithms used.
lexsort
Indirect stable sort with multiple keys.
ndarray.sort
Inplace sort.

Notes

See sort for notes on the different sorting algorithms.

Examples

>>> a = np.ma.array([3,2,1], mask=[False, False, True])
>>> a
masked_array(data = [3 2 --],
             mask = [False False  True],
       fill_value = 999999)
>>> a.argsort()
array([1, 0, 2])


numpy.ma.MaskedArray.choose

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.argsort

Next topic

numpy.ma.MaskedArray.compress

numpy.ma.MaskedArray.choose

MaskedArray.choose(choices, out=None, mode='raise')

Use an index array to construct a new array from a set of choices.

Refer to numpy.choose for full documentation.

See also

numpy.choose
equivalent function


numpy.ma.MaskedArray.compress

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.choose

Next topic

numpy.ma.MaskedArray.diagonal

numpy.ma.MaskedArray.compress

MaskedArray.compress(condition, axis=None, out=None) [source]

Return a where condition is True.

If condition is a MaskedArray, missing values are considered as False.

Parameters:

condition : var

Boolean 1-d array selecting which entries to return. If len(condition) is less than the size of a along the axis, then output is truncated to length of condition array.

axis : {None, int}, optional

Axis along which the operation must be performed.

out : {None, ndarray}, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type will be cast if necessary.
Returns:

result : MaskedArray

A MaskedArray object.

Notes

Please note the difference with compressed ! The output of compress has a mask, the output of compressed does not.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]
>>> x.compress([1, 0, 1])
masked_array(data = [1 3],
      mask = [False False],
      fill_value=999999)

>>> x.compress([1, 0, 1], axis=1)
masked_array(data =
 [[1 3]
 [-- --]
 [7 9]],
      mask =
 [[False False]
 [ True  True]
 [False False]],
      fill_value=999999)


numpy.ma.MaskedArray.diagonal

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.compress

Next topic

numpy.ma.MaskedArray.fill

numpy.ma.MaskedArray.diagonal

MaskedArray.diagonal(offset=0, axis1=0, axis2=1)

Return specified diagonals. In NumPy 1.9 the returned array is a read-only view instead of a copy as in previous NumPy versions. In NumPy 1.10 the read-only restriction will be removed.

Refer to numpy.diagonal for full documentation.

See also

numpy.diagonal
equivalent function


numpy.ma.MaskedArray.fill

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.diagonal

Next topic

numpy.ma.MaskedArray.item

numpy.ma.MaskedArray.fill

MaskedArray.fill(value)

Fill the array with a scalar value.

Parameters:

value : scalar

All elements of a will be assigned this value.

Examples

>>> a = np.array([1, 2])
>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([ 1.,  1.])


numpy.ma.MaskedArray.item

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.fill

Next topic

numpy.ma.MaskedArray.nonzero

numpy.ma.MaskedArray.item

MaskedArray.item(*args)

Copy an element of an array to a standard Python scalar and return it.

Parameters:

*args : Arguments (variable number and type)

  • none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.
  • int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.
  • tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.
Returns:

z : Standard Python scalar object

A copy of the specified element of the array as a suitable Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.item(3)
2
>>> x.item(7)
5
>>> x.item((0, 1))
1
>>> x.item((2, 2))
3


numpy.ma.MaskedArray.nonzero

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.count

Next topic

numpy.ma.shape

numpy.ma.MaskedArray.nonzero

MaskedArray.nonzero() [source]

Return the indices of unmasked elements that are not zero.

Returns a tuple of arrays, one for each dimension, containing the indices of the non-zero elements in that dimension. The corresponding non-zero values can be obtained with:

a[a.nonzero()]

To group the indices by element, rather than dimension, use instead:

np.transpose(a.nonzero())

The result of this is always a 2d array, with a row for each non-zero element.

Parameters:

None
Returns:

tuple_of_arrays : tuple

Indices of elements that are non-zero.

See also

numpy.nonzero
Function operating on ndarrays.
flatnonzero
Return indices that are non-zero in the flattened version of the input array.
ndarray.nonzero
Equivalent ndarray method.
count_nonzero
Counts the number of non-zero elements in the input array.

Examples

>>> import numpy.ma as ma
>>> x = ma.array(np.eye(3))
>>> x
masked_array(data =
 [[ 1.  0.  0.]
 [ 0.  1.  0.]
 [ 0.  0.  1.]],
      mask =
 False,
      fill_value=1e+20)
>>> x.nonzero()
(array([0, 1, 2]), array([0, 1, 2]))

Masked elements are ignored.

>>> x[1, 1] = ma.masked
>>> x
masked_array(data =
 [[1.0 0.0 0.0]
 [0.0 -- 0.0]
 [0.0 0.0 1.0]],
      mask =
 [[False False False]
 [False  True False]
 [False False False]],
      fill_value=1e+20)
>>> x.nonzero()
(array([0, 2]), array([0, 2]))

Indices can also be grouped by element.

>>> np.transpose(x.nonzero())
array([[0, 0],
       [2, 2]])

A common use for nonzero is to find the indices of an array, where a condition is True. Given an array a, the condition a > 3 is a boolean array and since False is interpreted as 0, ma.nonzero(a > 3) yields the indices of the a where the condition is true.

>>> a = ma.array([[1,2,3],[4,5,6],[7,8,9]])
>>> a > 3
masked_array(data =
 [[False False False]
 [ True  True  True]
 [ True  True  True]],
      mask =
 False,
      fill_value=999999)
>>> ma.nonzero(a > 3)
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))

The nonzero method of the condition array can also be called.

>>> (a > 3).nonzero()
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))


numpy.ma.MaskedArray.put

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.nonzero

Next topic

numpy.ma.MaskedArray.repeat

numpy.ma.MaskedArray.put

MaskedArray.put(indices, values, mode='raise') [source]

Set storage-indexed locations to corresponding values.

Sets self._data.flat[n] = values[n] for each n in indices. If values is shorter than indices then it will repeat. If values has some masked values, the initial mask is updated in consequence, else the corresponding values are unmasked.

Parameters:

indices : 1-D array_like

Target indices, interpreted as integers.

values : array_like

Values to place in self._data copy at target indices.

mode : {‘raise’, ‘wrap’, ‘clip’}, optional

Specifies how out-of-bounds indices will behave. ‘raise’ : raise an error. ‘wrap’ : wrap around. ‘clip’ : clip to the range.

Notes

values can be a scalar or length 1 array.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]
>>> x.put([0,4,8],[10,20,30])
>>> print x
[[10 -- 3]
 [-- 20 --]
 [7 -- 30]]

>>> x.put(4,999)
>>> print x
[[10 -- 3]
 [-- 999 --]
 [7 -- 30]]


numpy.ma.MaskedArray.repeat

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.put

Next topic

numpy.ma.MaskedArray.searchsorted

numpy.ma.MaskedArray.repeat

MaskedArray.repeat(repeats, axis=None)

Repeat elements of an array.

Refer to numpy.repeat for full documentation.

See also

numpy.repeat
equivalent function


numpy.ma.MaskedArray.searchsorted

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.repeat

Next topic

numpy.ma.MaskedArray.sort

numpy.ma.MaskedArray.searchsorted

MaskedArray.searchsorted(v, side='left', sorter=None)

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See also

numpy.searchsorted
equivalent function


numpy.ma.MaskedArray.sort

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.argsort

Next topic

numpy.ma.diag

numpy.ma.MaskedArray.sort

MaskedArray.sort(axis=-1, kind='quicksort', order=None, endwith=True, fill_value=None) [source]

Sort the array, in-place

Parameters:

a : array_like

Array to be sorted.

axis : int, optional

Axis along which to sort. If None, the array is flattened before sorting. The default is -1, which sorts along the last axis.

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm. Default is ‘quicksort’.

order : list, optional

When a is a structured array, this argument specifies which fields to compare first, second, and so on. This list does not need to include all of the fields.

endwith : {True, False}, optional

Whether missing values (if any) should be forced in the upper indices (at the end of the array) (True) or lower indices (at the beginning). When the array contains unmasked values of the largest (or smallest if False) representable value of the datatype the ordering of these values and the masked values is undefined. To enforce the masked values are at the end (beginning) in this case one must sort the mask.

fill_value : {var}, optional

Value used internally for the masked values. If fill_value is not None, it supersedes endwith.
Returns:

sorted_array : ndarray

Array of the same type and shape as a.

See also

ndarray.sort
Method to sort an array in-place.
argsort
Indirect sort.
lexsort
Indirect stable sort on multiple keys.
searchsorted
Find elements in a sorted array.

Notes

See sort for notes on the different sorting algorithms.

Examples

>>> a = ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])
>>> # Default
>>> a.sort()
>>> print a
[1 3 5 -- --]

>>> a = ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])
>>> # Put missing values in the front
>>> a.sort(endwith=False)
>>> print a
[-- -- 1 3 5]

>>> a = ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])
>>> # fill_value takes over endwith
>>> a.sort(endwith=False, fill_value=3)
>>> print a
[1 -- -- 3 5]


numpy.ma.MaskedArray.take

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.sort

Next topic

numpy.ma.MaskedArray.copy

numpy.ma.MaskedArray.take

MaskedArray.take(indices, axis=None, out=None, mode='raise') [source]


numpy.ma.MaskedArray.copy

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.fromfunction

Next topic

numpy.ma.empty

numpy.ma.MaskedArray.copy

MaskedArray.copy(order='C')

Return a copy of the array.

Parameters:

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout of the copy. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible. (Note that this function and :func:numpy.copy are very similar, but have different default values for their order= arguments.)

See also

numpy.copy, numpy.copyto

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
       [0, 0, 0]])

>>> y
array([[1, 2, 3],
       [4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True


numpy.ma.MaskedArray.dump

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.copy

Next topic

numpy.ma.MaskedArray.dumps

numpy.ma.MaskedArray.dump

MaskedArray.dump(file)

Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.

Parameters:

file : str

A string naming the dump file.


numpy.ma.MaskedArray.dumps

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.dump

Next topic

numpy.ma.MaskedArray.all

numpy.ma.MaskedArray.dumps

MaskedArray.dumps()

Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an array.

Parameters: None


numpy.ma.MaskedArray.all

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.recordmask

Next topic

numpy.ma.MaskedArray.any

numpy.ma.MaskedArray.all

MaskedArray.all(axis=None, out=None) [source]

Check if all of the elements of a are true.

Performs a logical_and over the given axis and returns the result. Masked values are considered as True during computation. For convenience, the output array is masked where ALL the values along the current axis are masked: if the output would have been a scalar and that all the values are masked, then the output is masked.

Parameters:

axis : {None, integer}

Axis to perform the operation over. If None, perform over flattened array.

out : {None, array}, optional

Array into which the result can be placed. Its type is preserved and it must be of the right shape to hold the output.

See also

all
equivalent function

Examples

>>> np.ma.array([1,2,3]).all()
True
>>> a = np.ma.array([1,2,3], mask=True)
>>> (a.all() is np.ma.masked)
True


numpy.ma.MaskedArray.anom

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.var

Next topic

numpy.ma.MaskedArray.cumprod

numpy.ma.MaskedArray.anom

MaskedArray.anom(axis=None, dtype=None) [source]

Compute the anomalies (deviations from the arithmetic mean) along the given axis.

Returns an array of anomalies, with the same shape as the input and where the arithmetic mean is computed along the given axis.

Parameters:

axis : int, optional

Axis over which the anomalies are taken. The default is to use the mean of the flattened array as reference.

dtype : dtype, optional

Type to use in computing the variance. For arrays of integer type

the default is float32; for arrays of float types it is the same as the array type.

See also

mean
Compute the mean of the array.

Examples

>>> a = np.ma.array([1,2,3])
>>> a.anom()
masked_array(data = [-1.  0.  1.],
             mask = False,
       fill_value = 1e+20)


numpy.ma.MaskedArray.any

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.all

Next topic

numpy.ma.MaskedArray.count

numpy.ma.MaskedArray.any

MaskedArray.any(axis=None, out=None) [source]

Check if any of the elements of a are true.

Performs a logical_or over the given axis and returns the result. Masked values are considered as False during computation.

Parameters:

axis : {None, integer}

Axis to perform the operation over. If None, perform over flattened array and return a scalar.

out : {None, array}, optional

Array into which the result can be placed. Its type is preserved and it must be of the right shape to hold the output.

See also

any
equivalent function


numpy.ma.MaskedArray.clip

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.round

Next topic

numpy.ma.MaskedArray.round

numpy.ma.MaskedArray.clip

MaskedArray.clip(a_min, a_max, out=None)

Return an array whose values are limited to [a_min, a_max].

Refer to numpy.clip for full documentation.

See also

numpy.clip
equivalent function


numpy.ma.MaskedArray.conj

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.clip

Next topic

numpy.ma.MaskedArray.conjugate

numpy.ma.MaskedArray.conj

MaskedArray.conj()

Complex-conjugate all elements.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.ma.MaskedArray.conjugate

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.conj

Next topic

numpy.ma.MaskedArray.cumprod

numpy.ma.MaskedArray.conjugate

MaskedArray.conjugate()

Return the complex conjugate, element-wise.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.ma.MaskedArray.cumprod

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.anom

Next topic

numpy.ma.MaskedArray.cumsum

numpy.ma.MaskedArray.cumprod

MaskedArray.cumprod(axis=None, dtype=None, out=None) [source]

Return the cumulative product of the elements along the given axis. The cumulative product is taken over the flattened array by default, otherwise over the specified axis.

Masked values are set to 1 internally during the computation. However, their position is saved, and the result will be masked at the same locations.

Parameters:

axis : {None, -1, int}, optional

Axis along which the product is computed. The default (axis = None) is to compute over the flattened array.

dtype : {None, dtype}, optional

Determines the type of the returned array and of the accumulator where the elements are multiplied. If dtype has the value None and the type of a is an integer type of precision less than the default platform integer, then the default platform integer precision is used. Otherwise, the dtype is the same as that of a.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary.
Returns:

cumprod : ndarray

A new array holding the result is returned unless out is specified, in which case a reference to out is returned.

Notes

The mask is lost if out is not a valid MaskedArray !

Arithmetic is modular when using integer types, and no error is raised on overflow.


numpy.ma.MaskedArray.cumsum

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.cumprod

Next topic

numpy.ma.MaskedArray.mean

numpy.ma.MaskedArray.cumsum

MaskedArray.cumsum(axis=None, dtype=None, out=None) [source]

Return the cumulative sum of the elements along the given axis. The cumulative sum is calculated over the flattened array by default, otherwise over the specified axis.

Masked values are set to 0 internally during the computation. However, their position is saved, and the result will be masked at the same locations.

Parameters:

axis : {None, -1, int}, optional

Axis along which the sum is computed. The default (axis = None) is to compute over the flattened array. axis may be negative, in which case it counts from the last to the first axis.

dtype : {None, dtype}, optional

Type of the returned array and of the accumulator in which the elements are summed. If dtype is not specified, it defaults to the dtype of a, unless a has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary.
Returns:

cumsum : ndarray.

A new array holding the result is returned unless out is specified, in which case a reference to out is returned.

Notes

The mask is lost if out is not a valid MaskedArray !

Arithmetic is modular when using integer types, and no error is raised on overflow.

Examples

>>> marr = np.ma.array(np.arange(10), mask=[0,0,0,1,1,1,0,0,0,0])
>>> print marr.cumsum()
[0 1 3 -- -- -- 9 16 24 33]


numpy.ma.MaskedArray.max

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.argmin

Next topic

numpy.ma.MaskedArray.min

numpy.ma.MaskedArray.max

MaskedArray.max(axis=None, out=None, fill_value=None) [source]

Return the maximum along a given axis.

Parameters:

axis : {None, int}, optional

Axis along which to operate. By default, axis is None and the flattened input is used.

out : array_like, optional

Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output.

fill_value : {var}, optional

Value used to fill in the masked values. If None, use the output of maximum_fill_value().
Returns:

amax : array_like

New array holding the result. If out was specified, out is returned.

See also

maximum_fill_value
Returns the maximum filling value for a given datatype.


numpy.ma.MaskedArray.mean

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.cumsum

Next topic

numpy.ma.MaskedArray.prod

numpy.ma.MaskedArray.mean

MaskedArray.mean(axis=None, dtype=None, out=None) [source]

Returns the average of the array elements.

Masked entries are ignored. The average is taken over the flattened array by default, otherwise over the specified axis. Refer to numpy.mean for the full documentation.

Parameters:

a : array_like

Array containing numbers whose mean is desired. If a is not an array, a conversion is attempted.

axis : int, optional

Axis along which the means are computed. The default is to compute the mean of the flattened array.

dtype : dtype, optional

Type to use in computing the mean. For integer inputs, the default is float64; for floating point, inputs it is the same as the input dtype.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type will be cast if necessary.
Returns:

mean : ndarray, see dtype parameter above

If out=None, returns a new array containing the mean values, otherwise a reference to the output array is returned.

See also

numpy.ma.mean
Equivalent function.
numpy.mean
Equivalent function on non-masked arrays.
numpy.ma.average
Weighted average.

Examples

>>> a = np.ma.array([1,2,3], mask=[False, False, True])
>>> a
masked_array(data = [1 2 --],
             mask = [False False  True],
       fill_value = 999999)
>>> a.mean()
1.5


numpy.ma.MaskedArray.min

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.max

Next topic

numpy.ma.MaskedArray.ptp

numpy.ma.MaskedArray.min

MaskedArray.min(axis=None, out=None, fill_value=None) [source]

Return the minimum along a given axis.

Parameters:

axis : {None, int}, optional

Axis along which to operate. By default, axis is None and the flattened input is used.

out : array_like, optional

Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output.

fill_value : {var}, optional

Value used to fill in the masked values. If None, use the output of minimum_fill_value.
Returns:

amin : array_like

New array holding the result. If out was specified, out is returned.

See also

minimum_fill_value
Returns the minimum filling value for a given datatype.


numpy.ma.MaskedArray.prod

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.mean

Next topic

numpy.ma.MaskedArray.std

numpy.ma.MaskedArray.prod

MaskedArray.prod(axis=None, dtype=None, out=None) [source]

Return the product of the array elements over the given axis. Masked elements are set to 1 internally for computation.

Parameters:

axis : {None, int}, optional

Axis over which the product is taken. If None is used, then the product is over all the array elements.

dtype : {None, dtype}, optional

Determines the type of the returned array and of the accumulator where the elements are multiplied. If dtype has the value None and the type of a is an integer type of precision less than the default platform integer, then the default platform integer precision is used. Otherwise, the dtype is the same as that of a.

out : {None, array}, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type will be cast if necessary.
Returns:

product_along_axis : {array, scalar}, see dtype parameter above.

Returns an array whose shape is the same as a with the specified axis removed. Returns a 0d array when a is 1d or axis=None. Returns a reference to the specified output array if specified.

See also

prod
equivalent function

Notes

Arithmetic is modular when using integer types, and no error is raised on overflow.

Examples

>>> np.prod([1.,2.])
2.0
>>> np.prod([1.,2.], dtype=np.int32)
2
>>> np.prod([[1.,2.],[3.,4.]])
24.0
>>> np.prod([[1.,2.],[3.,4.]], axis=1)
array([  2.,  12.])


numpy.ma.MaskedArray.product

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.prod

Next topic

numpy.ma.MaskedArray.ptp

numpy.ma.MaskedArray.product

MaskedArray.product(axis=None, dtype=None, out=None) [source]

Return the product of the array elements over the given axis. Masked elements are set to 1 internally for computation.

Parameters:

axis : {None, int}, optional

Axis over which the product is taken. If None is used, then the product is over all the array elements.

dtype : {None, dtype}, optional

Determines the type of the returned array and of the accumulator where the elements are multiplied. If dtype has the value None and the type of a is an integer type of precision less than the default platform integer, then the default platform integer precision is used. Otherwise, the dtype is the same as that of a.

out : {None, array}, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type will be cast if necessary.
Returns:

product_along_axis : {array, scalar}, see dtype parameter above.

Returns an array whose shape is the same as a with the specified axis removed. Returns a 0d array when a is 1d or axis=None. Returns a reference to the specified output array if specified.

See also

prod
equivalent function

Notes

Arithmetic is modular when using integer types, and no error is raised on overflow.

Examples

>>> np.prod([1.,2.])
2.0
>>> np.prod([1.,2.], dtype=np.int32)
2
>>> np.prod([[1.,2.],[3.,4.]])
24.0
>>> np.prod([[1.,2.],[3.,4.]], axis=1)
array([  2.,  12.])


numpy.ma.MaskedArray.ptp

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.min

Next topic

numpy.ma.argsort

numpy.ma.MaskedArray.ptp

MaskedArray.ptp(axis=None, out=None, fill_value=None) [source]

Return (maximum - minimum) along the the given dimension (i.e. peak-to-peak value).

Parameters:

axis : {None, int}, optional

Axis along which to find the peaks. If None (default) the flattened array is used.

out : {None, array_like}, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary.

fill_value : {var}, optional

Value used to fill in the masked values.
Returns:

ptp : ndarray.

A new array holding the result, unless out was specified, in which case a reference to out is returned.


numpy.ma.MaskedArray.round

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.clip

Next topic

numpy.ma.allequal

numpy.ma.MaskedArray.round

MaskedArray.round(decimals=0, out=None) [source]

Return a with each element rounded to the given number of decimals.

Refer to numpy.around for full documentation.

See also

numpy.around
equivalent function


numpy.ma.MaskedArray.std

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.prod

Next topic

numpy.ma.MaskedArray.sum

numpy.ma.MaskedArray.std

MaskedArray.std(axis=None, dtype=None, out=None, ddof=0) [source]

Compute the standard deviation along the specified axis.

Returns the standard deviation, a measure of the spread of a distribution, of the array elements. The standard deviation is computed for the flattened array by default, otherwise over the specified axis.

Parameters:

a : array_like

Calculate the standard deviation of these values.

axis : int, optional

Axis along which the standard deviation is computed. The default is to compute the standard deviation of the flattened array.

dtype : dtype, optional

Type to use in computing the standard deviation. For arrays of integer type the default is float64, for arrays of float types it is the same as the array type.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type (of the calculated values) will be cast if necessary.

ddof : int, optional

Means Delta Degrees of Freedom. The divisor used in calculations is N - ddof, where N represents the number of elements. By default ddof is zero.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

standard_deviation : ndarray, see dtype parameter above.

If out is None, return a new array containing the standard deviation, otherwise return a reference to the output array.

See also

var, mean, nanmean, nanstd, nanvar

numpy.doc.ufuncs
Section “Output arguments”

Notes

The standard deviation is the square root of the average of the squared deviations from the mean, i.e., std = sqrt(mean(abs(x - x.mean())**2)).

The average squared deviation is normally calculated as x.sum() / N, where N = len(x). If, however, ddof is specified, the divisor N - ddof is used instead. In standard statistical practice, ddof=1 provides an unbiased estimator of the variance of the infinite population. ddof=0 provides a maximum likelihood estimate of the variance for normally distributed variables. The standard deviation computed in this function is the square root of the estimated variance, so even with ddof=1, it will not be an unbiased estimate of the standard deviation per se.

Note that, for complex numbers, std takes the absolute value before squaring, so that the result is always real and nonnegative.

For floating-point input, the std is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-accuracy accumulator using the dtype keyword can alleviate this issue.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> np.std(a)
1.1180339887498949
>>> np.std(a, axis=0)
array([ 1.,  1.])
>>> np.std(a, axis=1)
array([ 0.5,  0.5])

In single precision, std() can be inaccurate:

>>> a = np.zeros((2,512*512), dtype=np.float32)
>>> a[0,:] = 1.0
>>> a[1,:] = 0.1
>>> np.std(a)
0.45172946707416706

Computing the standard deviation in float64 is more accurate:

>>> np.std(a, dtype=np.float64)
0.44999999925552653


numpy.ma.MaskedArray.sum

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.std

Next topic

numpy.ma.MaskedArray.var

numpy.ma.MaskedArray.sum

MaskedArray.sum(axis=None, dtype=None, out=None) [source]

Return the sum of the array elements over the given axis. Masked elements are set to 0 internally.

Parameters:

axis : {None, -1, int}, optional

Axis along which the sum is computed. The default (axis = None) is to compute over the flattened array.

dtype : {None, dtype}, optional

Determines the type of the returned array and of the accumulator where the elements are summed. If dtype has the value None and the type of a is an integer type of precision less than the default platform integer, then the default platform integer precision is used. Otherwise, the dtype is the same as that of a.

out : {None, ndarray}, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary.
Returns:

sum_along_axis : MaskedArray or scalar

An array with the same shape as self, with the specified axis removed. If self is a 0-d array, or if axis is None, a scalar is returned. If an output array is specified, a reference to out is returned.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]
>>> print x.sum()
25
>>> print x.sum(axis=1)
[4 5 16]
>>> print x.sum(axis=0)
[8 5 12]
>>> print type(x.sum(axis=0, dtype=np.int64)[0])
<type 'numpy.int64'>


numpy.ma.MaskedArray.trace

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.transpose

Next topic

numpy.ma.MaskedArray.transpose

numpy.ma.MaskedArray.trace

MaskedArray.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None) [source]

Return the sum along diagonals of the array.

Refer to numpy.trace for full documentation.

See also

numpy.trace
equivalent function


numpy.ma.MaskedArray.var

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.sum

Next topic

numpy.ma.argmax

numpy.ma.MaskedArray.var

MaskedArray.var(axis=None, dtype=None, out=None, ddof=0) [source]

Compute the variance along the specified axis.

Returns the variance of the array elements, a measure of the spread of a distribution. The variance is computed for the flattened array by default, otherwise over the specified axis.

Parameters:

a : array_like

Array containing numbers whose variance is desired. If a is not an array, a conversion is attempted.

axis : int, optional

Axis along which the variance is computed. The default is to compute the variance of the flattened array.

dtype : data-type, optional

Type to use in computing the variance. For arrays of integer type the default is float32; for arrays of float types it is the same as the array type.

out : ndarray, optional

Alternate output array in which to place the result. It must have the same shape as the expected output, but the type is cast if necessary.

ddof : int, optional

“Delta Degrees of Freedom”: the divisor used in the calculation is N - ddof, where N represents the number of elements. By default ddof is zero.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

variance : ndarray, see dtype parameter above

If out=None, returns a new array containing the variance; otherwise, a reference to the output array is returned.

See also

std, mean, nanmean, nanstd, nanvar

numpy.doc.ufuncs
Section “Output arguments”

Notes

The variance is the average of the squared deviations from the mean, i.e., var = mean(abs(x - x.mean())**2).

The mean is normally calculated as x.sum() / N, where N = len(x). If, however, ddof is specified, the divisor N - ddof is used instead. In standard statistical practice, ddof=1 provides an unbiased estimator of the variance of a hypothetical infinite population. ddof=0 provides a maximum likelihood estimate of the variance for normally distributed variables.

Note that for complex numbers, the absolute value is taken before squaring, so that the result is always real and nonnegative.

For floating-point input, the variance is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-accuracy accumulator using the dtype keyword can alleviate this issue.

Examples

>>> a = np.array([[1,2],[3,4]])
>>> np.var(a)
1.25
>>> np.var(a, axis=0)
array([ 1.,  1.])
>>> np.var(a, axis=1)
array([ 0.25,  0.25])

In single precision, var() can be inaccurate:

>>> a = np.zeros((2,512*512), dtype=np.float32)
>>> a[0,:] = 1.0
>>> a[1,:] = 0.1
>>> np.var(a)
0.20405951142311096

Computing the variance in float64 is more accurate:

>>> np.var(a, dtype=np.float64)
0.20249999932997387
>>> ((1-0.55)**2 + (0.1-0.55)**2)/2
0.20250000000000001


numpy.ma.MaskedArray.__lt__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.var

Next topic

numpy.ma.MaskedArray.__le__

numpy.ma.MaskedArray.__lt__

MaskedArray.__lt__

x.__lt__(y) <==> x<y


numpy.ma.MaskedArray.__le__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__lt__

Next topic

numpy.ma.MaskedArray.__gt__

numpy.ma.MaskedArray.__le__

MaskedArray.__le__

x.__le__(y) <==> x<=y


numpy.ma.MaskedArray.__gt__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__le__

Next topic

numpy.ma.MaskedArray.__ge__

numpy.ma.MaskedArray.__gt__

MaskedArray.__gt__

x.__gt__(y) <==> x>y


numpy.ma.MaskedArray.__ge__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__gt__

Next topic

numpy.ma.MaskedArray.__eq__

numpy.ma.MaskedArray.__ge__

MaskedArray.__ge__

x.__ge__(y) <==> x>=y


numpy.ma.MaskedArray.__eq__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__ge__

Next topic

numpy.ma.MaskedArray.__ne__

numpy.ma.MaskedArray.__eq__

MaskedArray.__eq__(other) [source]

Check whether other equals self elementwise


numpy.ma.MaskedArray.__ne__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__eq__

Next topic

numpy.ma.MaskedArray.__nonzero__

numpy.ma.MaskedArray.__ne__

MaskedArray.__ne__(other) [source]

Check whether other doesn’t equal self elementwise


numpy.ma.MaskedArray.__nonzero__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__ne__

Next topic

numpy.ma.MaskedArray.__abs__

numpy.ma.MaskedArray.__nonzero__

MaskedArray.__nonzero__

x.__nonzero__() <==> x != 0


numpy.ma.MaskedArray.__abs__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__nonzero__

Next topic

numpy.ma.MaskedArray.__add__

numpy.ma.MaskedArray.__abs__

MaskedArray.__abs__() <==> abs(x)


numpy.ma.MaskedArray.__add__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__abs__

Next topic

numpy.ma.MaskedArray.__radd__

numpy.ma.MaskedArray.__add__

MaskedArray.__add__(other) [source]

Add other to self, and return a new masked array.


numpy.ma.MaskedArray.__radd__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__add__

Next topic

numpy.ma.MaskedArray.__sub__

numpy.ma.MaskedArray.__radd__

MaskedArray.__radd__(other) [source]

Add other to self, and return a new masked array.


numpy.ma.MaskedArray.__sub__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__radd__

Next topic

numpy.ma.MaskedArray.__rsub__

numpy.ma.MaskedArray.__sub__

MaskedArray.__sub__(other) [source]

Subtract other to self, and return a new masked array.


numpy.ma.MaskedArray.__rsub__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__sub__

Next topic

numpy.ma.MaskedArray.__mul__

numpy.ma.MaskedArray.__rsub__

MaskedArray.__rsub__(other) [source]

Subtract other to self, and return a new masked array.


numpy.ma.MaskedArray.__mul__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__rsub__

Next topic

numpy.ma.MaskedArray.__rmul__

numpy.ma.MaskedArray.__mul__

MaskedArray.__mul__(other) [source]

Multiply other by self, and return a new masked array.


numpy.ma.MaskedArray.__rmul__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__mul__

Next topic

numpy.ma.MaskedArray.__div__

numpy.ma.MaskedArray.__rmul__

MaskedArray.__rmul__(other) [source]

Multiply other by self, and return a new masked array.


numpy.ma.MaskedArray.__div__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__rmul__

Next topic

numpy.ma.MaskedArray.__rdiv__

numpy.ma.MaskedArray.__div__

MaskedArray.__div__(other) [source]

Divide other into self, and return a new masked array.


numpy.ma.MaskedArray.__rdiv__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__div__

Next topic

numpy.ma.MaskedArray.__truediv__

numpy.ma.MaskedArray.__rdiv__

MaskedArray.__rdiv__

x.__rdiv__(y) <==> y/x


numpy.ma.MaskedArray.__truediv__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__rdiv__

Next topic

numpy.ma.MaskedArray.__rtruediv__

numpy.ma.MaskedArray.__truediv__

MaskedArray.__truediv__(other) [source]

Divide other into self, and return a new masked array.


numpy.ma.MaskedArray.__rtruediv__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__truediv__

Next topic

numpy.ma.MaskedArray.__floordiv__

numpy.ma.MaskedArray.__rtruediv__

MaskedArray.__rtruediv__(other) [source]

Divide other into self, and return a new masked array.


numpy.ma.MaskedArray.__floordiv__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__rtruediv__

Next topic

numpy.ma.MaskedArray.__rfloordiv__

numpy.ma.MaskedArray.__floordiv__

MaskedArray.__floordiv__(other) [source]

Divide other into self, and return a new masked array.


numpy.ma.MaskedArray.__rfloordiv__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__floordiv__

Next topic

numpy.ma.MaskedArray.__mod__

numpy.ma.MaskedArray.__rfloordiv__

MaskedArray.__rfloordiv__(other) [source]

Divide other into self, and return a new masked array.


numpy.ma.MaskedArray.__mod__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__rfloordiv__

Next topic

numpy.ma.MaskedArray.__rmod__

numpy.ma.MaskedArray.__mod__

MaskedArray.__mod__

x.__mod__(y) <==> x%y


numpy.ma.MaskedArray.__rmod__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__mod__

Next topic

numpy.ma.MaskedArray.__divmod__

numpy.ma.MaskedArray.__rmod__

MaskedArray.__rmod__

x.__rmod__(y) <==> y%x


numpy.ma.MaskedArray.__divmod__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__rmod__

Next topic

numpy.ma.MaskedArray.__rdivmod__

numpy.ma.MaskedArray.__divmod__

MaskedArray.__divmod__(y) <==> divmod(x, y)


numpy.ma.MaskedArray.__rdivmod__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__divmod__

Next topic

numpy.ma.MaskedArray.__pow__

numpy.ma.MaskedArray.__rdivmod__

MaskedArray.__rdivmod__(y) <==> divmod(y, x)


numpy.ma.MaskedArray.__pow__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__rdivmod__

Next topic

numpy.ma.MaskedArray.__rpow__

numpy.ma.MaskedArray.__pow__

MaskedArray.__pow__(other) [source]

Raise self to the power other, masking the potential NaNs/Infs


numpy.ma.MaskedArray.__rpow__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__pow__

Next topic

numpy.ma.MaskedArray.__lshift__

numpy.ma.MaskedArray.__rpow__

MaskedArray.__rpow__(other) [source]

Raise self to the power other, masking the potential NaNs/Infs


numpy.ma.MaskedArray.__lshift__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__rpow__

Next topic

numpy.ma.MaskedArray.__rlshift__

numpy.ma.MaskedArray.__lshift__

MaskedArray.__lshift__

x.__lshift__(y) <==> x<<y


numpy.ma.MaskedArray.__rlshift__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__lshift__

Next topic

numpy.ma.MaskedArray.__rshift__

numpy.ma.MaskedArray.__rlshift__

MaskedArray.__rlshift__

x.__rlshift__(y) <==> y<<x


numpy.ma.MaskedArray.__rshift__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__rlshift__

Next topic

numpy.ma.MaskedArray.__rrshift__

numpy.ma.MaskedArray.__rshift__

MaskedArray.__rshift__

x.__rshift__(y) <==> x>>y


numpy.ma.MaskedArray.__rrshift__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__rshift__

Next topic

numpy.ma.MaskedArray.__and__

numpy.ma.MaskedArray.__rrshift__

MaskedArray.__rrshift__

x.__rrshift__(y) <==> y>>x


numpy.ma.MaskedArray.__and__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__rrshift__

Next topic

numpy.ma.MaskedArray.__rand__

numpy.ma.MaskedArray.__and__

MaskedArray.__and__

x.__and__(y) <==> x&y


numpy.ma.MaskedArray.__rand__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__and__

Next topic

numpy.ma.MaskedArray.__or__

numpy.ma.MaskedArray.__rand__

MaskedArray.__rand__

x.__rand__(y) <==> y&x


numpy.ma.MaskedArray.__or__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__rand__

Next topic

numpy.ma.MaskedArray.__ror__

numpy.ma.MaskedArray.__or__

MaskedArray.__or__

x.__or__(y) <==> x|y


numpy.ma.MaskedArray.__ror__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__or__

Next topic

numpy.ma.MaskedArray.__xor__

numpy.ma.MaskedArray.__ror__

MaskedArray.__ror__

x.__ror__(y) <==> y|x


numpy.ma.MaskedArray.__xor__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__ror__

Next topic

numpy.ma.MaskedArray.__rxor__

numpy.ma.MaskedArray.__xor__

MaskedArray.__xor__

x.__xor__(y) <==> x^y


numpy.ma.MaskedArray.__rxor__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__xor__

Next topic

numpy.ma.MaskedArray.__iadd__

numpy.ma.MaskedArray.__rxor__

MaskedArray.__rxor__

x.__rxor__(y) <==> y^x


numpy.ma.MaskedArray.__iadd__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__rxor__

Next topic

numpy.ma.MaskedArray.__isub__

numpy.ma.MaskedArray.__iadd__

MaskedArray.__iadd__(other) [source]

Add other to self in-place.


numpy.ma.MaskedArray.__isub__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__iadd__

Next topic

numpy.ma.MaskedArray.__imul__

numpy.ma.MaskedArray.__isub__

MaskedArray.__isub__(other) [source]

Subtract other from self in-place.


numpy.ma.MaskedArray.__imul__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__isub__

Next topic

numpy.ma.MaskedArray.__idiv__

numpy.ma.MaskedArray.__imul__

MaskedArray.__imul__(other) [source]

Multiply self by other in-place.


numpy.ma.MaskedArray.__idiv__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__imul__

Next topic

numpy.ma.MaskedArray.__itruediv__

numpy.ma.MaskedArray.__idiv__

MaskedArray.__idiv__(other) [source]

Divide self by other in-place.


numpy.ma.MaskedArray.__itruediv__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__idiv__

Next topic

numpy.ma.MaskedArray.__ifloordiv__

numpy.ma.MaskedArray.__itruediv__

MaskedArray.__itruediv__(other) [source]

True divide self by other in-place.


numpy.ma.MaskedArray.__ifloordiv__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__itruediv__

Next topic

numpy.ma.MaskedArray.__imod__

numpy.ma.MaskedArray.__ifloordiv__

MaskedArray.__ifloordiv__(other) [source]

Floor divide self by other in-place.


numpy.ma.MaskedArray.__imod__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__ifloordiv__

Next topic

numpy.ma.MaskedArray.__ipow__

numpy.ma.MaskedArray.__imod__

MaskedArray.__imod__

x.__imod__(y) <==> x%=y


numpy.ma.MaskedArray.__ipow__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__imod__

Next topic

numpy.ma.MaskedArray.__ilshift__

numpy.ma.MaskedArray.__ipow__

MaskedArray.__ipow__(other) [source]

Raise self to the power other, in place.


numpy.ma.MaskedArray.__ilshift__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__ipow__

Next topic

numpy.ma.MaskedArray.__irshift__

numpy.ma.MaskedArray.__ilshift__

MaskedArray.__ilshift__

x.__ilshift__(y) <==> x<<=y


numpy.ma.MaskedArray.__irshift__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__ilshift__

Next topic

numpy.ma.MaskedArray.__iand__

numpy.ma.MaskedArray.__irshift__

MaskedArray.__irshift__

x.__irshift__(y) <==> x>>=y


numpy.ma.MaskedArray.__iand__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__irshift__

Next topic

numpy.ma.MaskedArray.__ior__

numpy.ma.MaskedArray.__iand__

MaskedArray.__iand__

x.__iand__(y) <==> x&=y


numpy.ma.MaskedArray.__ior__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__iand__

Next topic

numpy.ma.MaskedArray.__ixor__

numpy.ma.MaskedArray.__ior__

MaskedArray.__ior__

x.__ior__(y) <==> x|=y


numpy.ma.MaskedArray.__ixor__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__ior__

Next topic

numpy.ma.MaskedArray.__repr__

numpy.ma.MaskedArray.__ixor__

MaskedArray.__ixor__

x.__ixor__(y) <==> x^=y


numpy.ma.MaskedArray.__repr__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__ixor__

Next topic

numpy.ma.MaskedArray.__str__

numpy.ma.MaskedArray.__repr__

MaskedArray.__repr__() [source]

Literal string representation.


numpy.ma.MaskedArray.__str__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__repr__

Next topic

numpy.ma.MaskedArray.ids

numpy.ma.MaskedArray.__str__

MaskedArray.__str__() [source]

String representation.


numpy.ma.MaskedArray.ids

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__str__

Next topic

numpy.ma.MaskedArray.iscontiguous

numpy.ma.MaskedArray.ids

MaskedArray.ids() [source]

Return the addresses of the data and mask areas.

Parameters: None

Examples

>>> x = np.ma.array([1, 2, 3], mask=[0, 1, 1])
>>> x.ids()
(166670640, 166659832)

If the array has no mask, the address of nomask is returned. This address is typically not close to the data in memory:

>>> x = np.ma.array([1, 2, 3])
>>> x.ids()
(166691080, 3083169284L)


numpy.ma.MaskedArray.iscontiguous

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.ids

Next topic

numpy.ma.MaskedArray.__copy__

numpy.ma.MaskedArray.iscontiguous

MaskedArray.iscontiguous() [source]

Return a boolean indicating whether the data is contiguous.

Parameters: None

Examples

>>> x = np.ma.array([1, 2, 3])
>>> x.iscontiguous()
True

iscontiguous returns one of the flags of the masked array:

>>> x.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : True
  OWNDATA : False
  WRITEABLE : True
  ALIGNED : True
  UPDATEIFCOPY : False


numpy.ma.MaskedArray.__copy__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.iscontiguous

Next topic

numpy.ma.MaskedArray.__deepcopy__

numpy.ma.MaskedArray.__copy__

MaskedArray.__copy__([order])

Return a copy of the array.

Parameters:

order : {‘C’, ‘F’, ‘A’}, optional

If order is ‘C’ (False) then the result is contiguous (default). If order is ‘Fortran’ (True) then the result has fortran order. If order is ‘Any’ (None) then the result has fortran order only if the array already is in fortran order.


numpy.ma.MaskedArray.__deepcopy__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__copy__

Next topic

numpy.ma.MaskedArray.__getstate__

numpy.ma.MaskedArray.__deepcopy__

MaskedArray.__deepcopy__(memo=None) [source]


numpy.ma.MaskedArray.__getstate__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__deepcopy__

Next topic

numpy.ma.MaskedArray.__reduce__

numpy.ma.MaskedArray.__getstate__

MaskedArray.__getstate__() [source]

Return the internal state of the masked array, for pickling purposes.


numpy.ma.MaskedArray.__reduce__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__getstate__

Next topic

numpy.ma.MaskedArray.__setstate__

numpy.ma.MaskedArray.__reduce__

MaskedArray.__reduce__() [source]

Return a 3-tuple for pickling a MaskedArray.


numpy.ma.MaskedArray.__setstate__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__reduce__

Next topic

numpy.ma.MaskedArray.__new__

numpy.ma.MaskedArray.__setstate__

MaskedArray.__setstate__(state) [source]

Restore the internal state of the masked array, for pickling purposes. state is typically the output of the __getstate__ output, and is a 5-tuple:

  • class name
  • a tuple giving the shape of the data
  • a typecode for the data
  • a binary string for the data
  • a binary string for the mask.


numpy.ma.MaskedArray.__new__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__setstate__

Next topic

numpy.ma.MaskedArray.__array__

numpy.ma.MaskedArray.__new__

static MaskedArray.__new__(data=None, mask=False, dtype=None, copy=False, subok=True, ndmin=0, fill_value=None, keep_mask=True, hard_mask=None, shrink=True, **options) [source]

Create a new masked array from scratch.

Notes

A masked array can also be created by taking a .view(MaskedArray).


numpy.ma.MaskedArray.__array__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__new__

Next topic

numpy.ma.MaskedArray.__array_wrap__

numpy.ma.MaskedArray.__array__

MaskedArray.__array__(|dtype) → reference if type unchanged, copy otherwise.

Returns either a new reference to self if dtype is not given or a new array of provided data type if dtype is different from the current dtype of the array.


numpy.ma.MaskedArray.__array_wrap__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__array__

Next topic

numpy.ma.MaskedArray.__len__

numpy.ma.MaskedArray.__array_wrap__

MaskedArray.__array_wrap__(obj, context=None) [source]

Special hook for ufuncs. Wraps the numpy array and sets the mask according to context.


numpy.ma.MaskedArray.__len__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__array_wrap__

Next topic

numpy.ma.MaskedArray.__getitem__

numpy.ma.MaskedArray.__len__

MaskedArray.__len__() <==> len(x)


numpy.ma.MaskedArray.__getitem__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__len__

Next topic

numpy.ma.MaskedArray.__setitem__

numpy.ma.MaskedArray.__getitem__

MaskedArray.__getitem__(indx) [source]

x.__getitem__(y) <==> x[y]

Return the item described by i, as a masked array.


numpy.ma.MaskedArray.__setitem__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__getitem__

Next topic

numpy.ma.MaskedArray.__delitem__

numpy.ma.MaskedArray.__setitem__

MaskedArray.__setitem__(indx, value) [source]

x.__setitem__(i, y) <==> x[i]=y

Set item described by index. If value is masked, masks those locations.


numpy.ma.MaskedArray.__delitem__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__setitem__

Next topic

numpy.ma.MaskedArray.__getslice__

numpy.ma.MaskedArray.__delitem__

MaskedArray.__delitem__

x.__delitem__(y) <==> del x[y]


numpy.ma.MaskedArray.__getslice__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__delitem__

Next topic

numpy.ma.MaskedArray.__setslice__

numpy.ma.MaskedArray.__getslice__

MaskedArray.__getslice__(i, j) [source]

x.__getslice__(i, j) <==> x[i:j]

Return the slice described by (i, j). The use of negative indices is not supported.


numpy.ma.MaskedArray.__setslice__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__getslice__

Next topic

numpy.ma.MaskedArray.__contains__

numpy.ma.MaskedArray.__setslice__

MaskedArray.__setslice__(i, j, value) [source]

x.__setslice__(i, j, value) <==> x[i:j]=value

Set the slice (i,j) of a to value. If value is masked, mask those locations.


numpy.ma.MaskedArray.__contains__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__setslice__

Next topic

numpy.ma.MaskedArray.__setmask__

numpy.ma.MaskedArray.__contains__

MaskedArray.__contains__

x.__contains__(y) <==> y in x


numpy.ma.MaskedArray.__setmask__

  • Array objects
  • Masked arrays
  • Constants of the numpy.ma module
  • index
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.__contains__

Next topic

numpy.ma.MaskedArray.harden_mask

numpy.ma.MaskedArray.__setmask__

MaskedArray.__setmask__(mask, copy=False) [source]

Set the mask.


numpy.ma.MaskedArray.harden_mask

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.soften_mask

Next topic

numpy.ma.MaskedArray.soften_mask

numpy.ma.MaskedArray.harden_mask

MaskedArray.harden_mask() [source]

Force the mask to hard.

Whether the mask of a masked array is hard or soft is determined by its hardmask property. harden_mask sets hardmask to True.

See also

hardmask


numpy.ma.MaskedArray.soften_mask

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.harden_mask

Next topic

numpy.ma.MaskedArray.shrink_mask

numpy.ma.MaskedArray.soften_mask

MaskedArray.soften_mask() [source]

Force the mask to soft.

Whether the mask of a masked array is hard or soft is determined by its hardmask property. soften_mask sets hardmask to False.

See also

hardmask


numpy.ma.MaskedArray.unshare_mask

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.shrink_mask

Next topic

numpy.ma.asarray

numpy.ma.MaskedArray.unshare_mask

MaskedArray.unshare_mask() [source]

Copy the mask and set the sharedmask flag to False.

Whether the mask is shared between masked arrays can be seen from the sharedmask property. unshare_mask ensures the mask is not shared. A copy of the mask is only made if it was shared.

See also

sharedmask


numpy.ma.MaskedArray.shrink_mask

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.soften_mask

Next topic

numpy.ma.MaskedArray.unshare_mask

numpy.ma.MaskedArray.shrink_mask

MaskedArray.shrink_mask() [source]

Reduce a mask to nomask when possible.

Parameters: None
Returns: None

Examples

>>> x = np.ma.array([[1,2 ], [3, 4]], mask=[0]*4)
>>> x.mask
array([[False, False],
       [False, False]], dtype=bool)
>>> x.shrink_mask()
>>> x.mask
False


numpy.ma.MaskedArray.get_fill_value

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.set_fill_value

Next topic

numpy.ma.MaskedArray.set_fill_value

numpy.ma.MaskedArray.get_fill_value

MaskedArray.get_fill_value() [source]

Return the filling value of the masked array.

Returns:

fill_value : scalar

The filling value.

Examples

>>> for dt in [np.int32, np.int64, np.float64, np.complex128]:
...     np.ma.array([0, 1], dtype=dt).get_fill_value()
...
999999
999999
1e+20
(1e+20+0j)

>>> x = np.ma.array([0, 1.], fill_value=-np.inf)
>>> x.get_fill_value()
-inf


numpy.ma.MaskedArray.set_fill_value

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.get_fill_value

Next topic

numpy.ma.MaskedArray.fill_value

numpy.ma.MaskedArray.set_fill_value

MaskedArray.set_fill_value(value=None) [source]

Set the filling value of the masked array.

Parameters:

value : scalar, optional

The new filling value. Default is None, in which case a default based on the data type is used.

See also

ma.set_fill_value
Equivalent function.

Examples

>>> x = np.ma.array([0, 1.], fill_value=-np.inf)
>>> x.fill_value
-inf
>>> x.set_fill_value(np.pi)
>>> x.fill_value
3.1415926535897931

Reset to default:

>>> x.set_fill_value()
>>> x.fill_value
1e+20


numpy.ma.MaskedArray.count

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.any

Next topic

numpy.ma.MaskedArray.nonzero

numpy.ma.MaskedArray.count

MaskedArray.count(axis=None) [source]

Count the non-masked elements of the array along the given axis.

Parameters:

axis : int, optional

Axis along which to count the non-masked elements. If axis is None, all non-masked elements are counted.
Returns:

result : int or ndarray

If axis is None, an integer count is returned. When axis is not None, an array with shape determined by the lengths of the remaining axes, is returned.

See also

count_masked
Count masked elements in array or along a given axis.

Examples

>>> import numpy.ma as ma
>>> a = ma.arange(6).reshape((2, 3))
>>> a[1, :] = ma.masked
>>> a
masked_array(data =
 [[0 1 2]
 [-- -- --]],
             mask =
 [[False False False]
 [ True  True  True]],
       fill_value = 999999)
>>> a.count()
3

When the axis keyword is specified an array of appropriate size is returned.

>>> a.count(axis=0)
array([1, 1, 1])
>>> a.count(axis=1)
array([3, 0])


Masked array operations

  • next
  • previous

Table Of Contents

  • Masked array operations
    • Constants
    • Creation
      • From existing data
      • Ones and zeros
    • Inspecting the array
    • Manipulating a MaskedArray
      • Changing the shape
      • Modifying axes
      • Changing the number of dimensions
      • Joining arrays
    • Operations on masks
      • Creating a mask
      • Accessing a mask
      • Finding masked data
      • Modifying a mask
    • Conversion operations
      • > to a masked array
      • > to a ndarray
      • > to another object
      • Pickling and unpickling
      • Filling a masked array
    • Masked arrays arithmetics
      • Arithmetics
      • Minimum/maximum
      • Sorting
      • Algebra
      • Polynomial fit
      • Clipping and rounding
      • Miscellanea

Previous topic

numpy.not_equal

Next topic

numpy.ma.MaskType

Masked array operations

Constants

ma.MaskType alias of bool_

Creation

From existing data

ma.masked_array | alias of MaskedArray
ma.array(data[, dtype, copy, order, mask, ...]) | An array class with possibly masked values.
ma.copy | copy
ma.frombuffer(buffer[, dtype, count, offset]) | Interpret a buffer as a 1-dimensional array.
ma.fromfunction(function, shape, **kwargs) | Construct an array by executing a function over each coordinate.
ma.MaskedArray.copy([order]) | Return a copy of the array.

Ones and zeros

ma.empty(shape[, dtype, order]) | Return a new array of given shape and type, without initializing entries.
ma.empty_like(a[, dtype, order, subok]) | Return a new array with the same shape and type as a given array.
ma.masked_all(shape[, dtype]) | Empty masked array with all elements masked.
ma.masked_all_like(arr) | Empty masked array with the properties of an existing array.
ma.ones(shape[, dtype, order]) | Return a new array of given shape and type, filled with ones.
ma.zeros(shape[, dtype, order]) | Return a new array of given shape and type, filled with zeros.

Inspecting the array

ma.all(self[, axis, out]) | Check if all of the elements of a are true.
ma.any(self[, axis, out]) | Check if any of the elements of a are true.
ma.count(a[, axis]) | Count the non-masked elements of the array along the given axis.
ma.count_masked(arr[, axis]) | Count the number of masked elements along the given axis.
ma.getmask(a) | Return the mask of a masked array, or nomask.
ma.getmaskarray(arr) | Return the mask of a masked array, or full boolean array of False.
ma.getdata(a[, subok]) | Return the data of a masked array as an ndarray.
ma.nonzero(self) | Return the indices of unmasked elements that are not zero.
ma.shape(obj) | Return the shape of an array.
ma.size(obj[, axis]) | Return the number of elements along a given axis.
ma.is_masked(x) | Determine whether input has masked values.
ma.is_mask(m) | Return True if m is a valid, standard mask.
ma.MaskedArray.data | Return the current data, as a view of the original underlying data.
ma.MaskedArray.mask | Mask
ma.MaskedArray.recordmask | Return the mask of the records.
ma.MaskedArray.all([axis, out]) | Check if all of the elements of a are true.
ma.MaskedArray.any([axis, out]) | Check if any of the elements of a are true.
ma.MaskedArray.count([axis]) | Count the non-masked elements of the array along the given axis.
ma.MaskedArray.nonzero() | Return the indices of unmasked elements that are not zero.
ma.shape(obj) | Return the shape of an array.
ma.size(obj[, axis]) | Return the number of elements along a given axis.

Manipulating a MaskedArray

Changing the shape

ma.ravel(self) | Returns a 1D version of self, as a view.
ma.reshape(a, new_shape[, order]) | Returns an array containing the same data with a new shape.
ma.resize(x, new_shape) | Return a new masked array with the specified size and shape.
ma.MaskedArray.flatten([order]) | Return a copy of the array collapsed into one dimension.
ma.MaskedArray.ravel() | Returns a 1D version of self, as a view.
ma.MaskedArray.reshape(*s, **kwargs) | Give a new shape to the array without changing its data.
ma.MaskedArray.resize(newshape[, refcheck, ...]) |

Modifying axes

ma.swapaxes | swapaxes
ma.transpose(a[, axes]) | Permute the dimensions of an array.
ma.MaskedArray.swapaxes(axis1, axis2) | Return a view of the array with axis1 and axis2 interchanged.
ma.MaskedArray.transpose(*axes) | Returns a view of the array with axes transposed.

Changing the number of dimensions

ma.atleast_1d(*arys) | Convert inputs to arrays with at least one dimension.
ma.atleast_2d(*arys) | View inputs as arrays with at least two dimensions.
ma.atleast_3d(*arys) | View inputs as arrays with at least three dimensions.
ma.expand_dims(x, axis) | Expand the shape of an array.
ma.squeeze(a[, axis]) | Remove single-dimensional entries from the shape of an array.
ma.MaskedArray.squeeze([axis]) | Remove single-dimensional entries from the shape of a.
ma.column_stack(tup) | Stack 1-D arrays as columns into a 2-D array.
ma.concatenate(arrays[, axis]) | Concatenate a sequence of arrays along the given axis.
ma.dstack(tup) | Stack arrays in sequence depth wise (along third axis).
ma.hstack(tup) | Stack arrays in sequence horizontally (column wise).
ma.hsplit(ary, indices_or_sections) | Split an array into multiple sub-arrays horizontally (column-wise).
ma.mr_ | Translate slice objects to concatenation along the first axis.
ma.row_stack(tup) | Stack arrays in sequence vertically (row wise).
ma.vstack(tup) | Stack arrays in sequence vertically (row wise).

Joining arrays

ma.column_stack(tup) | Stack 1-D arrays as columns into a 2-D array.
ma.concatenate(arrays[, axis]) | Concatenate a sequence of arrays along the given axis.
ma.append(a, b[, axis]) | Append values to the end of an array.
ma.dstack(tup) | Stack arrays in sequence depth wise (along third axis).
ma.hstack(tup) | Stack arrays in sequence horizontally (column wise).
ma.vstack(tup) | Stack arrays in sequence vertically (row wise).

Operations on masks

Creating a mask

ma.make_mask(m[, copy, shrink, dtype]) | Create a boolean mask from an array.
ma.make_mask_none(newshape[, dtype]) | Return a boolean mask of the given shape, filled with False.
ma.mask_or(m1, m2[, copy, shrink]) | Combine two masks with the logical_or operator.
ma.make_mask_descr(ndtype) | Construct a dtype description list from a given dtype.

Accessing a mask

ma.getmask(a) | Return the mask of a masked array, or nomask.
ma.getmaskarray(arr) | Return the mask of a masked array, or full boolean array of False.
ma.masked_array.mask | Mask

Finding masked data

ma.flatnotmasked_contiguous(a) | Find contiguous unmasked data in a masked array along the given axis.
ma.flatnotmasked_edges(a) | Find the indices of the first and last unmasked values.
ma.notmasked_contiguous(a[, axis]) | Find contiguous unmasked data in a masked array along the given axis.
ma.notmasked_edges(a[, axis]) | Find the indices of the first and last unmasked values along an axis.

Modifying a mask

ma.mask_cols(a[, axis]) | Mask columns of a 2D array that contain masked values.
ma.mask_or(m1, m2[, copy, shrink]) | Combine two masks with the logical_or operator.
ma.mask_rowcols(a[, axis]) | Mask rows and/or columns of a 2D array that contain masked values.
ma.mask_rows(a[, axis]) | Mask rows of a 2D array that contain masked values.
ma.harden_mask(self) | Force the mask to hard.
ma.soften_mask(self) | Force the mask to soft.
ma.MaskedArray.harden_mask() | Force the mask to hard.
ma.MaskedArray.soften_mask() | Force the mask to soft.
ma.MaskedArray.shrink_mask() | Reduce a mask to nomask when possible.
ma.MaskedArray.unshare_mask() | Copy the mask and set the sharedmask flag to False.

Conversion operations

> to a masked array

ma.asarray(a[, dtype, order]) | Convert the input to a masked array of the given data-type.
ma.asanyarray(a[, dtype]) | Convert the input to a masked array, conserving subclasses.
ma.fix_invalid(a[, mask, copy, fill_value]) | Return input with invalid data masked and replaced by a fill value.
ma.masked_equal(x, value[, copy]) | Mask an array where equal to a given value.
ma.masked_greater(x, value[, copy]) | Mask an array where greater than a given value.
ma.masked_greater_equal(x, value[, copy]) | Mask an array where greater than or equal to a given value.
ma.masked_inside(x, v1, v2[, copy]) | Mask an array inside a given interval.
ma.masked_invalid(a[, copy]) | Mask an array where invalid values occur (NaNs or infs).
ma.masked_less(x, value[, copy]) | Mask an array where less than a given value.
ma.masked_less_equal(x, value[, copy]) | Mask an array where less than or equal to a given value.
ma.masked_not_equal(x, value[, copy]) | Mask an array where not equal to a given value.
ma.masked_object(x, value[, copy, shrink]) | Mask the array x where the data are exactly equal to value.
ma.masked_outside(x, v1, v2[, copy]) | Mask an array outside a given interval.
ma.masked_values(x, value[, rtol, atol, ...]) | Mask using floating point equality.
ma.masked_where(condition, a[, copy]) | Mask an array where a condition is met.

> to a ndarray

ma.compress_cols(a) | Suppress whole columns of a 2-D array that contain masked values.
ma.compress_rowcols(x[, axis]) | Suppress the rows and/or columns of a 2-D array that contain masked values.
ma.compress_rows(a) | Suppress whole rows of a 2-D array that contain masked values.
ma.compressed(x) | Return all the non-masked data as a 1-D array.
ma.filled(a[, fill_value]) | Return input as an array with masked data replaced by a fill value.
ma.MaskedArray.compressed() | Return all the non-masked data as a 1-D array.
ma.MaskedArray.filled([fill_value]) | Return a copy of self, with masked values filled with a given value.

> to another object

ma.MaskedArray.tofile(fid[, sep, format]) | Save a masked array to a file in binary format.
ma.MaskedArray.tolist([fill_value]) | Return the data portion of the masked array as a hierarchical Python list.
ma.MaskedArray.torecords() | Transforms a masked array into a flexible-type array.
ma.MaskedArray.tobytes([fill_value, order]) | Return the array data as a string containing the raw bytes in the array.

Pickling and unpickling

ma.dump(a, F) | Pickle a masked array to a file.
ma.dumps(a) | Return a string corresponding to the pickling of a masked array.
ma.load(F) | Wrapper around cPickle.load which accepts either a file-like object or a filename.
ma.loads(strg) | Load a pickle from the current string.

Filling a masked array

ma.common_fill_value(a, b) | Return the common filling value of two masked arrays, if any.
ma.default_fill_value(obj) | Return the default fill value for the argument object.
ma.maximum_fill_value(obj) | Return the minimum value that can be represented by the dtype of an object.
ma.maximum_fill_value(obj) | Return the minimum value that can be represented by the dtype of an object.
ma.set_fill_value(a, fill_value) | Set the filling value of a, if a is a masked array.
ma.MaskedArray.get_fill_value() | Return the filling value of the masked array.
ma.MaskedArray.set_fill_value([value]) | Set the filling value of the masked array.
ma.MaskedArray.fill_value | Filling value.

Masked arrays arithmetics

Arithmetics

ma.anom(self[, axis, dtype]) | Compute the anomalies (deviations from the arithmetic mean) along the given axis.
ma.anomalies(self[, axis, dtype]) | Compute the anomalies (deviations from the arithmetic mean) along the given axis.
ma.average(a[, axis, weights, returned]) | Return the weighted average of array over the given axis.
ma.conjugate(x[, out]) | Return the complex conjugate, element-wise.
ma.corrcoef(x[, y, rowvar, bias, ...]) | Return correlation coefficients of the input array.
ma.cov(x[, y, rowvar, bias, allow_masked, ddof]) | Estimate the covariance matrix.
ma.cumsum(self[, axis, dtype, out]) | Return the cumulative sum of the elements along the given axis.
ma.cumprod(self[, axis, dtype, out]) | Return the cumulative product of the elements along the given axis.
ma.mean(self[, axis, dtype, out]) | Returns the average of the array elements.
ma.median(a[, axis, out, overwrite_input]) | Compute the median along the specified axis.
ma.power(a, b[, third]) | Returns element-wise base array raised to power from second array.
ma.prod(self[, axis, dtype, out]) | Return the product of the array elements over the given axis.
ma.std(self[, axis, dtype, out, ddof]) | Compute the standard deviation along the specified axis.
ma.sum(self[, axis, dtype, out]) | Return the sum of the array elements over the given axis.
ma.var(self[, axis, dtype, out, ddof]) | Compute the variance along the specified axis.
ma.MaskedArray.anom([axis, dtype]) | Compute the anomalies (deviations from the arithmetic mean) along the given axis.
ma.MaskedArray.cumprod([axis, dtype, out]) | Return the cumulative product of the elements along the given axis.
ma.MaskedArray.cumsum([axis, dtype, out]) | Return the cumulative sum of the elements along the given axis.
ma.MaskedArray.mean([axis, dtype, out]) | Returns the average of the array elements.
ma.MaskedArray.prod([axis, dtype, out]) | Return the product of the array elements over the given axis.
ma.MaskedArray.std([axis, dtype, out, ddof]) | Compute the standard deviation along the specified axis.
ma.MaskedArray.sum([axis, dtype, out]) | Return the sum of the array elements over the given axis.
ma.MaskedArray.var([axis, dtype, out, ddof]) | Compute the variance along the specified axis.

Minimum/maximum

ma.argmax(a[, axis, fill_value]) | Returns array of indices of the maximum values along the given axis.
ma.argmin(a[, axis, fill_value]) | Return array of indices to the minimum values along the given axis.
ma.max(obj[, axis, out, fill_value]) | Return the maximum along a given axis.
ma.min(obj[, axis, out, fill_value]) | Return the minimum along a given axis.
ma.ptp(obj[, axis, out, fill_value]) | Return (maximum - minimum) along the the given dimension (i.e.
ma.MaskedArray.argmax([axis, fill_value, out]) | Returns array of indices of the maximum values along the given axis.
ma.MaskedArray.argmin([axis, fill_value, out]) | Return array of indices to the minimum values along the given axis.
ma.MaskedArray.max([axis, out, fill_value]) | Return the maximum along a given axis.
ma.MaskedArray.min([axis, out, fill_value]) | Return the minimum along a given axis.
ma.MaskedArray.ptp([axis, out, fill_value]) | Return (maximum - minimum) along the the given dimension (i.e.

Sorting

ma.argsort(a[, axis, kind, order, fill_value]) | Return an ndarray of indices that sort the array along the specified axis.
ma.sort(a[, axis, kind, order, endwith, ...]) | Sort the array, in-place
ma.MaskedArray.argsort([axis, kind, order, ...]) | Return an ndarray of indices that sort the array along the specified axis.
ma.MaskedArray.sort([axis, kind, order, ...]) | Sort the array, in-place

Algebra

ma.diag(v[, k]) | Extract a diagonal or construct a diagonal array.
ma.dot(a, b[, strict]) | Return the dot product of two arrays.
ma.identity(n[, dtype]) | Return the identity array.
ma.inner(a, b) | Inner product of two arrays.
ma.innerproduct(a, b) | Inner product of two arrays.
ma.outer(a, b) | Compute the outer product of two vectors.
ma.outerproduct(a, b) | Compute the outer product of two vectors.
ma.trace(self[, offset, axis1, axis2, ...]) | Return the sum along diagonals of the array.
ma.transpose(a[, axes]) | Permute the dimensions of an array.
ma.MaskedArray.trace([offset, axis1, axis2, ...]) | Return the sum along diagonals of the array.
ma.MaskedArray.transpose(*axes) | Returns a view of the array with axes transposed.

Polynomial fit

ma.vander(x[, n]) | Generate a Vandermonde matrix.
ma.polyfit(x, y, deg[, rcond, full, w, cov]) | Least squares polynomial fit.

Clipping and rounding

ma.around | Round an array to the given number of decimals.
ma.clip(a, a_min, a_max[, out]) | Clip (limit) the values in an array.
ma.round(a[, decimals, out]) | Return a copy of a, rounded to ‘decimals’ places.
ma.MaskedArray.clip(a_min, a_max[, out]) | Return an array whose values are limited to [a_min, a_max].
ma.MaskedArray.round([decimals, out]) | Return a with each element rounded to the given number of decimals.

Miscellanea

ma.allequal(a, b[, fill_value]) | Return True if all entries of a and b are equal, using fill_value as a truth value where either or both are masked.
ma.allclose(a, b[, masked_equal, rtol, atol]) | Returns True if two arrays are element-wise equal within a tolerance.
ma.apply_along_axis(func1d, axis, arr, ...) | Apply a function to 1-D slices along the given axis.
ma.arange([start,] stop[, step,][, dtype]) | Return evenly spaced values within a given interval.
ma.choose(indices, choices[, out, mode]) | Use an index array to construct a new array from a set of choices.
ma.ediff1d(arr[, to_end, to_begin]) | Compute the differences between consecutive elements of an array.
ma.indices(dimensions[, dtype]) | Return an array representing the indices of a grid.
ma.where(condition[, x, y]) | Return a masked array with elements from x or y, depending on condition.


numpy.ma.MaskType

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.where

Next topic

numpy.ma.masked_array

numpy.ma.MaskType

numpy.ma.MaskType [source]

alias of bool_


numpy.ma.copy

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.array

Next topic

numpy.ma.frombuffer

numpy.ma.copy

numpy.ma.copy = <numpy.ma.core._frommethod instance at 0x00000000048E4848>

copy a.copy(order=’C’)

Return a copy of the array.
Parameters:

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout of the copy. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible. (Note that this function and :func:numpy.copy are very similar, but have different default values for their order= arguments.)

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
       [0, 0, 0]])

>>> y
array([[1, 2, 3],
       [4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True


numpy.ma.frombuffer

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.copy

Next topic

numpy.ma.fromfunction

numpy.ma.frombuffer

numpy.ma.frombuffer(buffer, dtype=float, count=-1, offset=0) = <numpy.ma.core._convert2ma instance at 0x00000000048F1288>

Interpret a buffer as a 1-dimensional array.

Parameters:

buffer : buffer_like

An object that exposes the buffer interface.

dtype : data-type, optional

Data-type of the returned array; default: float.

count : int, optional

Number of items to read. -1 means all data in the buffer.

offset : int, optional

Start reading the buffer from this offset; default: 0.

Notes

If the buffer has data that is not in machine byte-order, this should be specified as part of the data-type, e.g.:

>>> dt = np.dtype(int)
>>> dt = dt.newbyteorder('>')
>>> np.frombuffer(buf, dtype=dt)

The data of the resulting array will not be byteswapped, but will be interpreted correctly.

Examples

>>> s = 'hello world'
>>> np.frombuffer(s, dtype='S1', count=5, offset=6)
array(['w', 'o', 'r', 'l', 'd'],
      dtype='|S1')


numpy.ma.fromfunction

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.frombuffer

Next topic

numpy.ma.MaskedArray.copy

numpy.ma.fromfunction

numpy.ma.fromfunction(function, shape, **kwargs) = <numpy.ma.core._convert2ma instance at 0x00000000048F12C8>

Construct an array by executing a function over each coordinate.

The resulting array therefore has a value fn(x, y, z) at coordinate (x, y, z).

Parameters:

function : callable

The function is called with N parameters, where N is the rank of shape. Each parameter represents the coordinates of the array varying along a specific axis. For example, if shape were (2, 2), then the parameters in turn be (0, 0), (0, 1), (1, 0), (1, 1).

shape : (N,) tuple of ints

Shape of the output array, which also determines the shape of the coordinate arrays passed to function.

dtype : data-type, optional

Data-type of the coordinate arrays passed to function. By default, dtype is float.
Returns:

fromfunction : any

The result of the call to function is passed back directly. Therefore the shape of fromfunction is completely determined by function. If function returns a scalar value, the shape of fromfunction would match the shape parameter.

See also

indices, meshgrid

Notes

Keywords other than dtype are passed to function.

Examples

>>> np.fromfunction(lambda i, j: i == j, (3, 3), dtype=int)
array([[ True, False, False],
       [False,  True, False],
       [False, False,  True]], dtype=bool)

>>> np.fromfunction(lambda i, j: i + j, (3, 3), dtype=int)
array([[0, 1, 2],
       [1, 2, 3],
       [2, 3, 4]])


numpy.ma.empty

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.copy

Next topic

numpy.ma.empty_like

numpy.ma.empty

numpy.ma.empty(shape, dtype=float, order='C') = <numpy.ma.core._convert2ma instance at 0x00000000048F11C8>

Return a new array of given shape and type, without initializing entries.

Parameters:

shape : int or tuple of int

Shape of the empty array

dtype : data-type, optional

Desired output data-type.

order : {‘C’, ‘F’}, optional

Whether to store multi-dimensional data in C (row-major) or Fortran (column-major) order in memory.
Returns:

out : ndarray

Array of uninitialized (arbitrary) data with the given shape, dtype, and order.

See also

empty_like, zeros, ones

Notes

empty, unlike zeros, does not set the array values to zero, and may therefore be marginally faster. On the other hand, it requires the user to manually set all the values in the array, and should be used with caution.

Examples

>>> np.empty([2, 2])
array([[ -9.74499359e+001,   6.69583040e-309],
       [  2.13182611e-314,   3.06959433e-309]])         #random

>>> np.empty([2, 2], dtype=int)
array([[-1073741821, -1067949133],
       [  496041986,    19249760]])                     #random


numpy.ma.empty_like

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.empty

Next topic

numpy.ma.masked_all

numpy.ma.empty_like

numpy.ma.empty_like(a, dtype=None, order='K', subok=True) = <numpy.ma.core._convert2ma instance at 0x00000000048F1248>

Return a new array with the same shape and type as a given array.

Parameters:

a : array_like

The shape and data-type of a define these same attributes of the returned array.

dtype : data-type, optional

New in version 1.6.0.

Overrides the data type of the result.

order : {‘C’, ‘F’, ‘A’, or ‘K’}, optional

New in version 1.6.0.

Overrides the memory layout of the result. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible.

subok : bool, optional.

If True, then the newly created array will use the sub-class type of ‘a’, otherwise it will be a base-class array. Defaults to True.
Returns:

out : ndarray

Array of uninitialized (arbitrary) data with the same shape and type as a.

See also

ones_like
Return an array of ones with shape and type of input.
zeros_like
Return an array of zeros with shape and type of input.
empty
Return a new uninitialized array.
ones
Return a new array setting values to one.
zeros
Return a new array setting values to zero.

Notes

This function does not initialize the returned array; to do that use zeros_like or ones_like instead. It may be marginally faster than the functions that do set the array values.

Examples

>>> a = ([1,2,3], [4,5,6])                         # a is array-like
>>> np.empty_like(a)
array([[-1073741821, -1073741821,           3],    #random
       [          0,           0, -1073741821]])
>>> a = np.array([[1., 2., 3.],[4.,5.,6.]])
>>> np.empty_like(a)
array([[ -2.00000715e+000,   1.48219694e-323,  -2.00000572e+000],#random
       [  4.38791518e-305,  -2.00000715e+000,   4.17269252e-309]])


numpy.ma.masked_all

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.empty_like

Next topic

numpy.ma.masked_all_like

numpy.ma.masked_all

numpy.ma.masked_all(shape, dtype=<type 'float'>) [source]

Empty masked array with all elements masked.

Return an empty masked array of the given shape and dtype, where all the data are masked.

Parameters:

shape : tuple

Shape of the required MaskedArray.

dtype : dtype, optional

Data type of the output.
Returns:

a : MaskedArray

A masked array with all data masked.

See also

masked_all_like
Empty masked array modelled on an existing array.

Examples

>>> import numpy.ma as ma
>>> ma.masked_all((3, 3))
masked_array(data =
 [[-- -- --]
 [-- -- --]
 [-- -- --]],
      mask =
 [[ True  True  True]
 [ True  True  True]
 [ True  True  True]],
      fill_value=1e+20)

The dtype parameter defines the underlying data type.

>>> a = ma.masked_all((3, 3))
>>> a.dtype
dtype('float64')
>>> a = ma.masked_all((3, 3), dtype=np.int32)
>>> a.dtype
dtype('int32')


numpy.ma.masked_all_like

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_all

Next topic

numpy.ma.ones

numpy.ma.masked_all_like

numpy.ma.masked_all_like(arr) [source]

Empty masked array with the properties of an existing array.

Return an empty masked array of the same shape and dtype as the array arr, where all the data are masked.

Parameters:

arr : ndarray

An array describing the shape and dtype of the required MaskedArray.
Returns:

a : MaskedArray

A masked array with all data masked.
Raises:

AttributeError

If arr doesn’t have a shape attribute (i.e. not an ndarray)

See also

masked_all
Empty masked array with all elements masked.

Examples

>>> import numpy.ma as ma
>>> arr = np.zeros((2, 3), dtype=np.float32)
>>> arr
array([[ 0.,  0.,  0.],
       [ 0.,  0.,  0.]], dtype=float32)
>>> ma.masked_all_like(arr)
masked_array(data =
 [[-- -- --]
 [-- -- --]],
      mask =
 [[ True  True  True]
 [ True  True  True]],
      fill_value=1e+20)

The dtype of the masked array matches the dtype of arr.

>>> arr.dtype
dtype('float32')
>>> ma.masked_all_like(arr).dtype
dtype('float32')


numpy.ma.ones

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_all_like

Next topic

numpy.ma.zeros

numpy.ma.ones

numpy.ma.ones(shape, dtype=None, order='C') = <numpy.ma.core._convert2ma instance at 0x00000000048F1388>

Return a new array of given shape and type, filled with ones.

Parameters:

shape : int or sequence of ints

Shape of the new array, e.g., (2, 3) or 2.

dtype : data-type, optional

The desired data-type for the array, e.g., numpy.int8. Default is numpy.float64.

order : {‘C’, ‘F’}, optional

Whether to store multidimensional data in C- or Fortran-contiguous (row- or column-wise) order in memory.
Returns:

out : ndarray

Array of ones with the given shape, dtype, and order.

See also

zeros, ones_like

Examples

>>> np.ones(5)
array([ 1.,  1.,  1.,  1.,  1.])

>>> np.ones((5,), dtype=np.int)
array([1, 1, 1, 1, 1])

>>> np.ones((2, 1))
array([[ 1.],
       [ 1.]])

>>> s = (2,2)
>>> np.ones(s)
array([[ 1.,  1.],
       [ 1.,  1.]])


numpy.ma.zeros

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.ones

Next topic

numpy.ma.all

numpy.ma.zeros

numpy.ma.zeros(shape, dtype=float, order='C') = <numpy.ma.core._convert2ma instance at 0x00000000048F1448>

Return a new array of given shape and type, filled with zeros.

Parameters:

shape : int or sequence of ints

Shape of the new array, e.g., (2, 3) or 2.

dtype : data-type, optional

The desired data-type for the array, e.g., numpy.int8. Default is numpy.float64.

order : {‘C’, ‘F’}, optional

Whether to store multidimensional data in C- or Fortran-contiguous (row- or column-wise) order in memory.
Returns:

out : ndarray

Array of zeros with the given shape, dtype, and order.

See also

zeros_like
Return an array of zeros with shape and type of input.
ones_like
Return an array of ones with shape and type of input.
empty_like
Return an empty array with shape and type of input.
ones
Return a new array setting values to one.
empty
Return a new uninitialized array.

Examples

>>> np.zeros(5)
array([ 0.,  0.,  0.,  0.,  0.])

>>> np.zeros((5,), dtype=numpy.int)
array([0, 0, 0, 0, 0])

>>> np.zeros((2, 1))
array([[ 0.],
       [ 0.]])

>>> s = (2,2)
>>> np.zeros(s)
array([[ 0.,  0.],
       [ 0.,  0.]])

>>> np.zeros((2,), dtype=[('x', 'i4'), ('y', 'i4')]) # custom dtype
array([(0, 0), (0, 0)],
      dtype=[('x', '<i4'), ('y', '<i4')])


numpy.ma.all

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.zeros

Next topic

numpy.ma.any

numpy.ma.all

numpy.ma.all(self, axis=None, out=None) = <numpy.ma.core._frommethod instance at 0x00000000048E4488>

Check if all of the elements of a are true.

Performs a logical_and over the given axis and returns the result. Masked values are considered as True during computation. For convenience, the output array is masked where ALL the values along the current axis are masked: if the output would have been a scalar and that all the values are masked, then the output is masked.

Parameters:

axis : {None, integer}

Axis to perform the operation over. If None, perform over flattened array.

out : {None, array}, optional

Array into which the result can be placed. Its type is preserved and it must be of the right shape to hold the output.

See also

all
equivalent function

Examples

>>> np.ma.array([1,2,3]).all()
True
>>> a = np.ma.array([1,2,3], mask=True)
>>> (a.all() is np.ma.masked)
True


numpy.ma.any

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.all

Next topic

numpy.ma.count

numpy.ma.any

numpy.ma.any(self, axis=None, out=None) = <numpy.ma.core._frommethod instance at 0x00000000048E4648>

Check if any of the elements of a are true.

Performs a logical_or over the given axis and returns the result. Masked values are considered as False during computation.

Parameters:

axis : {None, integer}

Axis to perform the operation over. If None, perform over flattened array and return a scalar.

out : {None, array}, optional

Array into which the result can be placed. Its type is preserved and it must be of the right shape to hold the output.

See also

any
equivalent function


numpy.ma.count

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.any

Next topic

numpy.ma.count_masked

numpy.ma.count

numpy.ma.count(a, axis=None) [source]

Count the non-masked elements of the array along the given axis.

Parameters:

axis : int, optional

Axis along which to count the non-masked elements. If axis is None, all non-masked elements are counted.
Returns:

result : int or ndarray

If axis is None, an integer count is returned. When axis is not None, an array with shape determined by the lengths of the remaining axes, is returned.

See also

count_masked
Count masked elements in array or along a given axis.

Examples

>>> import numpy.ma as ma
>>> a = ma.arange(6).reshape((2, 3))
>>> a[1, :] = ma.masked
>>> a
masked_array(data =
 [[0 1 2]
 [-- -- --]],
             mask =
 [[False False False]
 [ True  True  True]],
       fill_value = 999999)
>>> a.count()
3

When the axis keyword is specified an array of appropriate size is returned.

>>> a.count(axis=0)
array([1, 1, 1])
>>> a.count(axis=1)
array([3, 0])


numpy.ma.count_masked

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.count

Next topic

numpy.ma.getmask

numpy.ma.count_masked

numpy.ma.count_masked(arr, axis=None) [source]

Count the number of masked elements along the given axis.

Parameters:

arr : array_like

An array with (possibly) masked elements.

axis : int, optional

Axis along which to count. If None (default), a flattened version of the array is used.
Returns:

count : int, ndarray

The total number of masked elements (axis=None) or the number of masked elements along each slice of the given axis.

See also

MaskedArray.count
Count non-masked elements.

Examples

>>> import numpy.ma as ma
>>> a = np.arange(9).reshape((3,3))
>>> a = ma.array(a)
>>> a[1, 0] = ma.masked
>>> a[1, 2] = ma.masked
>>> a[2, 1] = ma.masked
>>> a
masked_array(data =
 [[0 1 2]
 [-- 4 --]
 [6 -- 8]],
      mask =
 [[False False False]
 [ True False  True]
 [False  True False]],
      fill_value=999999)
>>> ma.count_masked(a)
3

When the axis keyword is used an array is returned.

>>> ma.count_masked(a, axis=0)
array([1, 1, 1])
>>> ma.count_masked(a, axis=1)
array([0, 2, 1])


numpy.ma.getmask

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.make_mask_descr

Next topic

numpy.ma.getmaskarray

numpy.ma.getmask

numpy.ma.getmask(a) [source]

Return the mask of a masked array, or nomask.

Return the mask of a as an ndarray if a is a MaskedArray and the mask is not nomask, else return nomask. To guarantee a full array of booleans of the same shape as a, use getmaskarray.

Parameters:

a : array_like

Input MaskedArray for which the mask is required.

See also

getdata
Return the data of a masked array as an ndarray.
getmaskarray
Return the mask of a masked array, or full array of False.

Examples

>>> import numpy.ma as ma
>>> a = ma.masked_equal([[1,2],[3,4]], 2)
>>> a
masked_array(data =
 [[1 --]
 [3 4]],
      mask =
 [[False  True]
 [False False]],
      fill_value=999999)
>>> ma.getmask(a)
array([[False,  True],
       [False, False]], dtype=bool)

Equivalently use the MaskedArray mask attribute.

>>> a.mask
array([[False,  True],
       [False, False]], dtype=bool)

Result when mask == nomask

>>> b = ma.masked_array([[1,2],[3,4]])
>>> b
masked_array(data =
 [[1 2]
 [3 4]],
      mask =
 False,
      fill_value=999999)
>>> ma.nomask
False
>>> ma.getmask(b) == ma.nomask
True
>>> b.mask == ma.nomask
True


numpy.ma.getmaskarray

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.getmask

Next topic

numpy.ma.masked_array.mask

numpy.ma.getmaskarray

numpy.ma.getmaskarray(arr) [source]

Return the mask of a masked array, or full boolean array of False.

Return the mask of arr as an ndarray if arr is a MaskedArray and the mask is not nomask, else return a full boolean array of False of the same shape as arr.

Parameters:

arr : array_like

Input MaskedArray for which the mask is required.

See also

getmask
Return the mask of a masked array, or nomask.
getdata
Return the data of a masked array as an ndarray.

Examples

>>> import numpy.ma as ma
>>> a = ma.masked_equal([[1,2],[3,4]], 2)
>>> a
masked_array(data =
 [[1 --]
 [3 4]],
      mask =
 [[False  True]
 [False False]],
      fill_value=999999)
>>> ma.getmaskarray(a)
array([[False,  True],
       [False, False]], dtype=bool)

Result when mask == nomask

>>> b = ma.masked_array([[1,2],[3,4]])
>>> b
masked_array(data =
 [[1 2]
 [3 4]],
      mask =
 False,
      fill_value=999999)
>>> >ma.getmaskarray(b)
array([[False, False],
       [False, False]], dtype=bool)


numpy.ma.getdata

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.getmaskarray

Next topic

numpy.ma.nonzero

numpy.ma.getdata

numpy.ma.getdata(a, subok=True) [source]

Return the data of a masked array as an ndarray.

Return the data of a (if any) as an ndarray if a is a MaskedArray, else return a as a ndarray or subclass (depending on subok) if not.

Parameters:

a : array_like

Input MaskedArray, alternatively a ndarray or a subclass thereof.

subok : bool

Whether to force the output to be a pure ndarray (False) or to return a subclass of ndarray if appropriate (True, default).

See also

getmask
Return the mask of a masked array, or nomask.
getmaskarray
Return the mask of a masked array, or full array of False.

Examples

>>> import numpy.ma as ma
>>> a = ma.masked_equal([[1,2],[3,4]], 2)
>>> a
masked_array(data =
 [[1 --]
 [3 4]],
      mask =
 [[False  True]
 [False False]],
      fill_value=999999)
>>> ma.getdata(a)
array([[1, 2],
       [3, 4]])

Equivalently use the MaskedArray data attribute.

>>> a.data
array([[1, 2],
       [3, 4]])


numpy.ma.nonzero

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.getdata

Next topic

numpy.ma.shape

numpy.ma.nonzero

numpy.ma.nonzero(self) = <numpy.ma.core._frommethod instance at 0x00000000048E4A48>

Return the indices of unmasked elements that are not zero.

Returns a tuple of arrays, one for each dimension, containing the indices of the non-zero elements in that dimension. The corresponding non-zero values can be obtained with:

a[a.nonzero()]

To group the indices by element, rather than dimension, use instead:

np.transpose(a.nonzero())

The result of this is always a 2d array, with a row for each non-zero element.

Parameters:

None
Returns:

tuple_of_arrays : tuple

Indices of elements that are non-zero.

See also

numpy.nonzero
Function operating on ndarrays.
flatnonzero
Return indices that are non-zero in the flattened version of the input array.
ndarray.nonzero
Equivalent ndarray method.
count_nonzero
Counts the number of non-zero elements in the input array.

Examples

>>> import numpy.ma as ma
>>> x = ma.array(np.eye(3))
>>> x
masked_array(data =
 [[ 1.  0.  0.]
 [ 0.  1.  0.]
 [ 0.  0.  1.]],
      mask =
 False,
      fill_value=1e+20)
>>> x.nonzero()
(array([0, 1, 2]), array([0, 1, 2]))

Masked elements are ignored.

>>> x[1, 1] = ma.masked
>>> x
masked_array(data =
 [[1.0 0.0 0.0]
 [0.0 -- 0.0]
 [0.0 0.0 1.0]],
      mask =
 [[False False False]
 [False  True False]
 [False False False]],
      fill_value=1e+20)
>>> x.nonzero()
(array([0, 2]), array([0, 2]))

Indices can also be grouped by element.

>>> np.transpose(x.nonzero())
array([[0, 0],
       [2, 2]])

A common use for nonzero is to find the indices of an array, where a condition is True. Given an array a, the condition a > 3 is a boolean array and since False is interpreted as 0, ma.nonzero(a > 3) yields the indices of the a where the condition is true.

>>> a = ma.array([[1,2,3],[4,5,6],[7,8,9]])
>>> a > 3
masked_array(data =
 [[False False False]
 [ True  True  True]
 [ True  True  True]],
      mask =
 False,
      fill_value=999999)
>>> ma.nonzero(a > 3)
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))

The nonzero method of the condition array can also be called.

>>> (a > 3).nonzero()
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))


numpy.ma.shape

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.nonzero

Next topic

numpy.ma.size

numpy.ma.shape

numpy.ma.shape(obj) [source]

Return the shape of an array.

Parameters:

a : array_like

Input array.
Returns:

shape : tuple of ints

The elements of the shape tuple give the lengths of the corresponding array dimensions.

See also

alen

ndarray.shape
Equivalent array method.

Examples

>>> np.shape(np.eye(3))
(3, 3)
>>> np.shape([[1, 2]])
(1, 2)
>>> np.shape([0])
(1,)
>>> np.shape(0)
()

>>> a = np.array([(1, 2), (3, 4)], dtype=[('x', 'i4'), ('y', 'i4')])
>>> np.shape(a)
(2,)
>>> a.shape
(2,)


numpy.ma.size

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.shape

Next topic

numpy.ma.ravel

numpy.ma.size

numpy.ma.size(obj, axis=None) [source]

Return the number of elements along a given axis.

Parameters:

a : array_like

Input data.

axis : int, optional

Axis along which the elements are counted. By default, give the total number of elements.
Returns:

element_count : int

Number of elements along the specified axis.

See also

shape
dimensions of array
ndarray.shape
dimensions of array
ndarray.size
number of elements in array

Examples

>>> a = np.array([[1,2,3],[4,5,6]])
>>> np.size(a)
6
>>> np.size(a,1)
3
>>> np.size(a,0)
2


numpy.ma.is_masked

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.size

Next topic

numpy.ma.is_mask

numpy.ma.is_masked

numpy.ma.is_masked(x) [source]

Determine whether input has masked values.

Accepts any object as input, but always returns False unless the input is a MaskedArray containing masked values.

Parameters:

x : array_like

Array to check for masked values.
Returns:

result : bool

True if x is a MaskedArray with masked values, False otherwise.

Examples

>>> import numpy.ma as ma
>>> x = ma.masked_equal([0, 1, 0, 2, 3], 0)
>>> x
masked_array(data = [-- 1 -- 2 3],
      mask = [ True False  True False False],
      fill_value=999999)
>>> ma.is_masked(x)
True
>>> x = ma.masked_equal([0, 1, 0, 2, 3], 42)
>>> x
masked_array(data = [0 1 0 2 3],
      mask = False,
      fill_value=999999)
>>> ma.is_masked(x)
False

Always returns False if x isn’t a MaskedArray.

>>> x = [False, True, False]
>>> ma.is_masked(x)
False
>>> x = 'a string'
>>> ma.is_masked(x)
False


numpy.ma.is_mask

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.is_masked

Next topic

numpy.ma.MaskedArray.data

numpy.ma.is_mask

numpy.ma.is_mask(m) [source]

Return True if m is a valid, standard mask.

This function does not check the contents of the input, only that the type is MaskType. In particular, this function returns False if the mask has a flexible dtype.

Parameters:

m : array_like

Array to test.
Returns:

result : bool

True if m.dtype.type is MaskType, False otherwise.

See also

isMaskedArray
Test whether input is an instance of MaskedArray.

Examples

>>> import numpy.ma as ma
>>> m = ma.masked_equal([0, 1, 0, 2, 3], 0)
>>> m
masked_array(data = [-- 1 -- 2 3],
      mask = [ True False  True False False],
      fill_value=999999)
>>> ma.is_mask(m)
False
>>> ma.is_mask(m.mask)
True

Input must be an ndarray (or have similar attributes) for it to be considered a valid mask.

>>> m = [False, True, False]
>>> ma.is_mask(m)
False
>>> m = np.array([False, True, False])
>>> m
array([False,  True, False], dtype=bool)
>>> ma.is_mask(m)
True

Arrays with complex dtypes don’t return True.

>>> dtype = np.dtype({'names':['monty', 'pithon'],
                      'formats':[np.bool, np.bool]})
>>> dtype
dtype([('monty', '|b1'), ('pithon', '|b1')])
>>> m = np.array([(True, False), (False, True), (True, False)],
                 dtype=dtype)
>>> m
array([(True, False), (False, True), (True, False)],
      dtype=[('monty', '|b1'), ('pithon', '|b1')])
>>> ma.is_mask(m)
False


numpy.ma.MaskedArray.data

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.is_mask

Next topic

numpy.ma.MaskedArray.mask

numpy.ma.MaskedArray.data

MaskedArray.data

Return the current data, as a view of the original underlying data.


numpy.ma.MaskedArray.mask

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.data

Next topic

numpy.ma.MaskedArray.recordmask

numpy.ma.MaskedArray.mask

MaskedArray.mask

Mask


numpy.ma.MaskedArray.recordmask

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.mask

Next topic

numpy.ma.MaskedArray.all

numpy.ma.MaskedArray.recordmask

MaskedArray.recordmask

Return the mask of the records. A record is masked when all the fields are masked.


numpy.ma.ravel

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.size

Next topic

numpy.ma.reshape

numpy.ma.ravel

numpy.ma.ravel(self) = <numpy.ma.core._frommethod instance at 0x00000000048E4BC8>

Returns a 1D version of self, as a view.

Returns:

MaskedArray

Output view is of shape (self.size,) (or (np.ma.product(self.shape),)).

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]
>>> print x.ravel()
[1 -- 3 -- 5 -- 7 -- 9]


numpy.ma.reshape

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.ravel

Next topic

numpy.ma.resize

numpy.ma.reshape

numpy.ma.reshape(a, new_shape, order='C') [source]

Returns an array containing the same data with a new shape.

Refer to MaskedArray.reshape for full documentation.

See also

MaskedArray.reshape
equivalent function


numpy.ma.resize

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.reshape

Next topic

numpy.ma.MaskedArray.flatten

numpy.ma.resize

numpy.ma.resize(x, new_shape) [source]

Return a new masked array with the specified size and shape.

This is the masked equivalent of the numpy.resize function. The new array is filled with repeated copies of x (in the order that the data are stored in memory). If x is masked, the new array will be masked, and the new mask will be a repetition of the old one.

See also

numpy.resize
Equivalent function in the top level NumPy module.

Examples

>>> import numpy.ma as ma
>>> a = ma.array([[1, 2] ,[3, 4]])
>>> a[0, 1] = ma.masked
>>> a
masked_array(data =
 [[1 --]
 [3 4]],
             mask =
 [[False  True]
 [False False]],
       fill_value = 999999)
>>> np.resize(a, (3, 3))
array([[1, 2, 3],
       [4, 1, 2],
       [3, 4, 1]])
>>> ma.resize(a, (3, 3))
masked_array(data =
 [[1 -- 3]
 [4 1 --]
 [3 4 1]],
             mask =
 [[False  True False]
 [False False  True]
 [False False False]],
       fill_value = 999999)

A MaskedArray is always returned, regardless of the input type.

>>> a = np.array([[1, 2] ,[3, 4]])
>>> ma.resize(a, (3, 3))
masked_array(data =
 [[1 2 3]
 [4 1 2]
 [3 4 1]],
             mask =
 False,
       fill_value = 999999)


numpy.ma.swapaxes

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.resize

Next topic

numpy.ma.transpose

numpy.ma.swapaxes

numpy.ma.swapaxes = <numpy.ma.core._frommethod instance at 0x00000000048E4E88>

swapaxes a.swapaxes(axis1, axis2)

Return a view of the array with axis1 and axis2 interchanged.

Refer to numpy.swapaxes for full documentation.

See also

numpy.swapaxes
equivalent function


numpy.ma.transpose

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.trace

Next topic

numpy.ma.MaskedArray.trace

numpy.ma.transpose

numpy.ma.transpose(a, axes=None) [source]

Permute the dimensions of an array.

This function is exactly equivalent to numpy.transpose.

See also

numpy.transpose
Equivalent function in top-level NumPy module.

Examples

>>> import numpy.ma as ma
>>> x = ma.arange(4).reshape((2,2))
>>> x[1, 1] = ma.masked
>>>> x
masked_array(data =
 [[0 1]
 [2 --]],
             mask =
 [[False False]
 [False  True]],
       fill_value = 999999)
>>> ma.transpose(x)
masked_array(data =
 [[0 2]
 [1 --]],
             mask =
 [[False False]
 [False  True]],
       fill_value = 999999)


numpy.ma.atleast_1d

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.transpose

Next topic

numpy.ma.atleast_2d

numpy.ma.atleast_1d

numpy.ma.atleast_1d(*arys) = <numpy.ma.extras._fromnxfunction instance at 0x00000000048F1B88>

Convert inputs to arrays with at least one dimension.

Scalar inputs are converted to 1-dimensional arrays, whilst higher-dimensional inputs are preserved.

Parameters:

arys1, arys2, ... : array_like

One or more input arrays.
Returns:

ret : ndarray

An array, or sequence of arrays, each with a.ndim >= 1. Copies are made only if necessary.

Notes

The function is applied to both the _data and the _mask, if any.

Examples

>>> np.atleast_1d(1.0)
array([ 1.])

>>> x = np.arange(9.0).reshape(3,3)
>>> np.atleast_1d(x)
array([[ 0.,  1.,  2.],
       [ 3.,  4.,  5.],
       [ 6.,  7.,  8.]])
>>> np.atleast_1d(x) is x
True

>>> np.atleast_1d(1, [3, 4])
[array([1]), array([3, 4])]


numpy.ma.atleast_2d

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.atleast_1d

Next topic

numpy.ma.atleast_3d

numpy.ma.atleast_2d

numpy.ma.atleast_2d(*arys) = <numpy.ma.extras._fromnxfunction instance at 0x00000000048F1C88>
View inputs as arrays with at least two dimensions.
Parameters:

arys1, arys2, ... : array_like

One or more array-like sequences. Non-array inputs are converted to arrays. Arrays that already have two or more dimensions are preserved.
Returns:

res, res2, ... : ndarray

An array, or tuple of arrays, each with a.ndim >= 2. Copies are avoided where possible, and views with two or more dimensions are returned.

Notes

The function is applied to both the _data and the _mask, if any.

Examples

>>> np.atleast_2d(3.0)
array([[ 3.]])

>>> x = np.arange(3.0)
>>> np.atleast_2d(x)
array([[ 0.,  1.,  2.]])
>>> np.atleast_2d(x).base is x
True

>>> np.atleast_2d(1, [1, 2], [[1, 2]])
[array([[1]]), array([[1, 2]]), array([[1, 2]])]


numpy.ma.atleast_3d

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.atleast_2d

Next topic

numpy.ma.expand_dims

numpy.ma.atleast_3d

numpy.ma.atleast_3d(*arys) = <numpy.ma.extras._fromnxfunction instance at 0x00000000048F1D08>
View inputs as arrays with at least three dimensions.
Parameters:

arys1, arys2, ... : array_like

One or more array-like sequences. Non-array inputs are converted to arrays. Arrays that already have three or more dimensions are preserved.
Returns:

res1, res2, ... : ndarray

An array, or tuple of arrays, each with a.ndim >= 3. Copies are avoided where possible, and views with three or more dimensions are returned. For example, a 1-D array of shape (N,) becomes a view of shape (1, N, 1), and a 2-D array of shape (M, N) becomes a view of shape (M, N, 1).

Notes

The function is applied to both the _data and the _mask, if any.

Examples

>>> np.atleast_3d(3.0)
array([[[ 3.]]])

>>> x = np.arange(3.0)
>>> np.atleast_3d(x).shape
(1, 3, 1)

>>> x = np.arange(12.0).reshape(4,3)
>>> np.atleast_3d(x).shape
(4, 3, 1)
>>> np.atleast_3d(x).base is x
True

>>> for arr in np.atleast_3d([1, 2], [[1, 2]], [[[1, 2]]]):
...     print arr, arr.shape
...
[[[1]
  [2]]] (1, 2, 1)
[[[1]
  [2]]] (1, 2, 1)
[[[1 2]]] (1, 1, 2)


numpy.ma.expand_dims

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.atleast_3d

Next topic

numpy.ma.squeeze

numpy.ma.expand_dims

numpy.ma.expand_dims(x, axis) [source]

Expand the shape of an array.

Expands the shape of the array by including a new axis before the one specified by the axis parameter. This function behaves the same as numpy.expand_dims but preserves masked elements.

See also

numpy.expand_dims
Equivalent function in top-level NumPy module.

Examples

>>> import numpy.ma as ma
>>> x = ma.array([1, 2, 4])
>>> x[1] = ma.masked
>>> x
masked_array(data = [1 -- 4],
             mask = [False  True False],
       fill_value = 999999)
>>> np.expand_dims(x, axis=0)
array([[1, 2, 4]])
>>> ma.expand_dims(x, axis=0)
masked_array(data =
 [[1 -- 4]],
             mask =
 [[False  True False]],
       fill_value = 999999)

The same result can be achieved using slicing syntax with np.newaxis.

>>> x[np.newaxis, :]
masked_array(data =
 [[1 -- 4]],
             mask =
 [[False  True False]],
       fill_value = 999999)


numpy.ma.squeeze

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.expand_dims

Next topic

numpy.ma.MaskedArray.squeeze

numpy.ma.squeeze

numpy.ma.squeeze(a, axis=None) [source]

Remove single-dimensional entries from the shape of an array.

Parameters:

a : array_like

Input data.

axis : None or int or tuple of ints, optional

New in version 1.7.0.

Selects a subset of the single-dimensional entries in the shape. If an axis is selected with shape entry greater than one, an error is raised.
Returns:

squeezed : ndarray

The input array, but with all or a subset of the dimensions of length 1 removed. This is always a itself or a view into a.

Examples

>>> x = np.array([[[0], [1], [2]]])
>>> x.shape
(1, 3, 1)
>>> np.squeeze(x).shape
(3,)
>>> np.squeeze(x, axis=(2,)).shape
(1, 3)


numpy.ma.column_stack

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.vstack

Next topic

numpy.ma.concatenate

numpy.ma.column_stack

numpy.ma.column_stack(tup) = <numpy.ma.extras._fromnxfunction instance at 0x00000000048F1E88>

Stack 1-D arrays as columns into a 2-D array.

Take a sequence of 1-D arrays and stack them as columns to make a single 2-D array. 2-D arrays are stacked as-is, just like with hstack. 1-D arrays are turned into 2-D columns first.

Parameters:

tup : sequence of 1-D or 2-D arrays.

Arrays to stack. All of them must have the same first dimension.
Returns:

stacked : 2-D array

The array formed by stacking the given arrays.

Notes

The function is applied to both the _data and the _mask, if any.

Examples

>>> a = np.array((1,2,3))
>>> b = np.array((2,3,4))
>>> np.column_stack((a,b))
array([[1, 2],
       [2, 3],
       [3, 4]])


numpy.ma.concatenate

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.column_stack

Next topic

numpy.ma.append

numpy.ma.concatenate

numpy.ma.concatenate(arrays, axis=0) [source]

Concatenate a sequence of arrays along the given axis.

Parameters:

arrays : sequence of array_like

The arrays must have the same shape, except in the dimension corresponding to axis (the first, by default).

axis : int, optional

The axis along which the arrays will be joined. Default is 0.
Returns:

result : MaskedArray

The concatenated array with any masked entries preserved.

See also

numpy.concatenate
Equivalent function in the top-level NumPy module.

Examples

>>> import numpy.ma as ma
>>> a = ma.arange(3)
>>> a[1] = ma.masked
>>> b = ma.arange(2, 5)
>>> a
masked_array(data = [0 -- 2],
             mask = [False  True False],
       fill_value = 999999)
>>> b
masked_array(data = [2 3 4],
             mask = False,
       fill_value = 999999)
>>> ma.concatenate([a, b])
masked_array(data = [0 -- 2 2 3 4],
             mask = [False  True False False False False],
       fill_value = 999999)


numpy.ma.dstack

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.append

Next topic

numpy.ma.hstack

numpy.ma.dstack

numpy.ma.dstack(tup) = <numpy.ma.extras._fromnxfunction instance at 0x00000000048F1F08>

Stack arrays in sequence depth wise (along third axis).

Takes a sequence of arrays and stack them along the third axis to make a single array. Rebuilds arrays divided by dsplit. This is a simple way to stack 2D arrays (images) into a single 3D array for processing.

Parameters:

tup : sequence of arrays

Arrays to stack. All of them must have the same shape along all but the third axis.
Returns:

stacked : ndarray

The array formed by stacking the given arrays.

See also

vstack
Stack along first axis.
hstack
Stack along second axis.
concatenate
Join arrays.
dsplit
Split array along third axis.

Notes

The function is applied to both the _data and the _mask, if any.

Examples

>>> a = np.array((1,2,3))
>>> b = np.array((2,3,4))
>>> np.dstack((a,b))
array([[[1, 2],
        [2, 3],
        [3, 4]]])

>>> a = np.array([[1],[2],[3]])
>>> b = np.array([[2],[3],[4]])
>>> np.dstack((a,b))
array([[[1, 2]],
       [[2, 3]],
       [[3, 4]]])


numpy.ma.hstack

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.dstack

Next topic

numpy.ma.vstack

numpy.ma.hstack

numpy.ma.hstack(tup) = <numpy.ma.extras._fromnxfunction instance at 0x00000000048F1E08>

Stack arrays in sequence horizontally (column wise).

Take a sequence of arrays and stack them horizontally to make a single array. Rebuild arrays divided by hsplit.

Parameters:

tup : sequence of ndarrays

All arrays must have the same shape along all but the second axis.
Returns:

stacked : ndarray

The array formed by stacking the given arrays.

See also

vstack
Stack arrays in sequence vertically (row wise).
dstack
Stack arrays in sequence depth wise (along third axis).
concatenate
Join a sequence of arrays together.
hsplit
Split array along second axis.

Notes

The function is applied to both the _data and the _mask, if any.

Examples

>>> a = np.array((1,2,3))
>>> b = np.array((2,3,4))
>>> np.hstack((a,b))
array([1, 2, 3, 2, 3, 4])
>>> a = np.array([[1],[2],[3]])
>>> b = np.array([[2],[3],[4]])
>>> np.hstack((a,b))
array([[1, 2],
       [2, 3],
       [3, 4]])


numpy.ma.hsplit

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.hstack

Next topic

numpy.ma.mr

numpy.ma.hsplit

numpy.ma.hsplit(ary, indices_or_sections) = <numpy.ma.extras._fromnxfunction instance at 0x00000000048F1F88>

Split an array into multiple sub-arrays horizontally (column-wise).

Please refer to the split documentation. hsplit is equivalent to split with axis=1, the array is always split along the second axis regardless of the array dimension.

See also

split
Split an array into multiple sub-arrays of equal size.

Notes

The function is applied to both the _data and the _mask, if any.

Examples

>>> x = np.arange(16.0).reshape(4, 4)
>>> x
array([[  0.,   1.,   2.,   3.],
       [  4.,   5.,   6.,   7.],
       [  8.,   9.,  10.,  11.],
       [ 12.,  13.,  14.,  15.]])
>>> np.hsplit(x, 2)
[array([[  0.,   1.],
       [  4.,   5.],
       [  8.,   9.],
       [ 12.,  13.]]),
 array([[  2.,   3.],
       [  6.,   7.],
       [ 10.,  11.],
       [ 14.,  15.]])]
>>> np.hsplit(x, np.array([3, 6]))
[array([[  0.,   1.,   2.],
       [  4.,   5.,   6.],
       [  8.,   9.,  10.],
       [ 12.,  13.,  14.]]),
 array([[  3.],
       [  7.],
       [ 11.],
       [ 15.]]),
 array([], dtype=float64)]

With a higher dimensional array the split is still along the second axis.

>>> x = np.arange(8.0).reshape(2, 2, 2)
>>> x
array([[[ 0.,  1.],
        [ 2.,  3.]],
       [[ 4.,  5.],
        [ 6.,  7.]]])
>>> np.hsplit(x, 2)
[array([[[ 0.,  1.]],
       [[ 4.,  5.]]]),
 array([[[ 2.,  3.]],
       [[ 6.,  7.]]])]


numpy.ma.mr

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.hsplit

Next topic

numpy.ma.row_stack

numpy.ma.mr

numpy.ma.mr_ = <numpy.ma.extras.mr_class object at 0x00000000049024E0>

Translate slice objects to concatenation along the first axis.

This is the masked array version of lib.index_tricks.RClass.

See also

lib.index_tricks.RClass

Examples

>>> np.ma.mr_[np.ma.array([1,2,3]), 0, 0, np.ma.array([4,5,6])]
array([1, 2, 3, 0, 0, 4, 5, 6])


numpy.ma.row_stack

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.mr

Next topic

numpy.ma.vstack

numpy.ma.row_stack

numpy.ma.row_stack(tup) = <numpy.ma.extras._fromnxfunction instance at 0x00000000048F1D88>

Stack arrays in sequence vertically (row wise).

Take a sequence of arrays and stack them vertically to make a single array. Rebuild arrays divided by vsplit.

Parameters:

tup : sequence of ndarrays

Tuple containing arrays to be stacked. The arrays must have the same shape along all but the first axis.
Returns:

stacked : ndarray

The array formed by stacking the given arrays.

See also

hstack
Stack arrays in sequence horizontally (column wise).
dstack
Stack arrays in sequence depth wise (along third dimension).
concatenate
Join a sequence of arrays together.
vsplit
Split array into a list of multiple sub-arrays vertically.

Notes

The function is applied to both the _data and the _mask, if any.

Examples

>>> a = np.array([1, 2, 3])
>>> b = np.array([2, 3, 4])
>>> np.vstack((a,b))
array([[1, 2, 3],
       [2, 3, 4]])

>>> a = np.array([[1], [2], [3]])
>>> b = np.array([[2], [3], [4]])
>>> np.vstack((a,b))
array([[1],
       [2],
       [3],
       [2],
       [3],
       [4]])


numpy.ma.vstack

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.hstack

Next topic

numpy.ma.make_mask

numpy.ma.vstack

numpy.ma.vstack(tup) = <numpy.ma.extras._fromnxfunction instance at 0x00000000048F1D88>

Stack arrays in sequence vertically (row wise).

Take a sequence of arrays and stack them vertically to make a single array. Rebuild arrays divided by vsplit.

Parameters:

tup : sequence of ndarrays

Tuple containing arrays to be stacked. The arrays must have the same shape along all but the first axis.
Returns:

stacked : ndarray

The array formed by stacking the given arrays.

See also

hstack
Stack arrays in sequence horizontally (column wise).
dstack
Stack arrays in sequence depth wise (along third dimension).
concatenate
Join a sequence of arrays together.
vsplit
Split array into a list of multiple sub-arrays vertically.

Notes

The function is applied to both the _data and the _mask, if any.

Examples

>>> a = np.array([1, 2, 3])
>>> b = np.array([2, 3, 4])
>>> np.vstack((a,b))
array([[1, 2, 3],
       [2, 3, 4]])

>>> a = np.array([[1], [2], [3]])
>>> b = np.array([[2], [3], [4]])
>>> np.vstack((a,b))
array([[1],
       [2],
       [3],
       [2],
       [3],
       [4]])


numpy.ma.append

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.concatenate

Next topic

numpy.ma.dstack

numpy.ma.append

numpy.ma.append(a, b, axis=None) [source]

Append values to the end of an array.

New in version 1.9.0.

Parameters:

arr : array_like

Values are appended to a copy of this array.

values : array_like

These values are appended to a copy of arr. It must be of the correct shape (the same shape as arr, excluding axis). If axis is not specified, values can be any shape and will be flattened before use.

axis : int, optional

The axis along which values are appended. If axis is not given, both arr and values are flattened before use.
Returns:

append : MaskedArray

A copy of arr with values appended to axis. Note that append does not occur in-place: a new array is allocated and filled. If axis is None, the result is a flattened array.

See also

numpy.append
Equivalent function in the top-level NumPy module.

Examples

>>> import numpy.ma as ma
>>> a = ma.masked_values([1, 2, 3], 2)
>>> b = ma.masked_values([[4, 5, 6], [7, 8, 9]], 7)
>>> print(ma.append(a, b))
[1 -- 3 4 5 6 -- 8 9]


numpy.ma.make_mask

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.vstack

Next topic

numpy.ma.make_mask_none

numpy.ma.make_mask

numpy.ma.make_mask(m, copy=False, shrink=True, dtype=<type 'numpy.bool_'>) [source]

Create a boolean mask from an array.

Return m as a boolean mask, creating a copy if necessary or requested. The function can accept any sequence that is convertible to integers, or nomask. Does not require that contents must be 0s and 1s, values of 0 are interepreted as False, everything else as True.

Parameters:

m : array_like

Potential mask.

copy : bool, optional

Whether to return a copy of m (True) or m itself (False).

shrink : bool, optional

Whether to shrink m to nomask if all its values are False.

dtype : dtype, optional

Data-type of the output mask. By default, the output mask has a dtype of MaskType (bool). If the dtype is flexible, each field has a boolean dtype.
Returns:

result : ndarray

A boolean mask derived from m.

Examples

>>> import numpy.ma as ma
>>> m = [True, False, True, True]
>>> ma.make_mask(m)
array([ True, False,  True,  True], dtype=bool)
>>> m = [1, 0, 1, 1]
>>> ma.make_mask(m)
array([ True, False,  True,  True], dtype=bool)
>>> m = [1, 0, 2, -3]
>>> ma.make_mask(m)
array([ True, False,  True,  True], dtype=bool)

Effect of the shrink parameter.

>>> m = np.zeros(4)
>>> m
array([ 0.,  0.,  0.,  0.])
>>> ma.make_mask(m)
False
>>> ma.make_mask(m, shrink=False)
array([False, False, False, False], dtype=bool)

Using a flexible dtype.

>>> m = [1, 0, 1, 1]
>>> n = [0, 1, 0, 0]
>>> arr = []
>>> for man, mouse in zip(m, n):
...     arr.append((man, mouse))
>>> arr
[(1, 0), (0, 1), (1, 0), (1, 0)]
>>> dtype = np.dtype({'names':['man', 'mouse'],
                      'formats':[np.int, np.int]})
>>> arr = np.array(arr, dtype=dtype)
>>> arr
array([(1, 0), (0, 1), (1, 0), (1, 0)],
      dtype=[('man', '<i4'), ('mouse', '<i4')])
>>> ma.make_mask(arr, dtype=dtype)
array([(True, False), (False, True), (True, False), (True, False)],
      dtype=[('man', '|b1'), ('mouse', '|b1')])


numpy.ma.make_mask_none

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.make_mask

Next topic

numpy.ma.mask_or

numpy.ma.make_mask_none

numpy.ma.make_mask_none(newshape, dtype=None) [source]

Return a boolean mask of the given shape, filled with False.

This function returns a boolean ndarray with all entries False, that can be used in common mask manipulations. If a complex dtype is specified, the type of each field is converted to a boolean type.

Parameters:

newshape : tuple

A tuple indicating the shape of the mask.

dtype : {None, dtype}, optional

If None, use a MaskType instance. Otherwise, use a new datatype with the same fields as dtype, converted to boolean types.
Returns:

result : ndarray

An ndarray of appropriate shape and dtype, filled with False.

See also

make_mask
Create a boolean mask from an array.
make_mask_descr
Construct a dtype description list from a given dtype.

Examples

>>> import numpy.ma as ma
>>> ma.make_mask_none((3,))
array([False, False, False], dtype=bool)

Defining a more complex dtype.

>>> dtype = np.dtype({'names':['foo', 'bar'],
                      'formats':[np.float32, np.int]})
>>> dtype
dtype([('foo', '<f4'), ('bar', '<i4')])
>>> ma.make_mask_none((3,), dtype=dtype)
array([(False, False), (False, False), (False, False)],
      dtype=[('foo', '|b1'), ('bar', '|b1')])


numpy.ma.mask_or

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.mask_cols

Next topic

numpy.ma.mask_rowcols

numpy.ma.mask_or

numpy.ma.mask_or(m1, m2, copy=False, shrink=True) [source]

Combine two masks with the logical_or operator.

The result may be a view on m1 or m2 if the other is nomask (i.e. False).

Parameters:

m1, m2 : array_like

Input masks.

copy : bool, optional

If copy is False and one of the inputs is nomask, return a view of the other input mask. Defaults to False.

shrink : bool, optional

Whether to shrink the output to nomask if all its values are False. Defaults to True.
Returns:

mask : output mask

The result masks values that are masked in either m1 or m2.
Raises:

ValueError

If m1 and m2 have different flexible dtypes.

Examples

>>> m1 = np.ma.make_mask([0, 1, 1, 0])
>>> m2 = np.ma.make_mask([1, 0, 0, 0])
>>> np.ma.mask_or(m1, m2)
array([ True,  True,  True, False], dtype=bool)


numpy.ma.make_mask_descr

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.mask_or

Next topic

numpy.ma.getmask

numpy.ma.make_mask_descr

numpy.ma.make_mask_descr(ndtype) [source]

Construct a dtype description list from a given dtype.

Returns a new dtype object, with the type of all fields in ndtype to a boolean type. Field names are not altered.

Parameters:

ndtype : dtype

The dtype to convert.
Returns:

result : dtype

A dtype that looks like ndtype, the type of all fields is boolean.

Examples

>>> import numpy.ma as ma
>>> dtype = np.dtype({'names':['foo', 'bar'],
                      'formats':[np.float32, np.int]})
>>> dtype
dtype([('foo', '<f4'), ('bar', '<i4')])
>>> ma.make_mask_descr(dtype)
dtype([('foo', '|b1'), ('bar', '|b1')])
>>> ma.make_mask_descr(np.float32)
<type 'numpy.bool_'>


numpy.ma.masked_array.mask

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.getmaskarray

Next topic

numpy.ma.flatnotmasked_contiguous

numpy.ma.masked_array.mask

masked_array.mask

Mask


numpy.ma.flatnotmasked_contiguous

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_array.mask

Next topic

numpy.ma.flatnotmasked_edges

numpy.ma.flatnotmasked_contiguous

numpy.ma.flatnotmasked_contiguous(a) [source]

Find contiguous unmasked data in a masked array along the given axis.

Parameters:

a : narray

The input array.
Returns:

slice_list : list

A sorted sequence of slices (start index, end index).

See also

flatnotmasked_edges, notmasked_contiguous, notmasked_edges, clump_masked, clump_unmasked

Notes

Only accepts 2-D arrays at most.

Examples

>>> a = np.ma.arange(10)
>>> np.ma.extras.flatnotmasked_contiguous(a)
slice(0, 10, None)

>>> mask = (a < 3) | (a > 8) | (a == 5)
>>> a[mask] = np.ma.masked
>>> np.array(a[~a.mask])
array([3, 4, 6, 7, 8])

>>> np.ma.extras.flatnotmasked_contiguous(a)
[slice(3, 5, None), slice(6, 9, None)]
>>> a[:] = np.ma.masked
>>> print np.ma.extras.flatnotmasked_edges(a)
None


numpy.ma.flatnotmasked_edges

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.flatnotmasked_contiguous

Next topic

numpy.ma.notmasked_contiguous

numpy.ma.flatnotmasked_edges

numpy.ma.flatnotmasked_edges(a) [source]

Find the indices of the first and last unmasked values.

Expects a 1-D MaskedArray, returns None if all values are masked.

Parameters:

arr : array_like

Input 1-D MaskedArray
Returns:

edges : ndarray or None

The indices of first and last non-masked value in the array. Returns None if all values are masked.

See also

flatnotmasked_contiguous, notmasked_contiguous, notmasked_edges, clump_masked, clump_unmasked

Notes

Only accepts 1-D arrays.

Examples

>>> a = np.ma.arange(10)
>>> flatnotmasked_edges(a)
[0,-1]

>>> mask = (a < 3) | (a > 8) | (a == 5)
>>> a[mask] = np.ma.masked
>>> np.array(a[~a.mask])
array([3, 4, 6, 7, 8])

>>> flatnotmasked_edges(a)
array([3, 8])

>>> a[:] = np.ma.masked
>>> print flatnotmasked_edges(ma)
None


numpy.ma.notmasked_contiguous

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.flatnotmasked_edges

Next topic

numpy.ma.notmasked_edges

numpy.ma.notmasked_contiguous

numpy.ma.notmasked_contiguous(a, axis=None) [source]

Find contiguous unmasked data in a masked array along the given axis.

Parameters:

a : array_like

The input array.

axis : int, optional

Axis along which to perform the operation. If None (default), applies to a flattened version of the array.
Returns:

endpoints : list

A list of slices (start and end indexes) of unmasked indexes in the array.

See also

flatnotmasked_edges, flatnotmasked_contiguous, notmasked_edges, clump_masked, clump_unmasked

Notes

Only accepts 2-D arrays at most.

Examples

>>> a = np.arange(9).reshape((3, 3))
>>> mask = np.zeros_like(a)
>>> mask[1:, 1:] = 1

>>> ma = np.ma.array(a, mask=mask)
>>> np.array(ma[~ma.mask])
array([0, 1, 2, 3, 6])

>>> np.ma.extras.notmasked_contiguous(ma)
[slice(0, 4, None), slice(6, 7, None)]


numpy.ma.notmasked_edges

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.notmasked_contiguous

Next topic

numpy.ma.mask_cols

numpy.ma.notmasked_edges

numpy.ma.notmasked_edges(a, axis=None) [source]

Find the indices of the first and last unmasked values along an axis.

If all values are masked, return None. Otherwise, return a list of two tuples, corresponding to the indices of the first and last unmasked values respectively.

Parameters:

a : array_like

The input array.

axis : int, optional

Axis along which to perform the operation. If None (default), applies to a flattened version of the array.
Returns:

edges : ndarray or list

An array of start and end indexes if there are any masked data in the array. If there are no masked data in the array, edges is a list of the first and last index.

See also

flatnotmasked_contiguous, flatnotmasked_edges, notmasked_contiguous, clump_masked, clump_unmasked

Examples

>>> a = np.arange(9).reshape((3, 3))
>>> m = np.zeros_like(a)
>>> m[1:, 1:] = 1

>>> am = np.ma.array(a, mask=m)
>>> np.array(am[~am.mask])
array([0, 1, 2, 3, 6])

>>> np.ma.extras.notmasked_edges(ma)
array([0, 6])


numpy.ma.mask_cols

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.notmasked_edges

Next topic

numpy.ma.mask_or

numpy.ma.mask_cols

numpy.ma.mask_cols(a, axis=None) [source]

Mask columns of a 2D array that contain masked values.

This function is a shortcut to mask_rowcols with axis equal to 1.

See also

mask_rowcols
Mask rows and/or columns of a 2D array.
masked_where
Mask where a condition is met.

Examples

>>> import numpy.ma as ma
>>> a = np.zeros((3, 3), dtype=np.int)
>>> a[1, 1] = 1
>>> a
array([[0, 0, 0],
       [0, 1, 0],
       [0, 0, 0]])
>>> a = ma.masked_equal(a, 1)
>>> a
masked_array(data =
 [[0 0 0]
 [0 -- 0]
 [0 0 0]],
      mask =
 [[False False False]
 [False  True False]
 [False False False]],
      fill_value=999999)
>>> ma.mask_cols(a)
masked_array(data =
 [[0 -- 0]
 [0 -- 0]
 [0 -- 0]],
      mask =
 [[False  True False]
 [False  True False]
 [False  True False]],
      fill_value=999999)


numpy.ma.mask_rowcols

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.mask_or

Next topic

numpy.ma.mask_rows

numpy.ma.mask_rowcols

numpy.ma.mask_rowcols(a, axis=None) [source]

Mask rows and/or columns of a 2D array that contain masked values.

Mask whole rows and/or columns of a 2D array that contain masked values. The masking behavior is selected using the axis parameter.

  • If axis is None, rows and columns are masked.
  • If axis is 0, only rows are masked.
  • If axis is 1 or -1, only columns are masked.
Parameters:

a : array_like, MaskedArray

The array to mask. If not a MaskedArray instance (or if no array elements are masked). The result is a MaskedArray with mask set to nomask (False). Must be a 2D array.

axis : int, optional

Axis along which to perform the operation. If None, applies to a flattened version of the array.
Returns:

a : MaskedArray

A modified version of the input array, masked depending on the value of the axis parameter.
Raises:

NotImplementedError

If input array a is not 2D.

See also

mask_rows
Mask rows of a 2D array that contain masked values.
mask_cols
Mask cols of a 2D array that contain masked values.
masked_where
Mask where a condition is met.

Notes

The input array’s mask is modified by this function.

Examples

>>> import numpy.ma as ma
>>> a = np.zeros((3, 3), dtype=np.int)
>>> a[1, 1] = 1
>>> a
array([[0, 0, 0],
       [0, 1, 0],
       [0, 0, 0]])
>>> a = ma.masked_equal(a, 1)
>>> a
masked_array(data =
 [[0 0 0]
 [0 -- 0]
 [0 0 0]],
      mask =
 [[False False False]
 [False  True False]
 [False False False]],
      fill_value=999999)
>>> ma.mask_rowcols(a)
masked_array(data =
 [[0 -- 0]
 [-- -- --]
 [0 -- 0]],
      mask =
 [[False  True False]
 [ True  True  True]
 [False  True False]],
      fill_value=999999)


numpy.ma.mask_rows

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.mask_rowcols

Next topic

numpy.ma.harden_mask

numpy.ma.mask_rows

numpy.ma.mask_rows(a, axis=None) [source]

Mask rows of a 2D array that contain masked values.

This function is a shortcut to mask_rowcols with axis equal to 0.

See also

mask_rowcols
Mask rows and/or columns of a 2D array.
masked_where
Mask where a condition is met.

Examples

>>> import numpy.ma as ma
>>> a = np.zeros((3, 3), dtype=np.int)
>>> a[1, 1] = 1
>>> a
array([[0, 0, 0],
       [0, 1, 0],
       [0, 0, 0]])
>>> a = ma.masked_equal(a, 1)
>>> a
masked_array(data =
 [[0 0 0]
 [0 -- 0]
 [0 0 0]],
      mask =
 [[False False False]
 [False  True False]
 [False False False]],
      fill_value=999999)
>>> ma.mask_rows(a)
masked_array(data =
 [[0 0 0]
 [-- -- --]
 [0 0 0]],
      mask =
 [[False False False]
 [ True  True  True]
 [False False False]],
      fill_value=999999)


numpy.ma.harden_mask

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.mask_rows

Next topic

numpy.ma.soften_mask

numpy.ma.harden_mask

numpy.ma.harden_mask(self) = <numpy.ma.core._frommethod instance at 0x00000000048E4908>

Force the mask to hard.

Whether the mask of a masked array is hard or soft is determined by its hardmask property. harden_mask sets hardmask to True.

See also

hardmask


numpy.ma.soften_mask

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.harden_mask

Next topic

numpy.ma.MaskedArray.harden_mask

numpy.ma.soften_mask

numpy.ma.soften_mask(self) = <numpy.ma.core._frommethod instance at 0x00000000048E4CC8>

Force the mask to soft.

Whether the mask of a masked array is hard or soft is determined by its hardmask property. soften_mask sets hardmask to False.

See also

hardmask


numpy.ma.compress_cols

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.masked_where

Next topic

numpy.ma.compress_rowcols

numpy.ma.compress_cols

numpy.ma.compress_cols(a) [source]

Suppress whole columns of a 2-D array that contain masked values.

This is equivalent to np.ma.extras.compress_rowcols(a, 1), see extras.compress_rowcols for details.

See also

extras.compress_rowcols


numpy.ma.compress_rowcols

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.compress_cols

Next topic

numpy.ma.compress_rows

numpy.ma.compress_rowcols

numpy.ma.compress_rowcols(x, axis=None) [source]

Suppress the rows and/or columns of a 2-D array that contain masked values.

The suppression behavior is selected with the axis parameter.

  • If axis is None, both rows and columns are suppressed.
  • If axis is 0, only rows are suppressed.
  • If axis is 1 or -1, only columns are suppressed.
Parameters:

axis : int, optional

Axis along which to perform the operation. Default is None.
Returns:

compressed_array : ndarray

The compressed array.

Examples

>>> x = np.ma.array(np.arange(9).reshape(3, 3), mask=[[1, 0, 0],
...                                                   [1, 0, 0],
...                                                   [0, 0, 0]])
>>> x
masked_array(data =
 [[-- 1 2]
 [-- 4 5]
 [6 7 8]],
             mask =
 [[ True False False]
 [ True False False]
 [False False False]],
       fill_value = 999999)

>>> np.ma.extras.compress_rowcols(x)
array([[7, 8]])
>>> np.ma.extras.compress_rowcols(x, 0)
array([[6, 7, 8]])
>>> np.ma.extras.compress_rowcols(x, 1)
array([[1, 2],
       [4, 5],
       [7, 8]])


numpy.ma.compress_rows

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.compress_rowcols

Next topic

numpy.ma.compressed

numpy.ma.compress_rows

numpy.ma.compress_rows(a) [source]

Suppress whole rows of a 2-D array that contain masked values.

This is equivalent to np.ma.extras.compress_rowcols(a, 0), see extras.compress_rowcols for details.

See also

extras.compress_rowcols


numpy.ma.compressed

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.compress_rows

Next topic

numpy.ma.filled

numpy.ma.compressed

numpy.ma.compressed(x) [source]

Return all the non-masked data as a 1-D array.

This function is equivalent to calling the “compressed” method of a MaskedArray, see MaskedArray.compressed for details.

See also

MaskedArray.compressed
Equivalent method.


numpy.ma.filled

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.compressed

Next topic

numpy.ma.MaskedArray.compressed

numpy.ma.filled

numpy.ma.filled(a, fill_value=None) [source]

Return input as an array with masked data replaced by a fill value.

If a is not a MaskedArray, a itself is returned. If a is a MaskedArray and fill_value is None, fill_value is set to a.fill_value.

Parameters:

a : MaskedArray or array_like

An input object.

fill_value : scalar, optional

Filling value. Default is None.
Returns:

a : ndarray

The filled array.

See also

compressed

Examples

>>> x = np.ma.array(np.arange(9).reshape(3, 3), mask=[[1, 0, 0],
...                                                   [1, 0, 0],
...                                                   [0, 0, 0]])
>>> x.filled()
array([[999999,      1,      2],
       [999999,      4,      5],
       [     6,      7,      8]])


numpy.ma.dump

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.tobytes

Next topic

numpy.ma.dumps

numpy.ma.dump

numpy.ma.dump(a, F) [source]

Pickle a masked array to a file.

This is a wrapper around cPickle.dump.

Parameters:

a : MaskedArray

The array to be pickled.

F : str or file-like object

The file to pickle a to. If a string, the full path to the file.


numpy.ma.dumps

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.dump

Next topic

numpy.ma.load

numpy.ma.dumps

numpy.ma.dumps(a) [source]

Return a string corresponding to the pickling of a masked array.

This is a wrapper around cPickle.dumps.

Parameters:

a : MaskedArray

The array for which the string representation of the pickle is returned.


numpy.ma.load

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.dumps

Next topic

numpy.ma.loads

numpy.ma.load

numpy.ma.load(F) [source]

Wrapper around cPickle.load which accepts either a file-like object or a filename.

Parameters:

F : str or file

The file or file name to load.

See also

dump
Pickle an array

Notes

This is different from numpy.load, which does not use cPickle but loads the NumPy binary .npy format.


numpy.ma.loads

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.load

Next topic

numpy.ma.common_fill_value

numpy.ma.loads

numpy.ma.loads(strg) [source]

Load a pickle from the current string.

The result of cPickle.loads(strg) is returned.

Parameters:

strg : str

The string to load.

See also

dumps
Return a string corresponding to the pickling of a masked array.


numpy.ma.common_fill_value

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.loads

Next topic

numpy.ma.default_fill_value

numpy.ma.common_fill_value

numpy.ma.common_fill_value(a, b) [source]

Return the common filling value of two masked arrays, if any.

If a.fill_value == b.fill_value, return the fill value, otherwise return None.

Parameters:

a, b : MaskedArray

The masked arrays for which to compare fill values.
Returns:

fill_value : scalar or None

The common fill value, or None.

Examples

>>> x = np.ma.array([0, 1.], fill_value=3)
>>> y = np.ma.array([0, 1.], fill_value=3)
>>> np.ma.common_fill_value(x, y)
3.0


numpy.ma.default_fill_value

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.common_fill_value

Next topic

numpy.ma.maximum_fill_value

numpy.ma.default_fill_value

numpy.ma.default_fill_value(obj) [source]

Return the default fill value for the argument object.

The default filling value depends on the datatype of the input array or the type of the input scalar:

datatype | default
bool | True
int | 999999
float | 1.e20
complex | 1.e20+0j
object ‘?’
string | ‘N/A’
Parameters:

obj : ndarray, dtype or scalar

The array data-type or scalar for which the default fill value is returned.
Returns:

fill_value : scalar

The default fill value.

Examples

>>> np.ma.default_fill_value(1)
999999
>>> np.ma.default_fill_value(np.array([1.1, 2., np.pi]))
1e+20
>>>  np.ma.default_fill_value(np.dtype(complex))
(1e+20+0j)


numpy.ma.maximum_fill_value

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.maximum_fill_value

Next topic

numpy.ma.set_fill_value

numpy.ma.maximum_fill_value

numpy.ma.maximum_fill_value(obj) [source]

Return the minimum value that can be represented by the dtype of an object.

This function is useful for calculating a fill value suitable for taking the maximum of an array with a given dtype.

Parameters:

obj : {ndarray, dtype}

An object that can be queried for it’s numeric type.
Returns:

val : scalar

The minimum representable value.
Raises:

TypeError

If obj isn’t a suitable numeric type.

See also

minimum_fill_value
The inverse function.
set_fill_value
Set the filling value of a masked array.
MaskedArray.fill_value
Return current fill value.

Examples

>>> import numpy.ma as ma
>>> a = np.int8()
>>> ma.maximum_fill_value(a)
-128
>>> a = np.int32()
>>> ma.maximum_fill_value(a)
-2147483648

An array of numeric data can also be passed.

>>> a = np.array([1, 2, 3], dtype=np.int8)
>>> ma.maximum_fill_value(a)
-128
>>> a = np.array([1, 2, 3], dtype=np.float32)
>>> ma.maximum_fill_value(a)
-inf


numpy.ma.set_fill_value

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.maximum_fill_value

Next topic

numpy.ma.MaskedArray.get_fill_value

numpy.ma.set_fill_value

numpy.ma.set_fill_value(a, fill_value) [source]

Set the filling value of a, if a is a masked array.

This function changes the fill value of the masked array a in place. If a is not a masked array, the function returns silently, without doing anything.

Parameters:

a : array_like

Input array.

fill_value : dtype

Filling value. A consistency test is performed to make sure the value is compatible with the dtype of a.
Returns:

None

Nothing returned by this function.

See also

maximum_fill_value
Return the default fill value for a dtype.
MaskedArray.fill_value
Return current fill value.
MaskedArray.set_fill_value
Equivalent method.

Examples

>>> import numpy.ma as ma
>>> a = np.arange(5)
>>> a
array([0, 1, 2, 3, 4])
>>> a = ma.masked_where(a < 3, a)
>>> a
masked_array(data = [-- -- -- 3 4],
      mask = [ True  True  True False False],
      fill_value=999999)
>>> ma.set_fill_value(a, -999)
>>> a
masked_array(data = [-- -- -- 3 4],
      mask = [ True  True  True False False],
      fill_value=-999)

Nothing happens if a is not a masked array.

>>> a = range(5)
>>> a
[0, 1, 2, 3, 4]
>>> ma.set_fill_value(a, 100)
>>> a
[0, 1, 2, 3, 4]
>>> a = np.arange(5)
>>> a
array([0, 1, 2, 3, 4])
>>> ma.set_fill_value(a, 100)
>>> a
array([0, 1, 2, 3, 4])


numpy.ma.MaskedArray.fill_value

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.set_fill_value

Next topic

numpy.ma.anom

numpy.ma.MaskedArray.fill_value

MaskedArray.fill_value

Filling value.


numpy.ma.anom

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.fill_value

Next topic

numpy.ma.anomalies

numpy.ma.anom

numpy.ma.anom(self, axis=None, dtype=None) = <numpy.ma.core._frommethod instance at 0x00000000048E4588>

Compute the anomalies (deviations from the arithmetic mean) along the given axis.

Returns an array of anomalies, with the same shape as the input and where the arithmetic mean is computed along the given axis.

Parameters:

axis : int, optional

Axis over which the anomalies are taken. The default is to use the mean of the flattened array as reference.

dtype : dtype, optional

Type to use in computing the variance. For arrays of integer type

the default is float32; for arrays of float types it is the same as the array type.

See also

mean
Compute the mean of the array.

Examples

>>> a = np.ma.array([1,2,3])
>>> a.anom()
masked_array(data = [-1.  0.  1.],
             mask = False,
       fill_value = 1e+20)


numpy.ma.anomalies

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.anom

Next topic

numpy.ma.average

numpy.ma.anomalies

numpy.ma.anomalies(self, axis=None, dtype=None) = <numpy.ma.core._frommethod instance at 0x00000000048E4588>

Compute the anomalies (deviations from the arithmetic mean) along the given axis.

Returns an array of anomalies, with the same shape as the input and where the arithmetic mean is computed along the given axis.

Parameters:

axis : int, optional

Axis over which the anomalies are taken. The default is to use the mean of the flattened array as reference.

dtype : dtype, optional

Type to use in computing the variance. For arrays of integer type

the default is float32; for arrays of float types it is the same as the array type.

See also

mean
Compute the mean of the array.

Examples

>>> a = np.ma.array([1,2,3])
>>> a.anom()
masked_array(data = [-1.  0.  1.],
             mask = False,
       fill_value = 1e+20)


numpy.ma.average

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.anomalies

Next topic

numpy.ma.conjugate

numpy.ma.average

numpy.ma.average(a, axis=None, weights=None, returned=False) [source]

Return the weighted average of array over the given axis.

Parameters:

a : array_like

Data to be averaged. Masked entries are not taken into account in the computation.

axis : int, optional

Axis along which the average is computed. The default is to compute the average of the flattened array.

weights : array_like, optional

The importance that each element has in the computation of the average. The weights array can either be 1-D (in which case its length must be the size of a along the given axis) or of the same shape as a. If weights=None, then all data in a are assumed to have a weight equal to one. If weights is complex, the imaginary parts are ignored.

returned : bool, optional

Flag indicating whether a tuple (result, sum of weights) should be returned as output (True), or just the result (False). Default is False.
Returns:

average, [sum_of_weights] : (tuple of) scalar or MaskedArray

The average along the specified axis. When returned is True, return a tuple with the average as the first element and the sum of the weights as the second element. The return type is np.float64 if a is of integer type, otherwise it is of the same type as a. If returned, sum_of_weights is of the same type as average.

Examples

>>> a = np.ma.array([1., 2., 3., 4.], mask=[False, False, True, True])
>>> np.ma.average(a, weights=[3, 1, 0, 0])
1.25

>>> x = np.ma.arange(6.).reshape(3, 2)
>>> print x
[[ 0.  1.]
 [ 2.  3.]
 [ 4.  5.]]
>>> avg, sumweights = np.ma.average(x, axis=0, weights=[1, 2, 3],
...                                 returned=True)
>>> print avg
[2.66666666667 3.66666666667]


numpy.ma.conjugate

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.average

Next topic

numpy.ma.corrcoef

numpy.ma.conjugate

numpy.ma.conjugate(x[, out]) = <numpy.ma.core._MaskedUnaryOperation instance at 0x00000000048CD948>

Return the complex conjugate, element-wise.

The complex conjugate of a complex number is obtained by changing the sign of its imaginary part.

Parameters:

x : array_like

Input value.
Returns:

y : ndarray

The complex conjugate of x, with same dtype as y.

Examples

>>> np.conjugate(1+2j)
(1-2j)

>>> x = np.eye(2) + 1j * np.eye(2)
>>> np.conjugate(x)
array([[ 1.-1.j,  0.-0.j],
       [ 0.-0.j,  1.-1.j]])


numpy.ma.corrcoef

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.conjugate

Next topic

numpy.ma.cov

numpy.ma.corrcoef

numpy.ma.corrcoef(x, y=None, rowvar=True, bias=False, allow_masked=True, ddof=None) [source]

Return correlation coefficients of the input array.

Except for the handling of missing data this function does the same as numpy.corrcoef. For more details and examples, see numpy.corrcoef.

Parameters:

x : array_like

A 1-D or 2-D array containing multiple variables and observations. Each row of x represents a variable, and each column a single observation of all those variables. Also see rowvar below.

y : array_like, optional

An additional set of variables and observations. y has the same shape as x.

rowvar : bool, optional

If rowvar is True (default), then each row represents a variable, with observations in the columns. Otherwise, the relationship is transposed: each column represents a variable, while the rows contain observations.

bias : bool, optional

Default normalization (False) is by (N-1), where N is the number of observations given (unbiased estimate). If bias is 1, then normalization is by N. This keyword can be overridden by the keyword ddof in numpy versions >= 1.5.

allow_masked : bool, optional

If True, masked values are propagated pair-wise: if a value is masked in x, the corresponding value is masked in y. If False, raises an exception.

ddof : {None, int}, optional

New in version 1.5.

If not None normalization is by (N - ddof), where N is the number of observations; this overrides the value implied by bias. The default value is None.

See also

numpy.corrcoef
Equivalent function in top-level NumPy module.
cov
Estimate the covariance matrix.


numpy.ma.cov

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.corrcoef

Next topic

numpy.ma.cumsum

numpy.ma.cov

numpy.ma.cov(x, y=None, rowvar=True, bias=False, allow_masked=True, ddof=None) [source]

Estimate the covariance matrix.

Except for the handling of missing data this function does the same as numpy.cov. For more details and examples, see numpy.cov.

By default, masked values are recognized as such. If x and y have the same shape, a common mask is allocated: if x[i,j] is masked, then y[i,j] will also be masked. Setting allow_masked to False will raise an exception if values are missing in either of the input arrays.

Parameters:

x : array_like

A 1-D or 2-D array containing multiple variables and observations. Each row of x represents a variable, and each column a single observation of all those variables. Also see rowvar below.

y : array_like, optional

An additional set of variables and observations. y has the same form as x.

rowvar : bool, optional

If rowvar is True (default), then each row represents a variable, with observations in the columns. Otherwise, the relationship is transposed: each column represents a variable, while the rows contain observations.

bias : bool, optional

Default normalization (False) is by (N-1), where N is the number of observations given (unbiased estimate). If bias is True, then normalization is by N. This keyword can be overridden by the keyword ddof in numpy versions >= 1.5.

allow_masked : bool, optional

If True, masked values are propagated pair-wise: if a value is masked in x, the corresponding value is masked in y. If False, raises a ValueError exception when some values are missing.

ddof : {None, int}, optional

New in version 1.5.

If not None normalization is by (N - ddof), where N is the number of observations; this overrides the value implied by bias. The default value is None.
Raises:

ValueError

Raised if some values are missing and allow_masked is False.

See also

numpy.cov


numpy.ma.cumsum

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.cov

Next topic

numpy.ma.cumprod

numpy.ma.cumsum

numpy.ma.cumsum(self, axis=None, dtype=None, out=None) = <numpy.ma.core._frommethod instance at 0x00000000048E47C8>

Return the cumulative sum of the elements along the given axis. The cumulative sum is calculated over the flattened array by default, otherwise over the specified axis.

Masked values are set to 0 internally during the computation. However, their position is saved, and the result will be masked at the same locations.

Parameters:

axis : {None, -1, int}, optional

Axis along which the sum is computed. The default (axis = None) is to compute over the flattened array. axis may be negative, in which case it counts from the last to the first axis.

dtype : {None, dtype}, optional

Type of the returned array and of the accumulator in which the elements are summed. If dtype is not specified, it defaults to the dtype of a, unless a has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary.
Returns:

cumsum : ndarray.

A new array holding the result is returned unless out is specified, in which case a reference to out is returned.

Notes

The mask is lost if out is not a valid MaskedArray !

Arithmetic is modular when using integer types, and no error is raised on overflow.

Examples

>>> marr = np.ma.array(np.arange(10), mask=[0,0,0,1,1,1,0,0,0,0])
>>> print marr.cumsum()
[0 1 3 -- -- -- 9 16 24 33]


numpy.ma.cumprod

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.cumsum

Next topic

numpy.ma.mean

numpy.ma.cumprod

numpy.ma.cumprod(self, axis=None, dtype=None, out=None) = <numpy.ma.core._frommethod instance at 0x00000000048E4748>

Return the cumulative product of the elements along the given axis. The cumulative product is taken over the flattened array by default, otherwise over the specified axis.

Masked values are set to 1 internally during the computation. However, their position is saved, and the result will be masked at the same locations.

Parameters:

axis : {None, -1, int}, optional

Axis along which the product is computed. The default (axis = None) is to compute over the flattened array.

dtype : {None, dtype}, optional

Determines the type of the returned array and of the accumulator where the elements are multiplied. If dtype has the value None and the type of a is an integer type of precision less than the default platform integer, then the default platform integer precision is used. Otherwise, the dtype is the same as that of a.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary.
Returns:

cumprod : ndarray

A new array holding the result is returned unless out is specified, in which case a reference to out is returned.

Notes

The mask is lost if out is not a valid MaskedArray !

Arithmetic is modular when using integer types, and no error is raised on overflow.


numpy.ma.mean

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.cumprod

Next topic

numpy.ma.median

numpy.ma.mean

numpy.ma.mean(self, axis=None, dtype=None, out=None) = <numpy.ma.core._frommethod instance at 0x00000000048E49C8>

Returns the average of the array elements.

Masked entries are ignored. The average is taken over the flattened array by default, otherwise over the specified axis. Refer to numpy.mean for the full documentation.

Parameters:

a : array_like

Array containing numbers whose mean is desired. If a is not an array, a conversion is attempted.

axis : int, optional

Axis along which the means are computed. The default is to compute the mean of the flattened array.

dtype : dtype, optional

Type to use in computing the mean. For integer inputs, the default is float64; for floating point, inputs it is the same as the input dtype.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type will be cast if necessary.
Returns:

mean : ndarray, see dtype parameter above

If out=None, returns a new array containing the mean values, otherwise a reference to the output array is returned.

See also

numpy.ma.mean
Equivalent function.
numpy.mean
Equivalent function on non-masked arrays.
numpy.ma.average
Weighted average.

Examples

>>> a = np.ma.array([1,2,3], mask=[False, False, True])
>>> a
masked_array(data = [1 2 --],
             mask = [False False  True],
       fill_value = 999999)
>>> a.mean()
1.5


numpy.ma.median

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.mean

Next topic

numpy.ma.power

numpy.ma.median

numpy.ma.median(a, axis=None, out=None, overwrite_input=False) [source]

Compute the median along the specified axis.

Returns the median of the array elements.

Parameters:

a : array_like

Input array or object that can be converted to an array.

axis : int, optional

Axis along which the medians are computed. The default (None) is to compute the median along a flattened version of the array.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary.

overwrite_input : bool, optional

If True, then allow use of memory of input array (a) for calculations. The input array will be modified by the call to median. This will save memory when you do not need to preserve the contents of the input array. Treat the input as undefined, but it will probably be fully or partially sorted. Default is False. Note that, if overwrite_input is True, and the input is not already an ndarray, an error will be raised.
Returns:

median : ndarray

A new array holding the result is returned unless out is specified, in which case a reference to out is returned. Return data-type is float64 for integers and floats smaller than float64, or the input data-type, otherwise.

See also

mean

Notes

Given a vector V with N non masked values, the median of V is the middle value of a sorted copy of V (Vs) - i.e. Vs[(N-1)/2], when N is odd, or {Vs[N/2 - 1] + Vs[N/2]}/2 when N is even.

Examples

>>> x = np.ma.array(np.arange(8), mask=[0]*4 + [1]*4)
>>> np.ma.extras.median(x)
1.5

>>> x = np.ma.array(np.arange(10).reshape(2, 5), mask=[0]*6 + [1]*4)
>>> np.ma.extras.median(x)
2.5
>>> np.ma.extras.median(x, axis=-1, overwrite_input=True)
masked_array(data = [ 2.  5.],
             mask = False,
       fill_value = 1e+20)


numpy.ma.power

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.median

Next topic

numpy.ma.prod

numpy.ma.power

numpy.ma.power(a, b, third=None) [source]

Returns element-wise base array raised to power from second array.

This is the masked array version of numpy.power. For details see numpy.power.

See also

numpy.power

Notes

The out argument to numpy.power is not supported, third has to be None.


numpy.ma.prod

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.power

Next topic

numpy.ma.std

numpy.ma.prod

numpy.ma.prod(self, axis=None, dtype=None, out=None) = <numpy.ma.core._frommethod instance at 0x00000000048E4AC8>

Return the product of the array elements over the given axis. Masked elements are set to 1 internally for computation.

Parameters:

axis : {None, int}, optional

Axis over which the product is taken. If None is used, then the product is over all the array elements.

dtype : {None, dtype}, optional

Determines the type of the returned array and of the accumulator where the elements are multiplied. If dtype has the value None and the type of a is an integer type of precision less than the default platform integer, then the default platform integer precision is used. Otherwise, the dtype is the same as that of a.

out : {None, array}, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type will be cast if necessary.
Returns:

product_along_axis : {array, scalar}, see dtype parameter above.

Returns an array whose shape is the same as a with the specified axis removed. Returns a 0d array when a is 1d or axis=None. Returns a reference to the specified output array if specified.

See also

prod
equivalent function

Notes

Arithmetic is modular when using integer types, and no error is raised on overflow.

Examples

>>> np.prod([1.,2.])
2.0
>>> np.prod([1.,2.], dtype=np.int32)
2
>>> np.prod([[1.,2.],[3.,4.]])
24.0
>>> np.prod([[1.,2.],[3.,4.]], axis=1)
array([  2.,  12.])


numpy.ma.std

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.prod

Next topic

numpy.ma.sum

numpy.ma.std

numpy.ma.std(self, axis=None, dtype=None, out=None, ddof=0) = <numpy.ma.core._frommethod instance at 0x00000000048E4D88>

Compute the standard deviation along the specified axis.

Returns the standard deviation, a measure of the spread of a distribution, of the array elements. The standard deviation is computed for the flattened array by default, otherwise over the specified axis.

Parameters:

a : array_like

Calculate the standard deviation of these values.

axis : int, optional

Axis along which the standard deviation is computed. The default is to compute the standard deviation of the flattened array.

dtype : dtype, optional

Type to use in computing the standard deviation. For arrays of integer type the default is float64, for arrays of float types it is the same as the array type.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type (of the calculated values) will be cast if necessary.

ddof : int, optional

Means Delta Degrees of Freedom. The divisor used in calculations is N - ddof, where N represents the number of elements. By default ddof is zero.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

standard_deviation : ndarray, see dtype parameter above.

If out is None, return a new array containing the standard deviation, otherwise return a reference to the output array.

See also

var, mean, nanmean, nanstd, nanvar

numpy.doc.ufuncs
Section “Output arguments”

Notes

The standard deviation is the square root of the average of the squared deviations from the mean, i.e., std = sqrt(mean(abs(x - x.mean())**2)).

The average squared deviation is normally calculated as x.sum() / N, where N = len(x). If, however, ddof is specified, the divisor N - ddof is used instead. In standard statistical practice, ddof=1 provides an unbiased estimator of the variance of the infinite population. ddof=0 provides a maximum likelihood estimate of the variance for normally distributed variables. The standard deviation computed in this function is the square root of the estimated variance, so even with ddof=1, it will not be an unbiased estimate of the standard deviation per se.

Note that, for complex numbers, std takes the absolute value before squaring, so that the result is always real and nonnegative.

For floating-point input, the std is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-accuracy accumulator using the dtype keyword can alleviate this issue.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> np.std(a)
1.1180339887498949
>>> np.std(a, axis=0)
array([ 1.,  1.])
>>> np.std(a, axis=1)
array([ 0.5,  0.5])

In single precision, std() can be inaccurate:

>>> a = np.zeros((2,512*512), dtype=np.float32)
>>> a[0,:] = 1.0
>>> a[1,:] = 0.1
>>> np.std(a)
0.45172946707416706

Computing the standard deviation in float64 is more accurate:

>>> np.std(a, dtype=np.float64)
0.44999999925552653


numpy.ma.sum

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.std

Next topic

numpy.ma.var

numpy.ma.sum

numpy.ma.sum(self, axis=None, dtype=None, out=None) = <numpy.ma.core._frommethod instance at 0x00000000048E4E08>

Return the sum of the array elements over the given axis. Masked elements are set to 0 internally.

Parameters:

axis : {None, -1, int}, optional

Axis along which the sum is computed. The default (axis = None) is to compute over the flattened array.

dtype : {None, dtype}, optional

Determines the type of the returned array and of the accumulator where the elements are summed. If dtype has the value None and the type of a is an integer type of precision less than the default platform integer, then the default platform integer precision is used. Otherwise, the dtype is the same as that of a.

out : {None, ndarray}, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary.
Returns:

sum_along_axis : MaskedArray or scalar

An array with the same shape as self, with the specified axis removed. If self is a 0-d array, or if axis is None, a scalar is returned. If an output array is specified, a reference to out is returned.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]
>>> print x.sum()
25
>>> print x.sum(axis=1)
[4 5 16]
>>> print x.sum(axis=0)
[8 5 12]
>>> print type(x.sum(axis=0, dtype=np.int64)[0])
<type 'numpy.int64'>


numpy.ma.var

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.sum

Next topic

numpy.ma.MaskedArray.anom

numpy.ma.var

numpy.ma.var(self, axis=None, dtype=None, out=None, ddof=0) = <numpy.ma.core._frommethod instance at 0x00000000048E4F08>

Compute the variance along the specified axis.

Returns the variance of the array elements, a measure of the spread of a distribution. The variance is computed for the flattened array by default, otherwise over the specified axis.

Parameters:

a : array_like

Array containing numbers whose variance is desired. If a is not an array, a conversion is attempted.

axis : int, optional

Axis along which the variance is computed. The default is to compute the variance of the flattened array.

dtype : data-type, optional

Type to use in computing the variance. For arrays of integer type the default is float32; for arrays of float types it is the same as the array type.

out : ndarray, optional

Alternate output array in which to place the result. It must have the same shape as the expected output, but the type is cast if necessary.

ddof : int, optional

“Delta Degrees of Freedom”: the divisor used in the calculation is N - ddof, where N represents the number of elements. By default ddof is zero.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

variance : ndarray, see dtype parameter above

If out=None, returns a new array containing the variance; otherwise, a reference to the output array is returned.

See also

std, mean, nanmean, nanstd, nanvar

numpy.doc.ufuncs
Section “Output arguments”

Notes

The variance is the average of the squared deviations from the mean, i.e., var = mean(abs(x - x.mean())**2).

The mean is normally calculated as x.sum() / N, where N = len(x). If, however, ddof is specified, the divisor N - ddof is used instead. In standard statistical practice, ddof=1 provides an unbiased estimator of the variance of a hypothetical infinite population. ddof=0 provides a maximum likelihood estimate of the variance for normally distributed variables.

Note that for complex numbers, the absolute value is taken before squaring, so that the result is always real and nonnegative.

For floating-point input, the variance is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-accuracy accumulator using the dtype keyword can alleviate this issue.

Examples

>>> a = np.array([[1,2],[3,4]])
>>> np.var(a)
1.25
>>> np.var(a, axis=0)
array([ 1.,  1.])
>>> np.var(a, axis=1)
array([ 0.25,  0.25])

In single precision, var() can be inaccurate:

>>> a = np.zeros((2,512*512), dtype=np.float32)
>>> a[0,:] = 1.0
>>> a[1,:] = 0.1
>>> np.var(a)
0.20405951142311096

Computing the variance in float64 is more accurate:

>>> np.var(a, dtype=np.float64)
0.20249999932997387
>>> ((1-0.55)**2 + (0.1-0.55)**2)/2
0.20250000000000001


numpy.ma.argmax

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.var

Next topic

numpy.ma.argmin

numpy.ma.argmax

numpy.ma.argmax(a, axis=None, fill_value=None) [source]

Returns array of indices of the maximum values along the given axis. Masked values are treated as if they had the value fill_value.

Parameters:

axis : {None, integer}

If None, the index is into the flattened array, otherwise along the specified axis

fill_value : {var}, optional

Value used to fill in the masked values. If None, the output of maximum_fill_value(self._data) is used instead.

out : {None, array}, optional

Array into which the result can be placed. Its type is preserved and it must be of the right shape to hold the output.
Returns:

index_array : {integer_array}

Examples

>>> a = np.arange(6).reshape(2,3)
>>> a.argmax()
5
>>> a.argmax(0)
array([1, 1, 1])
>>> a.argmax(1)
array([2, 2])


numpy.ma.argmin

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.argmax

Next topic

numpy.ma.max

numpy.ma.argmin

numpy.ma.argmin(a, axis=None, fill_value=None) [source]

Return array of indices to the minimum values along the given axis.

Parameters:

axis : {None, integer}

If None, the index is into the flattened array, otherwise along the specified axis

fill_value : {var}, optional

Value used to fill in the masked values. If None, the output of minimum_fill_value(self._data) is used instead.

out : {None, array}, optional

Array into which the result can be placed. Its type is preserved and it must be of the right shape to hold the output.
Returns:

{ndarray, scalar}

If multi-dimension input, returns a new ndarray of indices to the minimum values along the given axis. Otherwise, returns a scalar of index to the minimum values along the given axis.

Examples

>>> x = np.ma.array(arange(4), mask=[1,1,0,0])
>>> x.shape = (2,2)
>>> print x
[[-- --]
 [2 3]]
>>> print x.argmin(axis=0, fill_value=-1)
[0 0]
>>> print x.argmin(axis=0, fill_value=9)
[1 1]


numpy.ma.max

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.argmin

Next topic

numpy.ma.min

numpy.ma.max

numpy.ma.max(obj, axis=None, out=None, fill_value=None) [source]

Return the maximum along a given axis.

Parameters:

axis : {None, int}, optional

Axis along which to operate. By default, axis is None and the flattened input is used.

out : array_like, optional

Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output.

fill_value : {var}, optional

Value used to fill in the masked values. If None, use the output of maximum_fill_value().
Returns:

amax : array_like

New array holding the result. If out was specified, out is returned.

See also

maximum_fill_value
Returns the maximum filling value for a given datatype.


numpy.ma.min

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.max

Next topic

numpy.ma.ptp

numpy.ma.min

numpy.ma.min(obj, axis=None, out=None, fill_value=None) [source]

Return the minimum along a given axis.

Parameters:

axis : {None, int}, optional

Axis along which to operate. By default, axis is None and the flattened input is used.

out : array_like, optional

Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output.

fill_value : {var}, optional

Value used to fill in the masked values. If None, use the output of minimum_fill_value.
Returns:

amin : array_like

New array holding the result. If out was specified, out is returned.

See also

minimum_fill_value
Returns the minimum filling value for a given datatype.


numpy.ma.ptp

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.min

Next topic

numpy.ma.MaskedArray.argmax

numpy.ma.ptp

numpy.ma.ptp(obj, axis=None, out=None, fill_value=None) [source]

Return (maximum - minimum) along the the given dimension (i.e. peak-to-peak value).

Parameters:

axis : {None, int}, optional

Axis along which to find the peaks. If None (default) the flattened array is used.

out : {None, array_like}, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary.

fill_value : {var}, optional

Value used to fill in the masked values.
Returns:

ptp : ndarray.

A new array holding the result, unless out was specified, in which case a reference to out is returned.


numpy.ma.argsort

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.ptp

Next topic

numpy.ma.sort

numpy.ma.argsort

numpy.ma.argsort(a, axis=None, kind='quicksort', order=None, fill_value=None) [source]

Return an ndarray of indices that sort the array along the specified axis. Masked values are filled beforehand to fill_value.

Parameters:

axis : int, optional

Axis along which to sort. The default is -1 (last axis). If None, the flattened array is used.

fill_value : var, optional

Value used to fill the array before sorting. The default is the fill_value attribute of the input array.

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.
Returns:

index_array : ndarray, int

Array of indices that sort a along the specified axis. In other words, a[index_array] yields a sorted a.

See also

sort
Describes sorting algorithms used.
lexsort
Indirect stable sort with multiple keys.
ndarray.sort
Inplace sort.

Notes

See sort for notes on the different sorting algorithms.

Examples

>>> a = np.ma.array([3,2,1], mask=[False, False, True])
>>> a
masked_array(data = [3 2 --],
             mask = [False False  True],
       fill_value = 999999)
>>> a.argsort()
array([1, 0, 2])


numpy.ma.sort

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.argsort

Next topic

numpy.ma.MaskedArray.argsort

numpy.ma.sort

numpy.ma.sort(a, axis=-1, kind='quicksort', order=None, endwith=True, fill_value=None) [source]

Sort the array, in-place

Parameters:

a : array_like

Array to be sorted.

axis : int, optional

Axis along which to sort. If None, the array is flattened before sorting. The default is -1, which sorts along the last axis.

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm. Default is ‘quicksort’.

order : list, optional

When a is a structured array, this argument specifies which fields to compare first, second, and so on. This list does not need to include all of the fields.

endwith : {True, False}, optional

Whether missing values (if any) should be forced in the upper indices (at the end of the array) (True) or lower indices (at the beginning). When the array contains unmasked values of the largest (or smallest if False) representable value of the datatype the ordering of these values and the masked values is undefined. To enforce the masked values are at the end (beginning) in this case one must sort the mask.

fill_value : {var}, optional

Value used internally for the masked values. If fill_value is not None, it supersedes endwith.
Returns:

sorted_array : ndarray

Array of the same type and shape as a.

See also

ndarray.sort
Method to sort an array in-place.
argsort
Indirect sort.
lexsort
Indirect stable sort on multiple keys.
searchsorted
Find elements in a sorted array.

Notes

See sort for notes on the different sorting algorithms.

Examples

>>> a = ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])
>>> # Default
>>> a.sort()
>>> print a
[1 3 5 -- --]

>>> a = ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])
>>> # Put missing values in the front
>>> a.sort(endwith=False)
>>> print a
[-- -- 1 3 5]

>>> a = ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])
>>> # fill_value takes over endwith
>>> a.sort(endwith=False, fill_value=3)
>>> print a
[1 -- -- 3 5]


numpy.ma.diag

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.sort

Next topic

numpy.ma.dot

numpy.ma.diag

numpy.ma.diag(v, k=0) [source]

Extract a diagonal or construct a diagonal array.

This function is the equivalent of numpy.diag that takes masked values into account, see numpy.diag for details.

See also

numpy.diag
Equivalent function for ndarrays.


numpy.ma.dot

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.diag

Next topic

numpy.ma.identity

numpy.ma.dot

numpy.ma.dot(a, b, strict=False) [source]

Return the dot product of two arrays.

Note

Works only with 2-D arrays at the moment.

This function is the equivalent of numpy.dot that takes masked values into account, see numpy.dot for details.

Parameters:

a, b : ndarray

Inputs arrays.

strict : bool, optional

Whether masked data are propagated (True) or set to 0 (False) for the computation. Default is False. Propagating the mask means that if a masked value appears in a row or column, the whole row or column is considered masked.

See also

numpy.dot
Equivalent function for ndarrays.

Examples

>>> a = ma.array([[1, 2, 3], [4, 5, 6]], mask=[[1, 0, 0], [0, 0, 0]])
>>> b = ma.array([[1, 2], [3, 4], [5, 6]], mask=[[1, 0], [0, 0], [0, 0]])
>>> np.ma.dot(a, b)
masked_array(data =
 [[21 26]
 [45 64]],
             mask =
 [[False False]
 [False False]],
       fill_value = 999999)
>>> np.ma.dot(a, b, strict=True)
masked_array(data =
 [[-- --]
 [-- 64]],
             mask =
 [[ True  True]
 [ True False]],
       fill_value = 999999)


numpy.ma.identity

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.dot

Next topic

numpy.ma.inner

numpy.ma.identity

numpy.ma.identity(n, dtype=None) = <numpy.ma.core._convert2ma instance at 0x00000000048F1348>

Return the identity array.

The identity array is a square array with ones on the main diagonal.

Parameters:

n : int

Number of rows (and columns) in n x n output.

dtype : data-type, optional

Data-type of the output. Defaults to float.
Returns:

out : ndarray

n x n array with its main diagonal set to one, and all other elements 0.

Examples

>>> np.identity(3)
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])


numpy.ma.inner

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.identity

Next topic

numpy.ma.innerproduct

numpy.ma.inner

numpy.ma.inner(a, b) [source]

Inner product of two arrays.

Ordinary inner product of vectors for 1-D arrays (without complex conjugation), in higher dimensions a sum product over the last axes.

Parameters:

a, b : array_like

If a and b are nonscalar, their last dimensions of must match.
Returns:

out : ndarray

out.shape = a.shape[:-1] + b.shape[:-1]
Raises:

ValueError

If the last dimension of a and b has different size.

See also

tensordot
Sum products over arbitrary axes.
dot
Generalised matrix product, using second last dimension of b.
einsum
Einstein summation convention.

Notes

Masked values are replaced by 0.

Examples

Ordinary inner product for vectors:

>>> a = np.array([1,2,3])
>>> b = np.array([0,1,0])
>>> np.inner(a, b)
2

A multidimensional example:

>>> a = np.arange(24).reshape((2,3,4))
>>> b = np.arange(4)
>>> np.inner(a, b)
array([[ 14,  38,  62],
       [ 86, 110, 134]])

An example where b is a scalar:

>>> np.inner(np.eye(2), 7)
array([[ 7.,  0.],
       [ 0.,  7.]])


numpy.ma.innerproduct

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.inner

Next topic

numpy.ma.outer

numpy.ma.innerproduct

numpy.ma.innerproduct(a, b) [source]

Inner product of two arrays.

Ordinary inner product of vectors for 1-D arrays (without complex conjugation), in higher dimensions a sum product over the last axes.

Parameters:

a, b : array_like

If a and b are nonscalar, their last dimensions of must match.
Returns:

out : ndarray

out.shape = a.shape[:-1] + b.shape[:-1]
Raises:

ValueError

If the last dimension of a and b has different size.

See also

tensordot
Sum products over arbitrary axes.
dot
Generalised matrix product, using second last dimension of b.
einsum
Einstein summation convention.

Notes

Masked values are replaced by 0.

Examples

Ordinary inner product for vectors:

>>> a = np.array([1,2,3])
>>> b = np.array([0,1,0])
>>> np.inner(a, b)
2

A multidimensional example:

>>> a = np.arange(24).reshape((2,3,4))
>>> b = np.arange(4)
>>> np.inner(a, b)
array([[ 14,  38,  62],
       [ 86, 110, 134]])

An example where b is a scalar:

>>> np.inner(np.eye(2), 7)
array([[ 7.,  0.],
       [ 0.,  7.]])


numpy.ma.outer

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.innerproduct

Next topic

numpy.ma.outerproduct

numpy.ma.outer

numpy.ma.outer(a, b) [source]

Compute the outer product of two vectors.

Given two vectors, a = [a0, a1, ..., aM] and b = [b0, b1, ..., bN], the outer product [R50] is:

[[a0*b0  a0*b1 ... a0*bN ]
 [a1*b0    .
 [ ...          .
 [aM*b0            aM*bN ]]
Parameters:

a : (M,) array_like

First input vector. Input is flattened if not already 1-dimensional.

b : (N,) array_like

Second input vector. Input is flattened if not already 1-dimensional.

out : (M, N) ndarray, optional

A location where the result is stored

New in version 1.9.0.
Returns:

out : (M, N) ndarray

out[i, j] = a[i] * b[j]

See also

inner, einsum

Notes

Masked values are replaced by 0.

References

[R50] (1, 2) : G. H. Golub and C. F. van Loan, Matrix Computations, 3rd ed., Baltimore, MD, Johns Hopkins University Press, 1996, pg. 8.

Examples

Make a (very coarse) grid for computing a Mandelbrot set:

>>> rl = np.outer(np.ones((5,)), np.linspace(-2, 2, 5))
>>> rl
array([[-2., -1.,  0.,  1.,  2.],
       [-2., -1.,  0.,  1.,  2.],
       [-2., -1.,  0.,  1.,  2.],
       [-2., -1.,  0.,  1.,  2.],
       [-2., -1.,  0.,  1.,  2.]])
>>> im = np.outer(1j*np.linspace(2, -2, 5), np.ones((5,)))
>>> im
array([[ 0.+2.j,  0.+2.j,  0.+2.j,  0.+2.j,  0.+2.j],
       [ 0.+1.j,  0.+1.j,  0.+1.j,  0.+1.j,  0.+1.j],
       [ 0.+0.j,  0.+0.j,  0.+0.j,  0.+0.j,  0.+0.j],
       [ 0.-1.j,  0.-1.j,  0.-1.j,  0.-1.j,  0.-1.j],
       [ 0.-2.j,  0.-2.j,  0.-2.j,  0.-2.j,  0.-2.j]])
>>> grid = rl + im
>>> grid
array([[-2.+2.j, -1.+2.j,  0.+2.j,  1.+2.j,  2.+2.j],
       [-2.+1.j, -1.+1.j,  0.+1.j,  1.+1.j,  2.+1.j],
       [-2.+0.j, -1.+0.j,  0.+0.j,  1.+0.j,  2.+0.j],
       [-2.-1.j, -1.-1.j,  0.-1.j,  1.-1.j,  2.-1.j],
       [-2.-2.j, -1.-2.j,  0.-2.j,  1.-2.j,  2.-2.j]])

An example using a “vector” of letters:

>>> x = np.array(['a', 'b', 'c'], dtype=object)
>>> np.outer(x, [1, 2, 3])
array([[a, aa, aaa],
       [b, bb, bbb],
       [c, cc, ccc]], dtype=object)


numpy.ma.outerproduct

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.outer

Next topic

numpy.ma.trace

numpy.ma.outerproduct

numpy.ma.outerproduct(a, b) [source]

Compute the outer product of two vectors.

Given two vectors, a = [a0, a1, ..., aM] and b = [b0, b1, ..., bN], the outer product [R51] is:

[[a0*b0  a0*b1 ... a0*bN ]
 [a1*b0    .
 [ ...          .
 [aM*b0            aM*bN ]]
Parameters:

a : (M,) array_like

First input vector. Input is flattened if not already 1-dimensional.

b : (N,) array_like

Second input vector. Input is flattened if not already 1-dimensional.

out : (M, N) ndarray, optional

A location where the result is stored

New in version 1.9.0.
Returns:

out : (M, N) ndarray

out[i, j] = a[i] * b[j]

See also

inner, einsum

Notes

Masked values are replaced by 0.

References

[R51] (1, 2) : G. H. Golub and C. F. van Loan, Matrix Computations, 3rd ed., Baltimore, MD, Johns Hopkins University Press, 1996, pg. 8.

Examples

Make a (very coarse) grid for computing a Mandelbrot set:

>>> rl = np.outer(np.ones((5,)), np.linspace(-2, 2, 5))
>>> rl
array([[-2., -1.,  0.,  1.,  2.],
       [-2., -1.,  0.,  1.,  2.],
       [-2., -1.,  0.,  1.,  2.],
       [-2., -1.,  0.,  1.,  2.],
       [-2., -1.,  0.,  1.,  2.]])
>>> im = np.outer(1j*np.linspace(2, -2, 5), np.ones((5,)))
>>> im
array([[ 0.+2.j,  0.+2.j,  0.+2.j,  0.+2.j,  0.+2.j],
       [ 0.+1.j,  0.+1.j,  0.+1.j,  0.+1.j,  0.+1.j],
       [ 0.+0.j,  0.+0.j,  0.+0.j,  0.+0.j,  0.+0.j],
       [ 0.-1.j,  0.-1.j,  0.-1.j,  0.-1.j,  0.-1.j],
       [ 0.-2.j,  0.-2.j,  0.-2.j,  0.-2.j,  0.-2.j]])
>>> grid = rl + im
>>> grid
array([[-2.+2.j, -1.+2.j,  0.+2.j,  1.+2.j,  2.+2.j],
       [-2.+1.j, -1.+1.j,  0.+1.j,  1.+1.j,  2.+1.j],
       [-2.+0.j, -1.+0.j,  0.+0.j,  1.+0.j,  2.+0.j],
       [-2.-1.j, -1.-1.j,  0.-1.j,  1.-1.j,  2.-1.j],
       [-2.-2.j, -1.-2.j,  0.-2.j,  1.-2.j,  2.-2.j]])

An example using a “vector” of letters:

>>> x = np.array(['a', 'b', 'c'], dtype=object)
>>> np.outer(x, [1, 2, 3])
array([[a, aa, aaa],
       [b, bb, bbb],
       [c, cc, ccc]], dtype=object)


numpy.ma.trace

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.outerproduct

Next topic

numpy.ma.transpose

numpy.ma.trace

numpy.ma.trace(self, offset=0, axis1=0, axis2=1, dtype=None, out=None) a.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None) = <numpy.ma.core._frommethod instance at 0x00000000048E4EC8>

Return the sum along diagonals of the array.

Refer to numpy.trace for full documentation.

See also

numpy.trace
equivalent function


numpy.ma.vander

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.transpose

Next topic

numpy.ma.polyfit

numpy.ma.vander

numpy.ma.vander(x, n=None) [source]

Generate a Vandermonde matrix.

The columns of the output matrix are powers of the input vector. The order of the powers is determined by the increasing boolean argument. Specifically, when increasing is False, the i-th output column is the input vector raised element-wise to the power of N - i - 1. Such a matrix with a geometric progression in each row is named for Alexandre- Theophile Vandermonde.

Parameters:

x : array_like

1-D input array.

N : int, optional

Number of columns in the output. If N is not specified, a square array is returned (N = len(x)).

increasing : bool, optional

Order of the powers of the columns. If True, the powers increase from left to right, if False (the default) they are reversed.

New in version 1.9.0.
Returns:

out : ndarray

Vandermonde matrix. If increasing is False, the first column is x^(N-1), the second x^(N-2) and so forth. If increasing is True, the columns are x^0, x^1, ..., x^(N-1).

See also

polynomial.polynomial.polyvander

Notes

Masked values in the input array result in rows of zeros.

Examples

>>> x = np.array([1, 2, 3, 5])
>>> N = 3
>>> np.vander(x, N)
array([[ 1,  1,  1],
       [ 4,  2,  1],
       [ 9,  3,  1],
       [25,  5,  1]])

>>> np.column_stack([x**(N-1-i) for i in range(N)])
array([[ 1,  1,  1],
       [ 4,  2,  1],
       [ 9,  3,  1],
       [25,  5,  1]])

>>> x = np.array([1, 2, 3, 5])
>>> np.vander(x)
array([[  1,   1,   1,   1],
       [  8,   4,   2,   1],
       [ 27,   9,   3,   1],
       [125,  25,   5,   1]])
>>> np.vander(x, increasing=True)
array([[  1,   1,   1,   1],
       [  1,   2,   4,   8],
       [  1,   3,   9,  27],
       [  1,   5,  25, 125]])

The determinant of a square Vandermonde matrix is the product of the differences between the values of the input vector:

>>> np.linalg.det(np.vander(x))
48.000000000000043
>>> (5-3)*(5-2)*(5-1)*(3-2)*(3-1)*(2-1)
48


numpy.ma.polyfit

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.vander

Next topic

numpy.ma.around

numpy.ma.polyfit

numpy.ma.polyfit(x, y, deg, rcond=None, full=False, w=None, cov=False) [source]

Least squares polynomial fit.

Fit a polynomial p(x) = p[0] * x**deg + ... + p[deg] of degree deg to points (x, y). Returns a vector of coefficients p that minimises the squared error.

Parameters:

x : array_like, shape (M,)

x-coordinates of the M sample points (x[i], y[i]).

y : array_like, shape (M,) or (M, K)

y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column.

deg : int

Degree of the fitting polynomial

rcond : float, optional

Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)*eps, where eps is the relative precision of the float type, about 2e-16 in most cases.

full : bool, optional

Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned.

w : array_like, shape (M,), optional

weights to apply to the y-coordinates of the sample points.

cov : bool, optional

Return the estimate and the covariance matrix of the estimate If full is True, then cov is not returned.
Returns:

p : ndarray, shape (M,) or (M, K)

Polynomial coefficients, highest power first. If y was 2-D, the coefficients for k-th data set are in p[:,k].

residuals, rank, singular_values, rcond :

Present only if full = True. Residuals of the least-squares fit, the effective rank of the scaled Vandermonde coefficient matrix, its singular values, and the specified value of rcond. For more details, see linalg.lstsq.

V : ndarray, shape (M,M) or (M,M,K)

Present only if full = False and cov`=True. The covariance matrix of the polynomial coefficient estimates. The diagonal of this matrix are the variance estimates for each coefficient. If y is a 2-D array, then the covariance matrix for the `k-th data set are in V[:,:,k]
Warns:

RankWarning

The rank of the coefficient matrix in the least-squares fit is deficient. The warning is only raised if full = False.

The warnings can be turned off by

>>> import warnings
>>> warnings.simplefilter('ignore', np.RankWarning)

See also

polyval
Computes polynomial values.
linalg.lstsq
Computes a least-squares fit.
scipy.interpolate.UnivariateSpline
Computes spline fits.

Notes

Any masked values in x is propagated in y, and vice-versa.

References

[R52] Wikipedia, “Curve fitting”, http://en.wikipedia.org/wiki/Curve_fitting
[R53] Wikipedia, “Polynomial interpolation”, http://en.wikipedia.org/wiki/Polynomial_interpolation

Examples

>>> x = np.array([0.0, 1.0, 2.0, 3.0,  4.0,  5.0])
>>> y = np.array([0.0, 0.8, 0.9, 0.1, -0.8, -1.0])
>>> z = np.polyfit(x, y, 3)
>>> z
array([ 0.08703704, -0.81349206,  1.69312169, -0.03968254])

It is convenient to use poly1d objects for dealing with polynomials:

>>> p = np.poly1d(z)
>>> p(0.5)
0.6143849206349179
>>> p(3.5)
-0.34732142857143039
>>> p(10)
22.579365079365115

High-order polynomials may oscillate wildly:

>>> p30 = np.poly1d(np.polyfit(x, y, 30))
/... RankWarning: Polyfit may be poorly conditioned...
>>> p30(4)
-0.80000000000000204
>>> p30(5)
-0.99999999999999445
>>> p30(4.5)
-0.10547061179440398

Illustration:

>>> import matplotlib.pyplot as plt
>>> xp = np.linspace(-2, 6, 100)
>>> _ = plt.plot(x, y, '.', xp, p(xp), '-', xp, p30(xp), '--')
>>> plt.ylim(-2,2)
(-2, 2)
>>> plt.show()

(Source code, png, pdf)


numpy.ma.around

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.polyfit

Next topic

numpy.ma.clip

numpy.ma.around

numpy.ma.around = <numpy.ma.core._MaskedUnaryOperation instance at 0x00000000048CDD08>

Round an array to the given number of decimals.

Refer to around for full documentation.

See also

around
equivalent function


numpy.ma.clip

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.around

Next topic

numpy.ma.round

numpy.ma.clip

numpy.ma.clip(a, a_min, a_max, out=None) [source]

Clip (limit) the values in an array.

Given an interval, values outside the interval are clipped to the interval edges. For example, if an interval of [0, 1] is specified, values smaller than 0 become 0, and values larger than 1 become 1.

Parameters:

a : array_like

Array containing elements to clip.

a_min : scalar or array_like

Minimum value.

a_max : scalar or array_like

Maximum value. If a_min or a_max are array_like, then they will be broadcasted to the shape of a.

out : ndarray, optional

The results will be placed in this array. It may be the input array for in-place clipping. out must be of the right shape to hold the output. Its type is preserved.
Returns:

clipped_array : ndarray

An array with the elements of a, but where values < a_min are replaced with a_min, and those > a_max with a_max.

See also

numpy.doc.ufuncs
Section “Output arguments”

Examples

>>> a = np.arange(10)
>>> np.clip(a, 1, 8)
array([1, 1, 2, 3, 4, 5, 6, 7, 8, 8])
>>> a
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
>>> np.clip(a, 3, 6, out=a)
array([3, 3, 3, 3, 4, 5, 6, 6, 6, 6])
>>> a = np.arange(10)
>>> a
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
>>> np.clip(a, [3,4,1,1,1,4,4,4,4,4], 8)
array([3, 4, 2, 3, 4, 5, 6, 7, 8, 8])


numpy.ma.round

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.clip

Next topic

numpy.ma.MaskedArray.clip

numpy.ma.round

numpy.ma.round(a, decimals=0, out=None) [source]

Return a copy of a, rounded to ‘decimals’ places.

When ‘decimals’ is negative, it specifies the number of positions to the left of the decimal point. The real and imaginary parts of complex numbers are rounded separately. Nothing is done if the array is not of float type and ‘decimals’ is greater than or equal to 0.

Parameters:

decimals : int

Number of decimals to round to. May be negative.

out : array_like

Existing array to use for output. If not given, returns a default copy of a.

Notes

If out is given and does not have a mask attribute, the mask of a is lost!


numpy.ma.allequal

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.MaskedArray.round

Next topic

numpy.ma.allclose

numpy.ma.allequal

numpy.ma.allequal(a, b, fill_value=True) [source]

Return True if all entries of a and b are equal, using fill_value as a truth value where either or both are masked.

Parameters:

a, b : array_like

Input arrays to compare.

fill_value : bool, optional

Whether masked values in a or b are considered equal (True) or not (False).
Returns:

y : bool

Returns True if the two arrays are equal within the given tolerance, False otherwise. If either array contains NaN, then False is returned.

See also

all, any, numpy.ma.allclose

Examples

>>> a = ma.array([1e10, 1e-7, 42.0], mask=[0, 0, 1])
>>> a
masked_array(data = [10000000000.0 1e-07 --],
      mask = [False False  True],
      fill_value=1e+20)

>>> b = array([1e10, 1e-7, -42.0])
>>> b
array([  1.00000000e+10,   1.00000000e-07,  -4.20000000e+01])
>>> ma.allequal(a, b, fill_value=False)
False
>>> ma.allequal(a, b)
True


numpy.ma.allclose

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.allequal

Next topic

numpy.ma.apply_along_axis

numpy.ma.allclose

numpy.ma.allclose(a, b, masked_equal=True, rtol=1e-05, atol=1e-08) [source]

Returns True if two arrays are element-wise equal within a tolerance.

This function is equivalent to allclose except that masked values are treated as equal (default) or unequal, depending on the masked_equal argument.

Parameters:

a, b : array_like

Input arrays to compare.

masked_equal : bool, optional

Whether masked values in a and b are considered equal (True) or not (False). They are considered equal by default.

rtol : float, optional

Relative tolerance. The relative difference is equal to rtol * b. Default is 1e-5.

atol : float, optional

Absolute tolerance. The absolute difference is equal to atol. Default is 1e-8.
Returns:

y : bool

Returns True if the two arrays are equal within the given tolerance, False otherwise. If either array contains NaN, then False is returned.

See also

all, any

numpy.allclose
the non-masked allclose.

Notes

If the following equation is element-wise True, then allclose returns True:

absolute(`a` - `b`) <= (`atol` + `rtol` * absolute(`b`))

Return True if all elements of a and b are equal subject to given tolerances.

Examples

>>> a = ma.array([1e10, 1e-7, 42.0], mask=[0, 0, 1])
>>> a
masked_array(data = [10000000000.0 1e-07 --],
             mask = [False False  True],
       fill_value = 1e+20)
>>> b = ma.array([1e10, 1e-8, -42.0], mask=[0, 0, 1])
>>> ma.allclose(a, b)
False

>>> a = ma.array([1e10, 1e-8, 42.0], mask=[0, 0, 1])
>>> b = ma.array([1.00001e10, 1e-9, -42.0], mask=[0, 0, 1])
>>> ma.allclose(a, b)
True
>>> ma.allclose(a, b, masked_equal=False)
False

Masked values are not compared directly.

>>> a = ma.array([1e10, 1e-8, 42.0], mask=[0, 0, 1])
>>> b = ma.array([1.00001e10, 1e-9, 42.0], mask=[0, 0, 1])
>>> ma.allclose(a, b)
True
>>> ma.allclose(a, b, masked_equal=False)
False


numpy.ma.apply_along_axis

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.allclose

Next topic

numpy.ma.arange

numpy.ma.apply_along_axis

numpy.ma.apply_along_axis(func1d, axis, arr, *args, **kwargs) [source]

Apply a function to 1-D slices along the given axis.

Execute func1d(a, *args) where func1d operates on 1-D arrays and a is a 1-D slice of arr along axis.

Parameters:

func1d : function

This function should accept 1-D arrays. It is applied to 1-D slices of arr along the specified axis.

axis : integer

Axis along which arr is sliced.

arr : ndarray

Input array.

args : any

Additional arguments to func1d.

kwargs: any

Additional named arguments to func1d.

New in version 1.9.0.
Returns:

apply_along_axis : ndarray

The output array. The shape of outarr is identical to the shape of arr, except along the axis dimension, where the length of outarr is equal to the size of the return value of func1d. If func1d returns a scalar outarr will have one fewer dimensions than arr.

See also

apply_over_axes
Apply a function repeatedly over multiple axes.

Examples

>>> def my_func(a):
...     """Average first and last element of a 1-D array"""
...     return (a[0] + a[-1]) * 0.5
>>> b = np.array([[1,2,3], [4,5,6], [7,8,9]])
>>> np.apply_along_axis(my_func, 0, b)
array([ 4.,  5.,  6.])
>>> np.apply_along_axis(my_func, 1, b)
array([ 2.,  5.,  8.])

For a function that doesn’t return a scalar, the number of dimensions in outarr is the same as arr.

>>> b = np.array([[8,1,7], [4,3,9], [5,2,6]])
>>> np.apply_along_axis(sorted, 1, b)
array([[1, 7, 8],
       [3, 4, 9],
       [2, 5, 6]])


numpy.ma.arange

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.apply_along_axis

Next topic

numpy.ma.choose

numpy.ma.arange

numpy.ma.arange([start, ]stop, [step, ]dtype=None) = <numpy.ma.core._convert2ma instance at 0x00000000048F10C8>

Return evenly spaced values within a given interval.

Values are generated within the half-open interval [start, stop) (in other words, the interval including start but excluding stop). For integer arguments the function is equivalent to the Python built-in range function, but returns an ndarray rather than a list.

When using a non-integer step, such as 0.1, the results will often not be consistent. It is better to use linspace for these cases.

Parameters:

start : number, optional

Start of interval. The interval includes this value. The default start value is 0.

stop : number

End of interval. The interval does not include this value, except in some cases where step is not an integer and floating point round-off affects the length of out.

step : number, optional

Spacing between values. For any output out, this is the distance between two adjacent values, out[i+1] - out[i]. The default step size is 1. If step is specified, start must also be given.

dtype : dtype

The type of the output array. If dtype is not given, infer the data type from the other input arguments.
Returns:

arange : ndarray

Array of evenly spaced values.

For floating point arguments, the length of the result is ceil((stop - start)/step). Because of floating point overflow, this rule may result in the last element of out being greater than stop.

See also

linspace
Evenly spaced numbers with careful handling of endpoints.
ogrid
Arrays of evenly spaced numbers in N-dimensions.
mgrid
Grid-shaped arrays of evenly spaced numbers in N-dimensions.

Examples

>>> np.arange(3)
array([0, 1, 2])
>>> np.arange(3.0)
array([ 0.,  1.,  2.])
>>> np.arange(3,7)
array([3, 4, 5, 6])
>>> np.arange(3,7,2)
array([3, 5])


numpy.ma.choose

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.arange

Next topic

numpy.ma.ediff1d

numpy.ma.choose

numpy.ma.choose(indices, choices, out=None, mode='raise') [source]

Use an index array to construct a new array from a set of choices.

Given an array of integers and a set of n choice arrays, this method will create a new array that merges each of the choice arrays. Where a value in a is i, the new array will have the value that choices[i] contains in the same place.

Parameters:

a : ndarray of ints

This array must contain integers in [0, n-1], where n is the number of choices.

choices : sequence of arrays

Choice arrays. The index array and all of the choices should be broadcastable to the same shape.

out : array, optional

If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype.

mode : {‘raise’, ‘wrap’, ‘clip’}, optional

Specifies how out-of-bounds indices will behave.

  • ‘raise’ : raise an error
  • ‘wrap’ : wrap around
  • ‘clip’ : clip to the range
Returns:

merged_array : array

See also

choose
equivalent function

Examples

>>> choice = np.array([[1,1,1], [2,2,2], [3,3,3]])
>>> a = np.array([2, 1, 0])
>>> np.ma.choose(a, choice)
masked_array(data = [3 2 1],
      mask = False,
      fill_value=999999)


numpy.ma.ediff1d

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.choose

Next topic

numpy.ma.indices

numpy.ma.ediff1d

numpy.ma.ediff1d(arr, to_end=None, to_begin=None) [source]

Compute the differences between consecutive elements of an array.

This function is the equivalent of numpy.ediff1d that takes masked values into account, see numpy.ediff1d for details.

See also

numpy.ediff1d
Equivalent function for ndarrays.


numpy.ma.indices

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.ediff1d

Next topic

numpy.ma.where

numpy.ma.indices

numpy.ma.indices(dimensions, dtype=<type 'int'>) [source]

Return an array representing the indices of a grid.

Compute an array where the subarrays contain index values 0,1,... varying only along the corresponding axis.

Parameters:

dimensions : sequence of ints

The shape of the grid.

dtype : dtype, optional

Data type of the result.
Returns:

grid : ndarray

The array of grid indices, grid.shape = (len(dimensions),) + tuple(dimensions).

See also

mgrid, meshgrid

Notes

The output shape is obtained by prepending the number of dimensions in front of the tuple of dimensions, i.e. if dimensions is a tuple (r0, ..., rN-1) of length N, the output shape is (N,r0,...,rN-1).

The subarrays grid[k] contains the N-D array of indices along the k-th axis. Explicitly:

grid[k,i0,i1,...,iN-1] = ik

Examples

>>> grid = np.indices((2, 3))
>>> grid.shape
(2, 2, 3)
>>> grid[0]        # row indices
array([[0, 0, 0],
       [1, 1, 1]])
>>> grid[1]        # column indices
array([[0, 1, 2],
       [0, 1, 2]])

The indices can be used as an index into an array.

>>> x = np.arange(20).reshape(5, 4)
>>> row, col = np.indices((2, 3))
>>> x[row, col]
array([[0, 1, 2],
       [4, 5, 6]])

Note that it would be more straightforward in the above example to extract the required elements directly with x[:2, :3].


numpy.ma.where

  • Masked array operations
  • next
  • previous

Previous topic

numpy.ma.indices

Next topic

Mathematical functions

numpy.ma.where

numpy.ma.where(condition, x=None, y=None) [source]

Return a masked array with elements from x or y, depending on condition.

Returns a masked array, shaped like condition, where the elements are from x when condition is True, and from y otherwise. If neither x nor y are given, the function returns a tuple of indices where condition is True (the result of condition.nonzero()).

Parameters:

condition : array_like, bool

The condition to meet. For each True element, yield the corresponding element from x, otherwise from y.

x, y : array_like, optional

Values from which to choose. x and y need to have the same shape as condition, or be broadcast-able to that shape.
Returns:

out : MaskedArray or tuple of ndarrays

The resulting masked array if x and y were given, otherwise the result of condition.nonzero().

See also

numpy.where
Equivalent function in the top-level NumPy module.

Examples

>>> x = np.ma.array(np.arange(9.).reshape(3, 3), mask=[[0, 1, 0],
...                                                    [1, 0, 1],
...                                                    [0, 1, 0]])
>>> print x
[[0.0 -- 2.0]
 [-- 4.0 --]
 [6.0 -- 8.0]]
>>> np.ma.where(x > 5)    # return the indices where x > 5
(array([2, 2]), array([0, 2]))

>>> print np.ma.where(x > 5, x, -3.1416)
[[-3.1416 -- -3.1416]
 [-- -3.1416 --]
 [6.0 -- 8.0]]


The Array Interface

  • Array objects
  • next
  • previous

Table Of Contents

  • The Array Interface
    • Python side
    • C-struct access
    • Type description examples
    • Differences with Array interface (Version 2)

Previous topic

numpy.ma.where

Next topic

Datetimes and Timedeltas

The Array Interface

Note

This page describes the numpy-specific API for accessing the contents of a numpy array from other C extensions. PEP 3118 – The Revised Buffer Protocol introduces similar, standardized API to Python 2.6 and 3.0 for any extension module to use. Cython‘s buffer array support uses the PEP 3118 API; 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 array interface described here.

version: 3

The array interface (sometimes called array protocol) was created in 2005 as a means for array-like Python objects to re-use each other’s data buffers intelligently whenever possible. The homogeneous N-dimensional array interface is a default mechanism for objects to share N-dimensional array memory and information. The interface consists of a Python-side and a C-side using two attributes. Objects wishing to be considered an N-dimensional array in application code should support at least one of these attributes. Objects wishing to support an N-dimensional array in application code should look for at least one of these attributes and use the information provided appropriately.

This interface describes homogeneous arrays in the sense that each item of the array has the same “type”. This type can be very simple or it can be a quite arbitrary and complicated C-like structure.

There are two ways to use the interface: A Python side and a C-side. Both are separate attributes.

Python side

This approach to the interface consists of the object having an __array_interface__ attribute.

__array_interface__

A dictionary of items (3 required and 5 optional). The optional keys in the dictionary have implied defaults if they are not provided.

The keys are:

shape (required)

Tuple whose elements are the array size in each dimension. Each entry is an integer (a Python int or long). Note that these integers could be larger than the platform “int” or “long” could hold (a Python int is a C long). It is up to the code using this attribute to handle this appropriately; either by raising an error when overflow is possible, or by using Py_LONG_LONG as the C type for the shapes.

typestr (required)

A string providing the basic type of the homogenous array The basic string format consists of 3 parts: a character describing the byteorder of the data (<: little-endian, >: big-endian, |: not-relevant), a character code giving the basic type of the array, and an integer providing the number of bytes the type uses.

The basic type character codes are:

t | Bit field (following integer gives the number of bits in the bit field).
b | Boolean (integer type where all values are only True or False)
i | Integer
u | Unsigned integer
f | Floating point
c | Complex floating point
O | Object (i.e. the memory contains a pointer to PyObject)
S | String (fixed-length sequence of char)
U | Unicode (fixed-length sequence of Py_UNICODE)
V | Other (void * – each item is a fixed-size chunk of memory)

descr (optional)

A list of tuples providing a more detailed description of the memory layout for each item in the homogeneous array. Each tuple in the list has two or three elements. Normally, this attribute would be used when typestr is V[0-9]+, but this is not a requirement. The only requirement is that the number of bytes represented in the typestr key is the same as the total number of bytes represented here. The idea is to support descriptions of C-like structs (records) that make up array elements. The elements of each tuple in the list are

  1. A string providing a name associated with this portion of the record. This could also be a tuple of ('full name', 'basic_name') where basic name would be a valid Python variable name representing the full name of the field.
  2. Either a basic-type description string as in typestr or another list (for nested records)
  3. An optional shape tuple providing how many times this part of the record should be repeated. No repeats are assumed if this is not given. Very complicated structures can be described using this generic interface. Notice, however, that each element of the array is still of the same data-type. Some examples of using this interface are given below.

Default: [('', typestr)]

data (optional)

A 2-tuple whose first argument is an integer (a long integer if necessary) that points to the data-area storing the array contents. This pointer must point to the first element of data (in other words any offset is always ignored in this case). The second entry in the tuple is a read-only flag (true means the data area is read-only).

This attribute can also be an object exposing the buffer interface which will be used to share the data. If this key is not present (or returns None), then memory sharing will be done through the buffer interface of the object itself. In this case, the offset key can be used to indicate the start of the buffer. A reference to the object exposing the array interface must be stored by the new object if the memory area is to be secured.

Default: None

strides (optional)

Either None to indicate a C-style contiguous array or a Tuple of strides which provides the number of bytes needed to jump to the next array element in the corresponding dimension. Each entry must be an integer (a Python int or long). As with shape, the values may be larger than can be represented by a C “int” or “long”; the calling code should handle this appropiately, either by raising an error, or by using Py_LONG_LONG in C. The default is None which implies a C-style contiguous memory buffer. In this model, the last dimension of the array varies the fastest. For example, the default strides tuple for an object whose array entries are 8 bytes long and whose shape is (10,20,30) would be (4800, 240, 8)

Default: None (C-style contiguous)

mask (optional)

None or an object exposing the array interface. All elements of the mask array should be interpreted only as true or not true indicating which elements of this array are valid. The shape of this object should be “broadcastable” to the shape of the original array.

Default: None (All array values are valid)

offset (optional)

An integer offset into the array data region. This can only be used when data is None or returns a buffer object.

Default: 0.

version (required)

An integer showing the version of the interface (i.e. 3 for this version). Be careful not to use this to invalidate objects exposing future versions of the interface.

C-struct access

This approach to the array interface allows for faster access to an array using only one attribute lookup and a well-defined C-structure.

__array_struct__

A PyCObject whose voidptr member contains a pointer to a filled PyArrayInterface structure. Memory for the structure is dynamically created and the PyCObject is also created with an appropriate destructor so the retriever of this attribute simply has to apply Py_DECREF to the object returned by this attribute when it is finished. Also, either the data needs to be copied out, or a reference to the object exposing this attribute must be held to ensure the data is not freed. Objects exposing the __array_struct__ interface 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 CONTIGUOUS (0x1), FORTRAN (0x2), ALIGNED (0x100), NOTSWAPPED (0x200), and WRITEABLE (0x400). A final flag 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.

New since June 16, 2006:

In the past most implementations used the “desc” member of the PyCObject itself (do not confuse this with the “descr” member of the PyArrayInterface structure above — they are two separate things) to hold the pointer to the object exposing the interface. This is now an explicit part of the interface. Be sure to own a reference to the object when the PyCObject is created using PyCObject_FromVoidPtrAndDesc.

Type description examples

For clarity it is useful to provide some examples of the type description and corresponding __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__


Datetimes and Timedeltas

  • Array objects
  • next
  • previous

Table Of Contents

  • Datetimes and Timedeltas
    • Basic Datetimes
    • Datetime and Timedelta Arithmetic
    • Datetime Units
    • Business Day Functionality
      • np.is_busday():
      • np.busday_count():
        • Custom Weekmasks
    • Differences Between 1.6 and 1.7 Datetimes
      • String Parsing
      • Unit Conversion
      • Datetime Arithmetic

Previous topic

The Array Interface

Next topic

Universal functions (ufunc)

Datetimes and Timedeltas

New in version 1.7.0.

Starting in NumPy 1.7, there are core array data types which natively support datetime functionality. The data type is called “datetime64”, so named because “datetime” is already taken by the datetime library included in Python.

Note

The datetime API is experimental in 1.7.0, and may undergo changes in future versions of NumPy.

Basic Datetimes

The most basic way to create datetimes is from strings in ISO 8601 date or datetime format. The unit for internal storage is automatically selected from the form of the string, and can be either a date unit or a time unit. The date units are years (‘Y’), months (‘M’), weeks (‘W’), and days (‘D’), while the time units are hours (‘h’), minutes (‘m’), seconds (‘s’), milliseconds (‘ms’), and some additional SI-prefix seconds-based units.

Example

A simple ISO date:

>>> np.datetime64('2005-02-25')
numpy.datetime64('2005-02-25')

Using months for the unit:

>>> np.datetime64('2005-02')
numpy.datetime64('2005-02')

Specifying just the month, but forcing a ‘days’ unit:

>>> np.datetime64('2005-02', 'D')
numpy.datetime64('2005-02-01')

Using UTC “Zulu” time:

>>> np.datetime64('2005-02-25T03:30Z')
numpy.datetime64('2005-02-24T21:30-0600')

ISO 8601 specifies to use the local time zone if none is explicitly given:

>>> np.datetime64('2005-02-25T03:30')
numpy.datetime64('2005-02-25T03:30-0600')

When creating an array of datetimes from a string, it is still possible to automatically select the unit from the inputs, by using the datetime type with generic units.

Example

>>> np.array(['2007-07-13', '2006-01-13', '2010-08-13'], dtype='datetime64')
array(['2007-07-13', '2006-01-13', '2010-08-13'], dtype='datetime64[D]')

>>> np.array(['2001-01-01T12:00', '2002-02-03T13:56:03.172'], dtype='datetime64')
array(['2001-01-01T12:00:00.000-0600', '2002-02-03T13:56:03.172-0600'], dtype='datetime64[ms]')

The datetime type works with many common NumPy functions, for example arange can be used to generate ranges of dates.

Example

All the dates for one month:

>>> np.arange('2005-02', '2005-03', dtype='datetime64[D]')
array(['2005-02-01', '2005-02-02', '2005-02-03', '2005-02-04',
       '2005-02-05', '2005-02-06', '2005-02-07', '2005-02-08',
       '2005-02-09', '2005-02-10', '2005-02-11', '2005-02-12',
       '2005-02-13', '2005-02-14', '2005-02-15', '2005-02-16',
       '2005-02-17', '2005-02-18', '2005-02-19', '2005-02-20',
       '2005-02-21', '2005-02-22', '2005-02-23', '2005-02-24',
       '2005-02-25', '2005-02-26', '2005-02-27', '2005-02-28'],
       dtype='datetime64[D]')

The datetime object represents a single moment in time. If two datetimes have different units, they may still be representing the same moment of time, and converting from a bigger unit like months to a smaller unit like days is considered a ‘safe’ cast because the moment of time is still being represented exactly.

Example

>>> np.datetime64('2005') == np.datetime64('2005-01-01')
True

>>> np.datetime64('2010-03-14T15Z') == np.datetime64('2010-03-14T15:00:00.00Z')
True

An important exception to this rule is between datetimes with date units and datetimes with time units. This is because this kind of conversion generally requires a choice of timezone and particular time of day on the given date.

Example

>>> np.datetime64('2003-12-25', 's')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: Cannot parse "2003-12-25" as unit 's' using casting rule 'same_kind'

>>> np.datetime64('2003-12-25') == np.datetime64('2003-12-25T00Z')
False

Datetime and Timedelta Arithmetic

NumPy allows the subtraction of two Datetime values, an operation which produces a number with a time unit. Because NumPy doesn’t have a physical quantities system in its core, the timedelta64 data type was created to complement datetime64.

Datetimes and Timedeltas work together to provide ways for simple datetime calculations.

Example

>>> np.datetime64('2009-01-01') - np.datetime64('2008-01-01')
numpy.timedelta64(366,'D')

>>> np.datetime64('2009') + np.timedelta64(20, 'D')
numpy.datetime64('2009-01-21')

>>> np.datetime64('2011-06-15T00:00') + np.timedelta64(12, 'h')
numpy.datetime64('2011-06-15T12:00-0500')

>>> np.timedelta64(1,'W') / np.timedelta64(1,'D')
7.0

There are two Timedelta units (‘Y’, years and ‘M’, months) which are treated specially, because how much time they represent changes depending on when they are used. While a timedelta day unit is equivalent to 24 hours, there is no way to convert a month unit into days, because different months have different numbers of days.

Example

>>> a = np.timedelta64(1, 'Y')

>>> np.timedelta64(a, 'M')
numpy.timedelta64(12,'M')

>>> np.timedelta64(a, 'D')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: Cannot cast NumPy timedelta64 scalar from metadata [Y] to [D] according to the rule 'same_kind'

Datetime Units

The Datetime and Timedelta data types support a large number of time units, as well as generic units which can be coerced into any of the other units based on input data.

Datetimes are always stored based on POSIX time (though having a TAI mode which allows for accounting of leap-seconds is proposed), with a epoch of 1970-01-01T00:00Z. This means the supported dates are always a symmetric interval around the epoch, called “time span” in the table below.

The length of the span is the range of a 64-bit integer times the length of the date or unit. For example, the time span for ‘W’ (week) is exactly 7 times longer than the time span for ‘D’ (day), and the time span for ‘D’ (day) is exactly 24 times longer than the time span for ‘h’ (hour).

Here are the date units:

Code | Meaning | Time span (relative) | Time span (absolute)
Y | year | +/- 9.2e18 years | [9.2e18 BC, 9.2e18 AD]
M | month | +/- 7.6e17 years | [7.6e17 BC, 7.6e17 AD]
W | week | +/- 1.7e17 years | [1.7e17 BC, 1.7e17 AD]
D | day | +/- 2.5e16 years | [2.5e16 BC, 2.5e16 AD]

And here are the time units:

Code | Meaning | Time span (relative) | Time span (absolute)
h | hour | +/- 1.0e15 years | [1.0e15 BC, 1.0e15 AD]
m | minute | +/- 1.7e13 years | [1.7e13 BC, 1.7e13 AD]
s | second | +/- 2.9e12 years | [ 2.9e9 BC, 2.9e9 AD]
ms | millisecond | +/- 2.9e9 years | [ 2.9e6 BC, 2.9e6 AD]
us | microsecond | +/- 2.9e6 years | [290301 BC, 294241 AD]
ns | nanosecond | +/- 292 years | [ 1678 AD, 2262 AD]
ps | picosecond | +/- 106 days | [ 1969 AD, 1970 AD]
fs | femtosecond | +/- 2.6 hours | [ 1969 AD, 1970 AD]
as | attosecond | +/- 9.2 seconds | [ 1969 AD, 1970 AD]

Business Day Functionality

To allow the datetime to be used in contexts where only certain days of the week are valid, NumPy includes a set of “busday” (business day) functions.

The default for busday functions is that the only valid days are Monday through Friday (the usual business days). The implementation is based on a “weekmask” containing 7 Boolean flags to indicate valid days; custom weekmasks are possible that specify other sets of valid days.

The “busday” functions can additionally check a list of “holiday” dates, specific dates that are not valid days.

The function busday_offset allows you to apply offsets specified in business days to datetimes with a unit of ‘D’ (day).

Example

>>> np.busday_offset('2011-06-23', 1)
numpy.datetime64('2011-06-24')

>>> np.busday_offset('2011-06-23', 2)
numpy.datetime64('2011-06-27')

When an input date falls on the weekend or a holiday, busday_offset first applies a rule to roll the date to a valid business day, then applies the offset. The default rule is ‘raise’, which simply raises an exception. The rules most typically used are ‘forward’ and ‘backward’.

Example

>>> np.busday_offset('2011-06-25', 2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: Non-business day date in busday_offset

>>> np.busday_offset('2011-06-25', 0, roll='forward')
numpy.datetime64('2011-06-27')

>>> np.busday_offset('2011-06-25', 2, roll='forward')
numpy.datetime64('2011-06-29')

>>> np.busday_offset('2011-06-25', 0, roll='backward')
numpy.datetime64('2011-06-24')

>>> np.busday_offset('2011-06-25', 2, roll='backward')
numpy.datetime64('2011-06-28')

In some cases, an appropriate use of the roll and the offset is necessary to get a desired answer.

Example

The first business day on or after a date:

>>> np.busday_offset('2011-03-20', 0, roll='forward')
numpy.datetime64('2011-03-21','D')
>>> np.busday_offset('2011-03-22', 0, roll='forward')
numpy.datetime64('2011-03-22','D')

The first business day strictly after a date:

>>> np.busday_offset('2011-03-20', 1, roll='backward')
numpy.datetime64('2011-03-21','D')
>>> np.busday_offset('2011-03-22', 1, roll='backward')
numpy.datetime64('2011-03-23','D')

The function is also useful for computing some kinds of days like holidays. In Canada and the U.S., Mother’s day is on the second Sunday in May, which can be computed with a custom weekmask.

Example

>>> np.busday_offset('2012-05', 1, roll='forward', weekmask='Sun')
numpy.datetime64('2012-05-13','D')

When performance is important for manipulating many business dates with one particular choice of weekmask and holidays, there is an object busdaycalendar which stores the data necessary in an optimized form.

np.is_busday():

To test a datetime64 value to see if it is a valid day, use is_busday.

Example

>>> np.is_busday(np.datetime64('2011-07-15'))  # a Friday
True
>>> np.is_busday(np.datetime64('2011-07-16')) # a Saturday
False
>>> np.is_busday(np.datetime64('2011-07-16'), weekmask="Sat Sun")
True
>>> a = np.arange(np.datetime64('2011-07-11'), np.datetime64('2011-07-18'))
>>> np.is_busday(a)
array([ True,  True,  True,  True,  True, False, False], dtype='bool')

np.busday_count():

To find how many valid days there are in a specified range of datetime64 dates, use busday_count:

Example

>>> np.busday_count(np.datetime64('2011-07-11'), np.datetime64('2011-07-18'))
5
>>> np.busday_count(np.datetime64('2011-07-18'), np.datetime64('2011-07-11'))
-5

If you have an array of datetime64 day values, and you want a count of how many of them are valid dates, you can do this:

Example

>>> a = np.arange(np.datetime64('2011-07-11'), np.datetime64('2011-07-18'))
>>> np.count_nonzero(np.is_busday(a))
5

Custom Weekmasks

Here are several examples of custom weekmask values. These examples specify the “busday” default of Monday through Friday being valid days.

Some examples:

# Positional sequences; positions are Monday through Sunday.
# Length of the sequence must be exactly 7.
weekmask = [1, 1, 1, 1, 1, 0, 0]
# list or other sequence; 0 == invalid day, 1 == valid day
weekmask = "1111100"
# string '0' == invalid day, '1' == valid day

# string abbreviations from this list: Mon Tue Wed Thu Fri Sat Sun
weekmask = "Mon Tue Wed Thu Fri"
# any amount of whitespace is allowed; abbreviations are case-sensitive.
weekmask = "MonTue Wed  Thu\tFri"

Differences Between 1.6 and 1.7 Datetimes

The NumPy 1.6 release includes a more primitive datetime data type than 1.7. This section documents many of the changes that have taken place.

String Parsing

The datetime string parser in NumPy 1.6 is very liberal in what it accepts, and silently allows invalid input without raising errors. The parser in NumPy 1.7 is quite strict about only accepting ISO 8601 dates, with a few convenience extensions. 1.6 always creates microsecond (us) units by default, whereas 1.7 detects a unit based on the format of the string. Here is a comparison.:

# NumPy 1.6.1
>>> np.datetime64('1979-03-22')
1979-03-22 00:00:00
# NumPy 1.7.0
>>> np.datetime64('1979-03-22')
numpy.datetime64('1979-03-22')

# NumPy 1.6.1, unit default microseconds
>>> np.datetime64('1979-03-22').dtype
dtype('datetime64[us]')
# NumPy 1.7.0, unit of days detected from string
>>> np.datetime64('1979-03-22').dtype
dtype('<M8[D]')

# NumPy 1.6.1, ignores invalid part of string
>>> np.datetime64('1979-03-2corruptedstring')
1979-03-02 00:00:00
# NumPy 1.7.0, raises error for invalid input
>>> np.datetime64('1979-03-2corruptedstring')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: Error parsing datetime string "1979-03-2corruptedstring" at position 8

# NumPy 1.6.1, 'nat' produces today's date
>>> np.datetime64('nat')
2012-04-30 00:00:00
# NumPy 1.7.0, 'nat' produces not-a-time
>>> np.datetime64('nat')
numpy.datetime64('NaT')

# NumPy 1.6.1, 'garbage' produces today's date
>>> np.datetime64('garbage')
2012-04-30 00:00:00
# NumPy 1.7.0, 'garbage' raises an exception
>>> np.datetime64('garbage')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: Error parsing datetime string "garbage" at position 0

# NumPy 1.6.1, can't specify unit in scalar constructor
>>> np.datetime64('1979-03-22T19:00', 'h')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: function takes at most 1 argument (2 given)
# NumPy 1.7.0, unit in scalar constructor
>>> np.datetime64('1979-03-22T19:00', 'h')
numpy.datetime64('1979-03-22T19:00-0500','h')

# NumPy 1.6.1, reads ISO 8601 strings w/o TZ as UTC
>>> np.array(['1979-03-22T19:00'], dtype='M8[h]')
array([1979-03-22 19:00:00], dtype=datetime64[h])
# NumPy 1.7.0, reads ISO 8601 strings w/o TZ as local (ISO specifies this)
>>> np.array(['1979-03-22T19:00'], dtype='M8[h]')
array(['1979-03-22T19-0500'], dtype='datetime64[h]')

# NumPy 1.6.1, doesn't parse all ISO 8601 strings correctly
>>> np.array(['1979-03-22T12'], dtype='M8[h]')
array([1979-03-22 00:00:00], dtype=datetime64[h])
>>> np.array(['1979-03-22T12:00'], dtype='M8[h]')
array([1979-03-22 12:00:00], dtype=datetime64[h])
# NumPy 1.7.0, handles this case correctly
>>> np.array(['1979-03-22T12'], dtype='M8[h]')
array(['1979-03-22T12-0500'], dtype='datetime64[h]')
>>> np.array(['1979-03-22T12:00'], dtype='M8[h]')
array(['1979-03-22T12-0500'], dtype='datetime64[h]')

Unit Conversion

The 1.6 implementation of datetime does not convert between units correctly.:

# NumPy 1.6.1, the representation value is untouched
>>> np.array(['1979-03-22'], dtype='M8[D]')
array([1979-03-22 00:00:00], dtype=datetime64[D])
>>> np.array(['1979-03-22'], dtype='M8[D]').astype('M8[M]')
array([2250-08-01 00:00:00], dtype=datetime64[M])
# NumPy 1.7.0, the representation is scaled accordingly
>>> np.array(['1979-03-22'], dtype='M8[D]')
array(['1979-03-22'], dtype='datetime64[D]')
>>> np.array(['1979-03-22'], dtype='M8[D]').astype('M8[M]')
array(['1979-03'], dtype='datetime64[M]')

Datetime Arithmetic

The 1.6 implementation of datetime only works correctly for a small subset of arithmetic operations. Here we show some simple cases.:

# NumPy 1.6.1, produces invalid results if units are incompatible
>>> a = np.array(['1979-03-22T12'], dtype='M8[h]')
>>> b = np.array([3*60], dtype='m8[m]')
>>> a + b
array([1970-01-01 00:00:00.080988], dtype=datetime64[us])
# NumPy 1.7.0, promotes to higher-resolution unit
>>> a = np.array(['1979-03-22T12'], dtype='M8[h]')
>>> b = np.array([3*60], dtype='m8[m]')
>>> a + b
array(['1979-03-22T15:00-0500'], dtype='datetime64[m]')

# NumPy 1.6.1, arithmetic works if everything is microseconds
>>> a = np.array(['1979-03-22T12:00'], dtype='M8[us]')
>>> b = np.array([3*60*60*1000000], dtype='m8[us]')
>>> a + b
array([1979-03-22 15:00:00], dtype=datetime64[us])
# NumPy 1.7.0
>>> a = np.array(['1979-03-22T12:00'], dtype='M8[us]')
>>> b = np.array([3*60*60*1000000], dtype='m8[us]')
>>> a + b
array(['1979-03-22T15:00:00.000000-0500'], dtype='datetime64[us]')


Universal functions (ufunc)

  • next
  • previous

Table Of Contents

  • Universal functions (ufunc)
    • Broadcasting
    • Output type determination
    • Use of internal buffers
    • Error handling
    • Casting Rules
    • Overriding Ufunc behavior
    • ufunc
      • Optional keyword arguments
      • Attributes
      • Methods
    • Available ufuncs
      • Math operations
      • Trigonometric functions
      • Bit-twiddling functions
      • Comparison functions
      • Floating functions

Previous topic

Datetimes and Timedeltas

Next topic

numpy.setbufsize

Universal functions (ufunc)

A universal function (or ufunc for short) is a function that operates on ndarrays in an element-by-element fashion, supporting array broadcasting, type casting, and several other standard features. That is, a ufunc is a “vectorized” wrapper for a function that takes a fixed number of scalar inputs and produces a fixed number of scalar outputs.

In Numpy, universal functions are instances of the numpy.ufunc class. Many of the built-in functions are implemented in compiled C code, but ufunc instances can also be produced using the frompyfunc factory function.

Broadcasting

Each universal function takes array inputs and produces array outputs by performing the core function element-wise on the inputs. Standard broadcasting rules are applied so that inputs not sharing exactly the same shapes can still be usefully operated on. Broadcasting can be understood by four rules:

  1. All input arrays with ndim smaller than the input array of largest ndim, have 1’s prepended to their shapes.
  2. The size in each dimension of the output shape is the maximum of all the input sizes in that dimension.
  3. An input can be used in the calculation if its size in a particular dimension either matches the output size in that dimension, or has value exactly 1.
  4. If an input has a dimension size of 1 in its shape, the first data entry in that dimension will be used for all calculations along that dimension. In other words, the stepping machinery of the ufunc will simply not step along that dimension (the stride will be 0 for that dimension).

Broadcasting is used throughout NumPy to decide how to handle disparately shaped arrays; for example, all arithmetic operations (+, -, *, ...) between ndarrays broadcast the arrays before operation.

A set of arrays is called “broadcastable” to the same shape if the above rules produce a valid result, i.e., one of the following is true:

  1. The arrays all have exactly the same shape.
  2. The arrays all have the same number of dimensions and the length of each dimensions is either a common length or 1.
  3. The arrays that have too few dimensions can have their shapes prepended with a dimension of length 1 to satisfy property 2.

Example

If a.shape is (5,1), b.shape is (1,6), c.shape is (6,) and d.shape is () so that d is a scalar, then a, b, c, and d are all broadcastable to dimension (5,6); and

  • a acts like a (5,6) array where a[:,0] is broadcast to the other columns,
  • b acts like a (5,6) array where b[0,:] is broadcast to the other rows,
  • c acts like a (1,6) array and therefore like a (5,6) array where c[:] is broadcast to every row, and finally,
  • d acts like a (5,6) array where the single value is repeated.

Output type determination

The output of the ufunc (and its methods) is not necessarily an ndarray, if all input arguments are not ndarrays.

All output arrays will be passed to the __array_prepare__ and __array_wrap__ methods of the input (besides ndarrays, and scalars) that defines it and has the highest __array_priority__ of any other input to the universal function. The default __array_priority__ of the ndarray is 0.0, and the default __array_priority__ of a subtype is 1.0. Matrices have __array_priority__ equal to 10.0.

All ufuncs can also take output arguments. If necessary, output will be cast to the data-type(s) of the provided output array(s). If a class with an __array__ method is used for the output, results will be written to the object returned by __array__. Then, if the class also has an __array_prepare__ method, it is called so metadata may be determined based on the context of the ufunc (the context consisting of the ufunc itself, the arguments passed to the ufunc, and the ufunc domain.) The array object returned by __array_prepare__ is passed to the ufunc for computation. Finally, if the class also has an __array_wrap__ method, the returned ndarray result will be passed to that method just before passing control back to the caller.

Use of internal buffers

Internally, buffers are used for misaligned data, swapped data, and data that has to be converted from one data type to another. The size of internal buffers is settable on a per-thread basis. There can be up to [image] buffers of the specified size created to handle the data from all the inputs and outputs of a ufunc. The default size of a buffer is 10,000 elements. Whenever buffer-based calculation would be needed, but all input arrays are smaller than the buffer size, those misbehaved or incorrectly-typed arrays will be copied before the calculation proceeds. Adjusting the size of the buffer may therefore alter the speed at which ufunc calculations of various sorts are completed. A simple interface for setting this variable is accessible using the function

setbufsize(size) Set the size of the buffer used in ufuncs.

Error handling

Universal functions can trip special floating-point status registers in your hardware (such as divide-by-zero). If available on your platform, these registers will be regularly checked during calculation. Error handling is controlled on a per-thread basis, and can be configured using the functions

seterr([all, divide, over, under, invalid]) | Set how floating-point errors are handled.
seterrcall(func) | Set the floating-point error callback function or log object.

Casting Rules

Note

In NumPy 1.6.0, a type promotion API was created to encapsulate the mechansim for determining output types. See the functions result_type, promote_types, and min_scalar_type for more details.

At the core of every ufunc is a one-dimensional strided loop that implements the actual function for a specific type combination. When a ufunc is created, it is given a static list of inner loops and a corresponding list of type signatures over which the ufunc operates. The ufunc machinery uses this list to determine which inner loop to use for a particular case. You can inspect the .types attribute for a particular ufunc to see which type combinations have a defined inner loop and which output type they produce (character codes are used in said output for brevity).

Casting must be done on one or more of the inputs whenever the ufunc does not have a core loop implementation for the input types provided. If an implementation for the input types cannot be found, then the algorithm searches for an implementation with a type signature to which all of the inputs can be cast “safely.” The first one it finds in its internal list of loops is selected and performed, after all necessary type casting. Recall that internal copies during ufuncs (even for casting) are limited to the size of an internal buffer (which is user settable).

Note

Universal functions in NumPy are flexible enough to have mixed type signatures. Thus, for example, a universal function could be defined that works with floating-point and integer values. See ldexp for an example.

By the above description, the casting rules are essentially implemented by the question of when a data type can be cast “safely” to another data type. The answer to this question can be determined in Python with a function call: can_cast(fromtype, totype). The Figure below shows the results of this call for the 24 internally supported types on the author’s 64-bit system. You can generate this table for your system with the code given in the Figure.

Figure

Code segment showing the “can cast safely” table for a 32-bit system.

>>> def print_table(ntypes):
...     print 'X',
...     for char in ntypes: print char,
...     print
...     for row in ntypes:
...         print row,
...         for col in ntypes:
...             print int(np.can_cast(row, col)),
...         print
>>> print_table(np.typecodes['All'])
X ? b h i l q p B H I L Q P e f d g F D G S U V O M m
? 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
b 0 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1 0 0
h 0 0 1 1 1 1 1 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 0 0
i 0 0 0 1 1 1 1 0 0 0 0 0 0 0 0 1 1 0 1 1 1 1 1 1 0 0
l 0 0 0 0 1 1 1 0 0 0 0 0 0 0 0 1 1 0 1 1 1 1 1 1 0 0
q 0 0 0 0 1 1 1 0 0 0 0 0 0 0 0 1 1 0 1 1 1 1 1 1 0 0
p 0 0 0 0 1 1 1 0 0 0 0 0 0 0 0 1 1 0 1 1 1 1 1 1 0 0
B 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0
H 0 0 0 1 1 1 1 0 1 1 1 1 1 0 1 1 1 1 1 1 1 1 1 1 0 0
I 0 0 0 0 1 1 1 0 0 1 1 1 1 0 0 1 1 0 1 1 1 1 1 1 0 0
L 0 0 0 0 0 0 0 0 0 0 1 1 1 0 0 1 1 0 1 1 1 1 1 1 0 0
Q 0 0 0 0 0 0 0 0 0 0 1 1 1 0 0 1 1 0 1 1 1 1 1 1 0 0
P 0 0 0 0 0 0 0 0 0 0 1 1 1 0 0 1 1 0 1 1 1 1 1 1 0 0
e 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1 0 0
f 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 0 0
d 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 1 1 1 1 1 1 0 0
g 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 1 1 1 1 0 0
F 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 0 0
D 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 0 0
G 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 0 0
S 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 0 0
U 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 0
V 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0
O 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0
M 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0
m 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1

You should note that, while included in the table for completeness, the ‘S’, ‘U’, and ‘V’ types cannot be operated on by ufuncs. Also, note that on a 32-bit system the integer types may have different sizes, resulting in a slightly altered table.

Mixed scalar-array operations use a different set of casting rules that ensure that a scalar cannot “upcast” an array unless the scalar is of a fundamentally different kind of data (i.e., under a different hierarchy in the data-type hierarchy) than the array. This rule enables you to use scalar constants in your code (which, as Python types, are interpreted accordingly in ufuncs) without worrying about whether the precision of the scalar constant will cause upcasting on your large (small precision) array.

Overriding Ufunc behavior

Classes (including ndarray subclasses) can override how ufuncs act on them by defining certain special methods. For details, see Standard array subclasses.

ufunc

Optional keyword arguments

All ufuncs take optional keyword arguments. Most of these represent advanced usage and will not typically be used.

out

New in version 1.6.

The first output can provided as either a positional or a keyword parameter.

where

New in version 1.7.

Accepts a boolean array which is broadcast together with the operands. Values of True indicate to calculate the ufunc at that position, values of False indicate to leave the value in the output alone.

casting

New in version 1.6.

May be ‘no’, ‘equiv’, ‘safe’, ‘same_kind’, or ‘unsafe’. See can_cast for explanations of the parameter values.

Provides a policy for what kind of casting is permitted. For compatibility with previous versions of NumPy, this defaults to ‘unsafe’ for numpy < 1.7. In numpy 1.7 a transition to ‘same_kind’ was begun where ufuncs produce a DeprecationWarning for calls which are allowed under the ‘unsafe’ rules, but not under the ‘same_kind’ rules. In numpy 1.10 the default will be ‘same_kind’.

order

New in version 1.6.

Specifies the calculation iteration order/memory layout of the output array. Defaults to ‘K’. ‘C’ means the output should be C-contiguous, ‘F’ means F-contiguous, ‘A’ means F-contiguous if the inputs are F-contiguous and not also not C-contiguous, C-contiguous otherwise, and ‘K’ means to match the element ordering of the inputs as closely as possible.

dtype

New in version 1.6.

Overrides the dtype of the calculation and output arrays. Similar to sig.

subok

New in version 1.6.

Defaults to true. If set to false, the output will always be a strict array, not a subtype.

sig

Either a data-type, a tuple of data-types, or a special signature string indicating the input and output types of a ufunc. This argument allows you to provide a specific signature for the 1-d loop to use in the underlying calculation. If the loop specified does not exist for the ufunc, then a TypeError is raised. Normally, a suitable loop is found automatically by comparing the input types with what is available and searching for a loop with data-types to which all inputs can be cast safely. This keyword argument lets you bypass that search and choose a particular loop. A list of available signatures is provided by the types attribute of the ufunc object.

extobj

a list of length 1, 2, or 3 specifying the ufunc buffer-size, the error mode integer, and the error call-back function. Normally, these values are looked up in a thread-specific dictionary. Passing them here circumvents that look up and uses the low-level specification provided for the error mode. This may be useful, for example, as an optimization for calculations requiring many ufunc calls on small arrays in a loop.

Attributes

There are some informational attributes that universal functions possess. None of the attributes can be set.

__doc__ | A docstring for each ufunc. The first part of the docstring is dynamically generated from the number of outputs, the name, and the number of inputs. The second part of the docstring is provided at creation time and stored with the ufunc.
__name__ | The name of the ufunc.
ufunc.nin | The number of inputs.
ufunc.nout | The number of outputs.
ufunc.nargs | The number of arguments.
ufunc.ntypes | The number of types.
ufunc.types | Returns a list with types grouped input->output.
ufunc.identity | The identity value.

Methods

All ufuncs have four methods. However, these methods only make sense on ufuncs that take two input arguments and return one output argument. Attempting to call these methods on other ufuncs will cause a ValueError. The reduce-like methods all take an axis keyword and a dtype keyword, and the arrays must all have dimension >= 1. The axis keyword specifies the axis of the array over which the reduction will take place and may be negative, but must be an integer. The dtype keyword allows you to manage a very common problem that arises when naively using {op}.reduce. Sometimes you may have an array of a certain data type and wish to add up all of its elements, but the result does not fit into the data type of the array. This commonly happens if you have an array of single-byte integers. The dtype keyword allows you to alter the data type over which the reduction takes place (and therefore the type of the output). Thus, you can ensure that the output is a data type with precision large enough to handle your output. The responsibility of altering the reduce type is mostly up to you. There is one exception: if no dtype is given for a reduction on the “add” or “multiply” operations, then if the input type is an integer (or Boolean) data-type and smaller than the size of the int_ data type, it will be internally upcast to the int_ (or uint) data-type.

Ufuncs also have a fifth method that allows in place operations to be performed using fancy indexing. No buffering is used on the dimensions where fancy indexing is used, so the fancy index can list an item more than once and the operation will be performed on the result of the previous operation for that item.

ufunc.reduce(a[, axis, dtype, out, keepdims]) | Reduces a‘s dimension by one, by applying ufunc along one axis.
ufunc.accumulate(array[, axis, dtype, out]) | Accumulate the result of applying the operator to all elements.
ufunc.reduceat(a, indices[, axis, dtype, out]) | Performs a (local) reduce with specified slices over a single axis.
ufunc.outer(A, B) | Apply the ufunc op to all pairs (a, b) with a in A and b in B.
ufunc.at(a, indices[, b]) | Performs unbuffered in place operation on operand ‘a’ for elements specified by ‘indices’.

Warning

A reduce-like operation on an array with a data-type that has a range “too small” to handle the result will silently wrap. One should use dtype to increase the size of the data-type over which reduction takes place.

Available ufuncs

There are currently more than 60 universal functions defined in numpy on one or more types, covering a wide variety of operations. Some of these ufuncs are called automatically on arrays when the relevant infix notation is used (e.g., add(a, b) is called internally when a + b is written and a or b is an ndarray). Nevertheless, you may still want to use the ufunc call in order to use the optional output argument(s) to place the output(s) in an object (or objects) of your choice.

Recall that each ufunc operates element-by-element. Therefore, each ufunc will be described as if acting on a set of scalar inputs to return a set of scalar outputs.

Note

The ufunc still returns its output(s) even if you use the optional output argument(s).

Math operations

add(x1, x2[, out]) | Add arguments element-wise.
subtract(x1, x2[, out]) | Subtract arguments, element-wise.
multiply(x1, x2[, out]) | Multiply arguments element-wise.
divide(x1, x2[, out]) | Divide arguments element-wise.
logaddexp(x1, x2[, out]) | Logarithm of the sum of exponentiations of the inputs.
logaddexp2(x1, x2[, out]) | Logarithm of the sum of exponentiations of the inputs in base-2.
true_divide(x1, x2[, out]) | Returns a true division of the inputs, element-wise.
floor_divide(x1, x2[, out]) | Return the largest integer smaller or equal to the division of the inputs.
negative(x[, out]) | Numerical negative, element-wise.
power(x1, x2[, out]) | First array elements raised to powers from second array, element-wise.
remainder(x1, x2[, out]) | Return element-wise remainder of division.
mod(x1, x2[, out]) | Return element-wise remainder of division.
fmod(x1, x2[, out]) | Return the element-wise remainder of division.
absolute(x[, out]) | Calculate the absolute value element-wise.
rint(x[, out]) | Round elements of the array to the nearest integer.
sign(x[, out]) | Returns an element-wise indication of the sign of a number.
conj(x[, out]) | Return the complex conjugate, element-wise.
exp(x[, out]) | Calculate the exponential of all elements in the input array.
exp2(x[, out]) | Calculate 2**p for all p in the input array.
log(x[, out]) | Natural logarithm, element-wise.
log2(x[, out]) | Base-2 logarithm of x.
log10(x[, out]) | Return the base 10 logarithm of the input array, element-wise.
expm1(x[, out]) | Calculate exp(x) - 1 for all elements in the array.
log1p(x[, out]) | Return the natural logarithm of one plus the input array, element-wise.
sqrt(x[, out]) | Return the positive square-root of an array, element-wise.
square(x[, out]) | Return the element-wise square of the input.
reciprocal(x[, out]) | Return the reciprocal of the argument, element-wise.
ones_like(a[, dtype, order, subok]) | Return an array of ones with the same shape and type as a given array.

Tip

The optional output arguments can be used to help you save memory for large calculations. If your arrays are large, complicated expressions can take longer than absolutely necessary due to the creation and (later) destruction of temporary calculation spaces. For example, the expression G = a * b + c is equivalent to t1 = A * B; G = T1 + C; del t1. It will be more quickly executed as G = A * B; add(G, C, G) which is the same as G = A * B; G += C.

Trigonometric functions

All trigonometric functions use radians when an angle is called for. The ratio of degrees to radians is

sin(x[, out]) | Trigonometric sine, element-wise.
cos(x[, out]) | Cosine element-wise.
tan(x[, out]) | Compute tangent element-wise.
arcsin(x[, out]) | Inverse sine, element-wise.
arccos(x[, out]) | Trigonometric inverse cosine, element-wise.
arctan(x[, out]) | Trigonometric inverse tangent, element-wise.
arctan2(x1, x2[, out]) | Element-wise arc tangent of x1/x2 choosing the quadrant correctly.
hypot(x1, x2[, out]) | Given the “legs” of a right triangle, return its hypotenuse.
sinh(x[, out]) | Hyperbolic sine, element-wise.
cosh(x[, out]) | Hyperbolic cosine, element-wise.
tanh(x[, out]) | Compute hyperbolic tangent element-wise.
arcsinh(x[, out]) | Inverse hyperbolic sine element-wise.
arccosh(x[, out]) | Inverse hyperbolic cosine, element-wise.
arctanh(x[, out]) | Inverse hyperbolic tangent element-wise.
deg2rad(x[, out]) | Convert angles from degrees to radians.
rad2deg(x[, out]) | Convert angles from radians to degrees.

Bit-twiddling functions

These function all require integer arguments and they manipulate the bit-pattern of those arguments.

bitwise_and(x1, x2[, out]) | Compute the bit-wise AND of two arrays element-wise.
bitwise_or(x1, x2[, out]) | Compute the bit-wise OR of two arrays element-wise.
bitwise_xor(x1, x2[, out]) | Compute the bit-wise XOR of two arrays element-wise.
invert(x[, out]) | Compute bit-wise inversion, or bit-wise NOT, element-wise.
left_shift(x1, x2[, out]) | Shift the bits of an integer to the left.
right_shift(x1, x2[, out]) | Shift the bits of an integer to the right.

Comparison functions

greater(x1, x2[, out]) | Return the truth value of (x1 > x2) element-wise.
greater_equal(x1, x2[, out]) | Return the truth value of (x1 >= x2) element-wise.
less(x1, x2[, out]) | Return the truth value of (x1 < x2) element-wise.
less_equal(x1, x2[, out]) | Return the truth value of (x1 =< x2) element-wise.
not_equal(x1, x2[, out]) | Return (x1 != x2) element-wise.
equal(x1, x2[, out]) | Return (x1 == x2) element-wise.

Warning

Do not use the Python keywords and and or to combine logical array expressions. These keywords will test the truth value of the entire array (not element-by-element as you might expect). Use the bitwise operators & and | instead.

logical_and(x1, x2[, out]) | Compute the truth value of x1 AND x2 element-wise.
logical_or(x1, x2[, out]) | Compute the truth value of x1 OR x2 element-wise.
logical_xor(x1, x2[, out]) | Compute the truth value of x1 XOR x2, element-wise.
logical_not(x[, out]) | Compute the truth value of NOT x element-wise.

Warning

The bit-wise operators & and | are the proper way to perform element-by-element array comparisons. Be sure you understand the operator precedence: (a > 2) & (a < 5) is the proper syntax because a > 2 & a < 5 will result in an error due to the fact that 2 & a is evaluated first.

maximum(x1, x2[, out]) Element-wise maximum of array elements.

Tip

The Python function max() will find the maximum over a one-dimensional array, but it will do so using a slower sequence interface. The reduce method of the maximum ufunc is much faster. Also, the max() method will not give answers you might expect for arrays with greater than one dimension. The reduce method of minimum also allows you to compute a total minimum over an array.

minimum(x1, x2[, out]) Element-wise minimum of array elements.

Warning

the behavior of maximum(a, b) is different than that of max(a, b). As a ufunc, maximum(a, b) performs an element-by-element comparison of a and b and chooses each element of the result according to which element in the two arrays is larger. In contrast, max(a, b) treats the objects a and b as a whole, looks at the (total) truth value of a > b and uses it to return either a or b (as a whole). A similar difference exists between minimum(a, b) and min(a, b).

fmax(x1, x2[, out]) | Element-wise maximum of array elements.
fmin(x1, x2[, out]) | Element-wise minimum of array elements.

Floating functions

Recall that all of these functions work element-by-element over an array, returning an array output. The description details only a single operation.

isreal(x) | Returns a bool array, where True if input element is real.
iscomplex(x) | Returns a bool array, where True if input element is complex.
isfinite(x[, out]) | Test element-wise for finiteness (not infinity or not Not a Number).
isinf(x[, out]) | Test element-wise for positive or negative infinity.
isnan(x[, out]) | Test element-wise for NaN and return result as a boolean array.
signbit(x[, out]) | Returns element-wise True where signbit is set (less than zero).
copysign(x1, x2[, out]) | Change the sign of x1 to that of x2, element-wise.
nextafter(x1, x2[, out]) | Return the next floating-point value after x1 towards x2, element-wise.
modf(x[, out1, out2]) | Return the fractional and integral parts of an array, element-wise.
ldexp(x1, x2[, out]) | Returns x1 * 2**x2, element-wise.
frexp(x[, out1, out2]) | Decompose the elements of x into mantissa and twos exponent.
fmod(x1, x2[, out]) | Return the element-wise remainder of division.
floor(x[, out]) | Return the floor of the input, element-wise.
ceil(x[, out]) | Return the ceiling of the input, element-wise.
trunc(x[, out]) | Return the truncated value of the input, element-wise.


numpy.setbufsize

  • Miscellaneous routines
  • next
  • previous

Previous topic

numpy.restoredot

Next topic

numpy.getbufsize

numpy.setbufsize

numpy.setbufsize(size) [source]

Set the size of the buffer used in ufuncs.

Parameters:

size : int

Size of buffer.


numpy.seterr

  • Floating point error handling
  • next
  • previous

Previous topic

numpy.geterrobj

Next topic

numpy.geterr

numpy.seterr

numpy.seterr(all=None, divide=None, over=None, under=None, invalid=None) [source]

Set how floating-point errors are handled.

Note that operations on integer scalar types (such as int16) are handled like floating point, and are affected by these settings.

Parameters:

all : {‘ignore’, ‘warn’, ‘raise’, ‘call’, ‘print’, ‘log’}, optional

Set treatment for all types of floating-point errors at once:

  • ignore: Take no action when the exception occurs.
  • warn: Print a RuntimeWarning (via the Python warnings module).
  • raise: Raise a FloatingPointError.
  • call: Call a function specified using the seterrcall function.
  • print: Print a warning directly to stdout.
  • log: Record error in a Log object specified by seterrcall.

The default is not to change the current behavior.

divide : {‘ignore’, ‘warn’, ‘raise’, ‘call’, ‘print’, ‘log’}, optional

Treatment for division by zero.

over : {‘ignore’, ‘warn’, ‘raise’, ‘call’, ‘print’, ‘log’}, optional

Treatment for floating-point overflow.

under : {‘ignore’, ‘warn’, ‘raise’, ‘call’, ‘print’, ‘log’}, optional

Treatment for floating-point underflow.

invalid : {‘ignore’, ‘warn’, ‘raise’, ‘call’, ‘print’, ‘log’}, optional

Treatment for invalid floating-point operation.
Returns:

old_settings : dict

Dictionary containing the old settings.

See also

seterrcall
Set a callback function for the ‘call’ mode.

geterr, geterrcall, errstate

Notes

The floating-point exceptions are defined in the IEEE 754 standard [1]:

  • Division by zero: infinite result obtained from finite numbers.
  • Overflow: result too large to be expressed.
  • Underflow: result so close to zero that some precision was lost.
  • Invalid operation: result is not an expressible number, typically indicates that a NaN was produced.
[R245] http://en.wikipedia.org/wiki/IEEE_754

Examples

>>> old_settings = np.seterr(all='ignore')  #seterr to known value
>>> np.seterr(over='raise')
{'over': 'ignore', 'divide': 'ignore', 'invalid': 'ignore',
 'under': 'ignore'}
>>> np.seterr(**old_settings)  # reset to default
{'over': 'raise', 'divide': 'ignore', 'invalid': 'ignore', 'under': 'ignore'}

>>> np.int16(32000) * np.int16(3)
30464
>>> old_settings = np.seterr(all='warn', over='raise')
>>> np.int16(32000) * np.int16(3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
FloatingPointError: overflow encountered in short_scalars

>>> old_settings = np.seterr(all='print')
>>> np.geterr()
{'over': 'print', 'divide': 'print', 'invalid': 'print', 'under': 'print'}
>>> np.int16(32000) * np.int16(3)
Warning: overflow encountered in short_scalars
30464


numpy.seterrcall

  • Floating point error handling
  • next
  • previous

Previous topic

numpy.geterr

Next topic

numpy.geterrcall

numpy.seterrcall

numpy.seterrcall(func) [source]

Set the floating-point error callback function or log object.

There are two ways to capture floating-point error messages. The first is to set the error-handler to ‘call’, using seterr. Then, set the function to call using this function.

The second is to set the error-handler to ‘log’, using seterr. Floating-point errors then trigger a call to the ‘write’ method of the provided object.

Parameters:

func : callable f(err, flag) or object with write method

Function to call upon floating-point errors (‘call’-mode) or object whose ‘write’ method is used to log such message (‘log’-mode).

The call function takes two arguments. The first is the type of error (one of “divide”, “over”, “under”, or “invalid”), and the second is the status flag. The flag is a byte, whose least-significant bits indicate the status:

[0 0 0 0 invalid over under invalid]

In other words, flags = divide + 2*over + 4*under + 8*invalid.

If an object is provided, its write method should take one argument, a string.
Returns:

h : callable, log instance or None

The old error handler.

See also

seterr, geterr, geterrcall

Examples

Callback upon error:

>>> def err_handler(type, flag):
...     print "Floating point error (%s), with flag %s" % (type, flag)
...

>>> saved_handler = np.seterrcall(err_handler)
>>> save_err = np.seterr(all='call')

>>> np.array([1, 2, 3]) / 0.0
Floating point error (divide by zero), with flag 1
array([ Inf,  Inf,  Inf])

>>> np.seterrcall(saved_handler)
<function err_handler at 0x...>
>>> np.seterr(**save_err)
{'over': 'call', 'divide': 'call', 'invalid': 'call', 'under': 'call'}

Log error message:

>>> class Log(object):
...     def write(self, msg):
...         print "LOG: %s" % msg
...

>>> log = Log()
>>> saved_handler = np.seterrcall(log)
>>> save_err = np.seterr(all='log')

>>> np.array([1, 2, 3]) / 0.0
LOG: Warning: divide by zero encountered in divide

array([ Inf,  Inf,  Inf])

>>> np.seterrcall(saved_handler)
<__main__.Log object at 0x...>
>>> np.seterr(**save_err)
{'over': 'log', 'divide': 'log', 'invalid': 'log', 'under': 'log'}


numpy.ufunc.nin

  • Universal functions (ufunc)
  • index
  • next
  • previous

Previous topic

numpy.seterrcall

Next topic

numpy.ufunc.nout

numpy.ufunc.nin

ufunc.nin

The number of inputs.

Data attribute containing the number of arguments the ufunc treats as input.

Examples

>>> np.add.nin
2
>>> np.multiply.nin
2
>>> np.power.nin
2
>>> np.exp.nin
1


numpy.ufunc.nout

  • Universal functions (ufunc)
  • index
  • next
  • previous

Previous topic

numpy.ufunc.nin

Next topic

numpy.ufunc.nargs

numpy.ufunc.nout

ufunc.nout

The number of outputs.

Data attribute containing the number of arguments the ufunc treats as output.

Notes

Since all ufuncs can take output arguments, this will always be (at least) 1.

Examples

>>> np.add.nout
1
>>> np.multiply.nout
1
>>> np.power.nout
1
>>> np.exp.nout
1


numpy.ufunc.nargs

  • Universal functions (ufunc)
  • index
  • next
  • previous

Previous topic

numpy.ufunc.nout

Next topic

numpy.ufunc.ntypes

numpy.ufunc.nargs

ufunc.nargs

The number of arguments.

Data attribute containing the number of arguments the ufunc takes, including optional ones.

Notes

Typically this value will be one more than what you might expect because all ufuncs take the optional “out” argument.

Examples

>>> np.add.nargs
3
>>> np.multiply.nargs
3
>>> np.power.nargs
3
>>> np.exp.nargs
2


numpy.ufunc.ntypes

  • Universal functions (ufunc)
  • index
  • next
  • previous

Previous topic

numpy.ufunc.nargs

Next topic

numpy.ufunc.types

numpy.ufunc.ntypes

ufunc.ntypes

The number of types.

The number of numerical NumPy types - of which there are 18 total - on which the ufunc can operate.

See also

numpy.ufunc.types

Examples

>>> np.add.ntypes
18
>>> np.multiply.ntypes
18
>>> np.power.ntypes
17
>>> np.exp.ntypes
7
>>> np.remainder.ntypes
14


numpy.ufunc.types

  • Universal functions (ufunc)
  • index
  • next
  • previous

Previous topic

numpy.ufunc.ntypes

Next topic

numpy.ufunc.identity

numpy.ufunc.types

ufunc.types

Returns a list with types grouped input->output.

Data attribute listing the data-type “Domain-Range” groupings the ufunc can deliver. The data-types are given using the character codes.

See also

numpy.ufunc.ntypes

Examples

>>> np.add.types
['??->?', 'bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l',
'LL->L', 'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'FF->F', 'DD->D',
'GG->G', 'OO->O']

>>> np.multiply.types
['??->?', 'bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l',
'LL->L', 'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'FF->F', 'DD->D',
'GG->G', 'OO->O']

>>> np.power.types
['bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l', 'LL->L',
'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'FF->F', 'DD->D', 'GG->G',
'OO->O']

>>> np.exp.types
['f->f', 'd->d', 'g->g', 'F->F', 'D->D', 'G->G', 'O->O']

>>> np.remainder.types
['bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l', 'LL->L',
'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'OO->O']


numpy.ufunc.identity

  • Universal functions (ufunc)
  • index
  • next
  • previous

Previous topic

numpy.ufunc.types

Next topic

numpy.ufunc.reduce

numpy.ufunc.identity

ufunc.identity

The identity value.

Data attribute containing the identity element for the ufunc, if it has one. If it does not, the attribute value is None.

Examples

>>> np.add.identity
0
>>> np.multiply.identity
1
>>> np.power.identity
1
>>> print np.exp.identity
None


numpy.ufunc.reduce

  • Universal functions (ufunc)
  • index
  • next
  • previous

Previous topic

numpy.ufunc.identity

Next topic

numpy.ufunc.accumulate

numpy.ufunc.reduce

ufunc.reduce(a, axis=0, dtype=None, out=None, keepdims=False)

Reduces a‘s dimension by one, by applying ufunc along one axis.

Let a.shape = (N_0, ..., N_i, ..., N_{M-1}). Then ufunc.reduce(a, axis=i)[k_0, ..,k_{i-1}, k_{i+1}, .., k_{M-1}] = the result of iterating j over [image], cumulatively applying ufunc to each a[k_0, ..,k_{i-1}, j, k_{i+1}, .., k_{M-1}]. For a one-dimensional array, reduce produces results equivalent to:

r = op.identity # op = ufunc
for i in range(len(A)):
  r = op(r, A[i])
return r

For example, add.reduce() is equivalent to sum().

Parameters:

a : array_like

The array to act on.

axis : None or int or tuple of ints, optional

Axis or axes along which a reduction is performed. The default (axis = 0) is perform a reduction over the first dimension of the input array. axis may be negative, in which case it counts from the last to the first axis.

New in version 1.7.0.

If this is None, a reduction is performed over all the axes. If this is a tuple of ints, a reduction is performed on multiple axes, instead of a single axis or all the axes as before.

For operations which are either not commutative or not associative, doing a reduction over multiple axes is not well-defined. The ufuncs do not currently raise an exception in this case, but will likely do so in the future.

dtype : data-type code, optional

The type used to represent the intermediate results. Defaults to the data-type of the output array if this is provided, or the data-type of the input array if no output array is provided.

out : ndarray, optional

A location into which the result is stored. If not provided, a freshly-allocated array is returned.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.

New in version 1.7.0.
Returns:

r : ndarray

The reduced array. If out was supplied, r is a reference to it.

Examples

>>> np.multiply.reduce([2,3,5])
30

A multi-dimensional array example:

>>> X = np.arange(8).reshape((2,2,2))
>>> X
array([[[0, 1],
        [2, 3]],
       [[4, 5],
        [6, 7]]])
>>> np.add.reduce(X, 0)
array([[ 4,  6],
       [ 8, 10]])
>>> np.add.reduce(X) # confirm: default axis value is 0
array([[ 4,  6],
       [ 8, 10]])
>>> np.add.reduce(X, 1)
array([[ 2,  4],
       [10, 12]])
>>> np.add.reduce(X, 2)
array([[ 1,  5],
       [ 9, 13]])


numpy.ufunc.accumulate

  • Universal functions (ufunc)
  • index
  • next
  • previous

Previous topic

numpy.ufunc.reduce

Next topic

numpy.ufunc.reduceat

numpy.ufunc.accumulate

ufunc.accumulate(array, axis=0, dtype=None, out=None)

Accumulate the result of applying the operator to all elements.

For a one-dimensional array, accumulate produces results equivalent to:

r = np.empty(len(A))
t = op.identity        # op = the ufunc being applied to A's  elements
for i in range(len(A)):
    t = op(t, A[i])
    r[i] = t
return r

For example, add.accumulate() is equivalent to np.cumsum().

For a multi-dimensional array, accumulate is applied along only one axis (axis zero by default; see Examples below) so repeated use is necessary if one wants to accumulate over multiple axes.

Parameters:

array : array_like

The array to act on.

axis : int, optional

The axis along which to apply the accumulation; default is zero.

dtype : data-type code, optional

The data-type used to represent the intermediate results. Defaults to the data-type of the output array if such is provided, or the the data-type of the input array if no output array is provided.

out : ndarray, optional

A location into which the result is stored. If not provided a freshly-allocated array is returned.
Returns:

r : ndarray

The accumulated values. If out was supplied, r is a reference to out.

Examples

1-D array examples:

>>> np.add.accumulate([2, 3, 5])
array([ 2,  5, 10])
>>> np.multiply.accumulate([2, 3, 5])
array([ 2,  6, 30])

2-D array examples:

>>> I = np.eye(2)
>>> I
array([[ 1.,  0.],
       [ 0.,  1.]])

Accumulate along axis 0 (rows), down columns:

>>> np.add.accumulate(I, 0)
array([[ 1.,  0.],
       [ 1.,  1.]])
>>> np.add.accumulate(I) # no axis specified = axis zero
array([[ 1.,  0.],
       [ 1.,  1.]])

Accumulate along axis 1 (columns), through rows:

>>> np.add.accumulate(I, 1)
array([[ 1.,  1.],
       [ 0.,  1.]])


numpy.ufunc.reduceat

  • Universal functions (ufunc)
  • index
  • next
  • previous

Previous topic

numpy.ufunc.accumulate

Next topic

numpy.ufunc.outer

numpy.ufunc.reduceat

ufunc.reduceat(a, indices, axis=0, dtype=None, out=None)

Performs a (local) reduce with specified slices over a single axis.

For i in range(len(indices)), reduceat computes ufunc.reduce(a[indices[i]:indices[i+1]]), which becomes the i-th generalized “row” parallel to axis in the final result (i.e., in a 2-D array, for example, if axis = 0, it becomes the i-th row, but if axis = 1, it becomes the i-th column). There are three exceptions to this:

  • when i = len(indices) - 1 (so for the last index), indices[i+1] = a.shape[axis].
  • if indices[i] >= indices[i + 1], the i-th generalized “row” is simply a[indices[i]].
  • if indices[i] >= len(a) or indices[i] < 0, an error is raised.

The shape of the output depends on the size of indices, and may be larger than a (this happens if len(indices) > a.shape[axis]).

Parameters:

a : array_like

The array to act on.

indices : array_like

Paired indices, comma separated (not colon), specifying slices to reduce.

axis : int, optional

The axis along which to apply the reduceat.

dtype : data-type code, optional

The type used to represent the intermediate results. Defaults to the data type of the output array if this is provided, or the data type of the input array if no output array is provided.

out : ndarray, optional

A location into which the result is stored. If not provided a freshly-allocated array is returned.
Returns:

r : ndarray

The reduced values. If out was supplied, r is a reference to out.

Notes

A descriptive example:

If a is 1-D, the function ufunc.accumulate(a) is the same as ufunc.reduceat(a, indices)[::2] where indices is range(len(array) - 1) with a zero placed in every other element: indices = zeros(2 * len(a) - 1), indices[1::2] = range(1, len(a)).

Don’t be fooled by this attribute’s name: reduceat(a) is not necessarily smaller than a.

Examples

To take the running sum of four successive values:

>>> np.add.reduceat(np.arange(8),[0,4, 1,5, 2,6, 3,7])[::2]
array([ 6, 10, 14, 18])

A 2-D example:

>>> x = np.linspace(0, 15, 16).reshape(4,4)
>>> x
array([[  0.,   1.,   2.,   3.],
       [  4.,   5.,   6.,   7.],
       [  8.,   9.,  10.,  11.],
       [ 12.,  13.,  14.,  15.]])

# reduce such that the result has the following five rows:
# [row1 + row2 + row3]
# [row4]
# [row2]
# [row3]
# [row1 + row2 + row3 + row4]

>>> np.add.reduceat(x, [0, 3, 1, 2, 0])
array([[ 12.,  15.,  18.,  21.],
       [ 12.,  13.,  14.,  15.],
       [  4.,   5.,   6.,   7.],
       [  8.,   9.,  10.,  11.],
       [ 24.,  28.,  32.,  36.]])

# reduce such that result has the following two columns:
# [col1 * col2 * col3, col4]

>>> np.multiply.reduceat(x, [0, 3], 1)
array([[    0.,     3.],
       [  120.,     7.],
       [  720.,    11.],
       [ 2184.,    15.]])


numpy.ufunc.outer

  • Universal functions (ufunc)
  • index
  • next
  • previous

Previous topic

numpy.ufunc.reduceat

Next topic

numpy.ufunc.at

numpy.ufunc.outer

ufunc.outer(A, B)

Apply the ufunc op to all pairs (a, b) with a in A and b in B.

Let M = A.ndim, N = B.ndim. Then the result, C, of op.outer(A, B) is an array of dimension M + N such that:

C[i_0, ..., i_{M-1}, j_0, ..., j_{N-1}] = op(A[i_0, ..., i_{M-1}], B[j_0, ..., j_{N-1}])

For A and B one-dimensional, this is equivalent to:

r = empty(len(A),len(B))
for i in range(len(A)):
    for j in range(len(B)):
        r[i,j] = op(A[i], B[j]) # op = ufunc in question
Parameters:

A : array_like

First array

B : array_like

Second array
Returns:

r : ndarray

Output array

See also

numpy.outer

Examples

>>> np.multiply.outer([1, 2, 3], [4, 5, 6])
array([[ 4,  5,  6],
       [ 8, 10, 12],
       [12, 15, 18]])

A multi-dimensional example:

>>> A = np.array([[1, 2, 3], [4, 5, 6]])
>>> A.shape
(2, 3)
>>> B = np.array([[1, 2, 3, 4]])
>>> B.shape
(1, 4)
>>> C = np.multiply.outer(A, B)
>>> C.shape; C
(2, 3, 1, 4)
array([[[[ 1,  2,  3,  4]],
        [[ 2,  4,  6,  8]],
        [[ 3,  6,  9, 12]]],
       [[[ 4,  8, 12, 16]],
        [[ 5, 10, 15, 20]],
        [[ 6, 12, 18, 24]]]])


numpy.ufunc.at

  • Universal functions (ufunc)
  • index
  • next
  • previous

Previous topic

numpy.ufunc.outer

Next topic

Routines

numpy.ufunc.at

ufunc.at(a, indices, b=None)

Performs unbuffered in place operation on operand ‘a’ for elements specified by ‘indices’. For addition ufunc, this method is equivalent to a[indices] += b, except that results are accumulated for elements that are indexed more than once. For example, a[[0,0]] += 1 will only increment the first element once because of buffering, whereas add.at(a, [0,0], 1) will increment the first element twice.

New in version 1.8.0.

Parameters:

a : array_like

The array to perform in place operation on.

indices : array_like or tuple

Array like index object or slice object for indexing into first operand. If first operand has multiple dimensions, indices can be a tuple of array like index objects or slice objects.

b : array_like

Second operand for ufuncs requiring two operands. Operand must be broadcastable over first operand after indexing or slicing.

Examples

Set items 0 and 1 to their negative values:

>>> a = np.array([1, 2, 3, 4])
>>> np.negative.at(a, [0, 1])
>>> print(a)
array([-1, -2, 3, 4])

Increment items 0 and 1, and increment item 2 twice:

>>> a = np.array([1, 2, 3, 4])
>>> np.add.at(a, [0, 1, 2, 2], 1)
>>> print(a)
array([2, 3, 5, 4])

Add items 0 and 1 in first array to second array, and store results in first array:

>>> a = np.array([1, 2, 3, 4])
>>> b = np.array([1, 2])
>>> np.add.at(a, [0, 1], b)
>>> print(a)
array([2, 4, 3, 4])


Routines

  • next
  • previous

Previous topic

numpy.ufunc.at

Next topic

Array creation routines

Routines

In this chapter routine docstrings are presented, grouped by functionality. Many docstrings contain example code, which demonstrates basic usage of the routine. The examples assume that NumPy is imported with:

>>> import numpy as np

A convenient way to execute examples is the %doctest_mode mode of IPython, which allows for pasting of multi-line examples and preserves indentation.

  • Array creation routines
    • Ones and zeros
    • From existing data
    • Creating record arrays (numpy.rec)
    • Creating character arrays (numpy.char)
    • Numerical ranges
    • Building matrices
    • The Matrix class
  • Array manipulation routines
    • Basic operations
    • Changing array shape
    • Transpose-like operations
    • Changing number of dimensions
    • Changing kind of array
    • Joining arrays
    • Splitting arrays
    • Tiling arrays
    • Adding and removing elements
    • Rearranging elements
  • Binary operations
    • Elementwise bit operations
    • Bit packing
    • Output formatting
  • String operations
    • String operations
    • Comparison
    • String information
    • Convenience class
  • C-Types Foreign Function Interface (numpy.ctypeslib)
  • Datetime Support Functions
    • Business Day Functions
  • Data type routines
    • numpy.can_cast
    • numpy.promote_types
    • numpy.min_scalar_type
    • numpy.result_type
    • numpy.common_type
    • numpy.obj2sctype
    • Creating data types
    • Data type information
    • Data type testing
    • Miscellaneous
  • Optionally Scipy-accelerated routines (numpy.dual)
    • Linear algebra
    • FFT
    • Other
  • Mathematical functions with automatic domain (numpy.emath)
  • Floating point error handling
    • Setting and getting error handling
    • Internal functions
  • Discrete Fourier Transform (numpy.fft)
    • Standard FFTs
    • Real FFTs
    • Hermitian FFTs
    • Helper routines
    • Background information
    • Implementation details
    • Real and Hermitian transforms
    • Higher dimensions
    • References
    • Examples
  • Financial functions
    • Simple financial functions
  • Functional programming
    • numpy.apply_along_axis
    • numpy.apply_over_axes
    • numpy.vectorize
    • numpy.frompyfunc
    • numpy.piecewise
  • Numpy-specific help functions
    • Finding help
    • Reading help
  • Indexing routines
    • Generating index arrays
    • Indexing-like operations
    • Inserting data into arrays
    • Iterating over arrays
  • Input and output
    • NPZ files
    • Text files
    • Raw binary files
    • String formatting
    • Memory mapping files
    • Text formatting options
    • Base-n representations
    • Data sources
  • Linear algebra (numpy.linalg)
    • Matrix and vector products
    • Decompositions
    • Matrix eigenvalues
    • Norms and other numbers
    • Solving equations and inverting matrices
    • Exceptions
    • Linear algebra on several matrices at once
  • Logic functions
    • Truth value testing
    • Array contents
    • Array type testing
    • Logical operations
    • Comparison
  • Masked array operations
    • Constants
    • Creation
    • Inspecting the array
    • Manipulating a MaskedArray
    • Operations on masks
    • Conversion operations
    • Masked arrays arithmetics
  • Mathematical functions
    • Trigonometric functions
    • Hyperbolic functions
    • Rounding
    • Sums, products, differences
    • Exponents and logarithms
    • Other special functions
    • Floating point routines
    • Arithmetic operations
    • Handling complex numbers
    • Miscellaneous
  • Matrix library (numpy.matlib)
    • numpy.matlib.empty
    • numpy.matlib.zeros
    • numpy.matlib.ones
    • numpy.matlib.eye
    • numpy.matlib.identity
    • numpy.matlib.repmat
    • numpy.matlib.rand
    • numpy.matlib.randn
  • Miscellaneous routines
    • Buffer objects
    • Performance tuning
  • Padding Arrays
    • numpy.pad
  • Polynomials
    • Transition notice
  • Random sampling (numpy.random)
    • Simple random data
    • Permutations
    • Distributions
    • Random generator
  • Set routines
    • Making proper sets
    • Boolean operations
  • Sorting, searching, and counting
    • Sorting
    • Searching
    • Counting
  • Statistics
    • Order statistics
    • Averages and variances
    • Correlating
    • Histograms
  • Test Support (numpy.testing)
    • Asserts
    • Decorators
    • Test Running
  • Window functions
    • Various windows


Array creation routines

  • next
  • previous

Table Of Contents

  • Array creation routines
    • Ones and zeros
    • From existing data
    • Creating record arrays (numpy.rec)
    • Creating character arrays (numpy.char)
    • Numerical ranges
    • Building matrices
    • The Matrix class

Previous topic

Routines

Next topic

numpy.empty

Array creation routines

See also

Array creation

Ones and zeros

empty(shape[, dtype, order]) | Return a new array of given shape and type, without initializing entries.
empty_like(a[, dtype, order, subok]) | Return a new array with the same shape and type as a given array.
eye(N[, M, k, dtype]) | Return a 2-D array with ones on the diagonal and zeros elsewhere.
identity(n[, dtype]) | Return the identity array.
ones(shape[, dtype, order]) | Return a new array of given shape and type, filled with ones.
ones_like(a[, dtype, order, subok]) | Return an array of ones with the same shape and type as a given array.
zeros(shape[, dtype, order]) | Return a new array of given shape and type, filled with zeros.
zeros_like(a[, dtype, order, subok]) | Return an array of zeros with the same shape and type as a given array.
full(shape, fill_value[, dtype, order]) | Return a new array of given shape and type, filled with fill_value.
full_like(a, fill_value[, dtype, order, subok]) | Return a full array with the same shape and type as a given array.

From existing data

array(object[, dtype, copy, order, subok, ndmin]) | Create an array.
asarray(a[, dtype, order]) | Convert the input to an array.
asanyarray(a[, dtype, order]) | Convert the input to an ndarray, but pass ndarray subclasses through.
ascontiguousarray(a[, dtype]) | Return a contiguous array in memory (C order).
asmatrix(data[, dtype]) | Interpret the input as a matrix.
copy(a[, order]) | Return an array copy of the given object.
frombuffer(buffer[, dtype, count, offset]) | Interpret a buffer as a 1-dimensional array.
fromfile(file[, dtype, count, sep]) | Construct an array from data in a text or binary file.
fromfunction(function, shape, **kwargs) | Construct an array by executing a function over each coordinate.
fromiter(iterable, dtype[, count]) | Create a new 1-dimensional array from an iterable object.
fromstring(string[, dtype, count, sep]) | A new 1-D array initialized from raw binary or text data in a string.
loadtxt(fname[, dtype, comments, delimiter, ...]) | Load data from a text file.

Creating record arrays (numpy.rec)

Note

numpy.rec is the preferred alias for numpy.core.records.

core.records.array(obj[, dtype, shape, ...]) | Construct a record array from a wide-variety of objects.
core.records.fromarrays(arrayList[, dtype, ...]) | create a record array from a (flat) list of arrays
core.records.fromrecords(recList[, dtype, ...]) | create a recarray from a list of records in text form
core.records.fromstring(datastring[, dtype, ...]) | create a (read-only) record array from binary data contained in
core.records.fromfile(fd[, dtype, shape, ...]) | Create an array from binary file data

Creating character arrays (numpy.char)

Note

numpy.char is the preferred alias for numpy.core.defchararray.

core.defchararray.array(obj[, itemsize, ...]) | Create a chararray.
core.defchararray.asarray(obj[, itemsize, ...]) | Convert the input to a chararray, copying the data only if necessary.

Numerical ranges

arange([start,] stop[, step,][, dtype]) | Return evenly spaced values within a given interval.
linspace(start, stop[, num, endpoint, ...]) | Return evenly spaced numbers over a specified interval.
logspace(start, stop[, num, endpoint, base, ...]) | Return numbers spaced evenly on a log scale.
meshgrid(*xi, **kwargs) | Return coordinate matrices from coordinate vectors.
mgrid | nd_grid instance which returns a dense multi-dimensional “meshgrid”.
ogrid | nd_grid instance which returns an open multi-dimensional “meshgrid”.

Building matrices

diag(v[, k]) | Extract a diagonal or construct a diagonal array.
diagflat(v[, k]) | Create a two-dimensional array with the flattened input as a diagonal.
tri(N[, M, k, dtype]) | An array with ones at and below the given diagonal and zeros elsewhere.
tril(m[, k]) | Lower triangle of an array.
triu(m[, k]) | Upper triangle of an array.
vander(x[, N, increasing]) | Generate a Vandermonde matrix.

The Matrix class

mat(data[, dtype]) | Interpret the input as a matrix.
bmat(obj[, ldict, gdict]) | Build a matrix object from a string, nested sequence, or array.


numpy.empty

  • Array creation routines
  • next
  • previous

Previous topic

numpy.bmat

Next topic

numpy.empty_like

numpy.empty

numpy.empty(shape, dtype=float, order='C')

Return a new array of given shape and type, without initializing entries.

Parameters:

shape : int or tuple of int

Shape of the empty array

dtype : data-type, optional

Desired output data-type.

order : {‘C’, ‘F’}, optional

Whether to store multi-dimensional data in C (row-major) or Fortran (column-major) order in memory.
Returns:

out : ndarray

Array of uninitialized (arbitrary) data with the given shape, dtype, and order.

See also

empty_like, zeros, ones

Notes

empty, unlike zeros, does not set the array values to zero, and may therefore be marginally faster. On the other hand, it requires the user to manually set all the values in the array, and should be used with caution.

Examples

>>> np.empty([2, 2])
array([[ -9.74499359e+001,   6.69583040e-309],
       [  2.13182611e-314,   3.06959433e-309]])         #random

>>> np.empty([2, 2], dtype=int)
array([[-1073741821, -1067949133],
       [  496041986,    19249760]])                     #random


numpy.empty_like

  • Array creation routines
  • next
  • previous

Previous topic

numpy.empty

Next topic

numpy.eye

numpy.empty_like

numpy.empty_like(a, dtype=None, order='K', subok=True)

Return a new array with the same shape and type as a given array.

Parameters:

a : array_like

The shape and data-type of a define these same attributes of the returned array.

dtype : data-type, optional

New in version 1.6.0.

Overrides the data type of the result.

order : {‘C’, ‘F’, ‘A’, or ‘K’}, optional

New in version 1.6.0.

Overrides the memory layout of the result. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible.

subok : bool, optional.

If True, then the newly created array will use the sub-class type of ‘a’, otherwise it will be a base-class array. Defaults to True.
Returns:

out : ndarray

Array of uninitialized (arbitrary) data with the same shape and type as a.

See also

ones_like
Return an array of ones with shape and type of input.
zeros_like
Return an array of zeros with shape and type of input.
empty
Return a new uninitialized array.
ones
Return a new array setting values to one.
zeros
Return a new array setting values to zero.

Notes

This function does not initialize the returned array; to do that use zeros_like or ones_like instead. It may be marginally faster than the functions that do set the array values.

Examples

>>> a = ([1,2,3], [4,5,6])                         # a is array-like
>>> np.empty_like(a)
array([[-1073741821, -1073741821,           3],    #random
       [          0,           0, -1073741821]])
>>> a = np.array([[1., 2., 3.],[4.,5.,6.]])
>>> np.empty_like(a)
array([[ -2.00000715e+000,   1.48219694e-323,  -2.00000572e+000],#random
       [  4.38791518e-305,  -2.00000715e+000,   4.17269252e-309]])


numpy.eye

  • Array creation routines
  • next
  • previous

Previous topic

numpy.empty_like

Next topic

numpy.identity

numpy.eye

numpy.eye(N, M=None, k=0, dtype=<type 'float'>) [source]

Return a 2-D array with ones on the diagonal and zeros elsewhere.

Parameters:

N : int

Number of rows in the output.

M : int, optional

Number of columns in the output. If None, defaults to N.

k : int, optional

Index of the diagonal: 0 (the default) refers to the main diagonal, a positive value refers to an upper diagonal, and a negative value to a lower diagonal.

dtype : data-type, optional

Data-type of the returned array.
Returns:

I : ndarray of shape (N,M)

An array where all elements are equal to zero, except for the k-th diagonal, whose values are equal to one.

See also

identity
(almost) equivalent function
diag
diagonal 2-D array from a 1-D array specified by the user.

Examples

>>> np.eye(2, dtype=int)
array([[1, 0],
       [0, 1]])
>>> np.eye(3, k=1)
array([[ 0.,  1.,  0.],
       [ 0.,  0.,  1.],
       [ 0.,  0.,  0.]])


numpy.identity

  • Array creation routines
  • next
  • previous

Previous topic

numpy.eye

Next topic

numpy.ones

numpy.identity

numpy.identity(n, dtype=None) [source]

Return the identity array.

The identity array is a square array with ones on the main diagonal.

Parameters:

n : int

Number of rows (and columns) in n x n output.

dtype : data-type, optional

Data-type of the output. Defaults to float.
Returns:

out : ndarray

n x n array with its main diagonal set to one, and all other elements 0.

Examples

>>> np.identity(3)
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])


numpy.ones

  • Array creation routines
  • next
  • previous

Previous topic

numpy.identity

Next topic

numpy.ones_like

numpy.ones

numpy.ones(shape, dtype=None, order='C') [source]

Return a new array of given shape and type, filled with ones.

Parameters:

shape : int or sequence of ints

Shape of the new array, e.g., (2, 3) or 2.

dtype : data-type, optional

The desired data-type for the array, e.g., numpy.int8. Default is numpy.float64.

order : {‘C’, ‘F’}, optional

Whether to store multidimensional data in C- or Fortran-contiguous (row- or column-wise) order in memory.
Returns:

out : ndarray

Array of ones with the given shape, dtype, and order.

See also

zeros, ones_like

Examples

>>> np.ones(5)
array([ 1.,  1.,  1.,  1.,  1.])

>>> np.ones((5,), dtype=np.int)
array([1, 1, 1, 1, 1])

>>> np.ones((2, 1))
array([[ 1.],
       [ 1.]])

>>> s = (2,2)
>>> np.ones(s)
array([[ 1.,  1.],
       [ 1.,  1.]])


numpy.ones_like

  • Array creation routines
  • next
  • previous

Previous topic

numpy.ones

Next topic

numpy.zeros

numpy.ones_like

numpy.ones_like(a, dtype=None, order='K', subok=True) [source]

Return an array of ones with the same shape and type as a given array.

Parameters:

a : array_like

The shape and data-type of a define these same attributes of the returned array.

dtype : data-type, optional

New in version 1.6.0.

Overrides the data type of the result.

order : {‘C’, ‘F’, ‘A’, or ‘K’}, optional

New in version 1.6.0.

Overrides the memory layout of the result. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible.

subok : bool, optional.

If True, then the newly created array will use the sub-class type of ‘a’, otherwise it will be a base-class array. Defaults to True.
Returns:

out : ndarray

Array of ones with the same shape and type as a.

See also

zeros_like
Return an array of zeros with shape and type of input.
empty_like
Return an empty array with shape and type of input.
zeros
Return a new array setting values to zero.
ones
Return a new array setting values to one.
empty
Return a new uninitialized array.

Examples

>>> x = np.arange(6)
>>> x = x.reshape((2, 3))
>>> x
array([[0, 1, 2],
       [3, 4, 5]])
>>> np.ones_like(x)
array([[1, 1, 1],
       [1, 1, 1]])

>>> y = np.arange(3, dtype=np.float)
>>> y
array([ 0.,  1.,  2.])
>>> np.ones_like(y)
array([ 1.,  1.,  1.])


numpy.zeros

  • Array creation routines
  • next
  • previous

Previous topic

numpy.ones_like

Next topic

numpy.zeros_like

numpy.zeros

numpy.zeros(shape, dtype=float, order='C')

Return a new array of given shape and type, filled with zeros.

Parameters:

shape : int or sequence of ints

Shape of the new array, e.g., (2, 3) or 2.

dtype : data-type, optional

The desired data-type for the array, e.g., numpy.int8. Default is numpy.float64.

order : {‘C’, ‘F’}, optional

Whether to store multidimensional data in C- or Fortran-contiguous (row- or column-wise) order in memory.
Returns:

out : ndarray

Array of zeros with the given shape, dtype, and order.

See also

zeros_like
Return an array of zeros with shape and type of input.
ones_like
Return an array of ones with shape and type of input.
empty_like
Return an empty array with shape and type of input.
ones
Return a new array setting values to one.
empty
Return a new uninitialized array.

Examples

>>> np.zeros(5)
array([ 0.,  0.,  0.,  0.,  0.])

>>> np.zeros((5,), dtype=numpy.int)
array([0, 0, 0, 0, 0])

>>> np.zeros((2, 1))
array([[ 0.],
       [ 0.]])

>>> s = (2,2)
>>> np.zeros(s)
array([[ 0.,  0.],
       [ 0.,  0.]])

>>> np.zeros((2,), dtype=[('x', 'i4'), ('y', 'i4')]) # custom dtype
array([(0, 0), (0, 0)],
      dtype=[('x', '<i4'), ('y', '<i4')])


numpy.zeros_like

  • Array creation routines
  • next
  • previous

Previous topic

numpy.zeros

Next topic

numpy.full

numpy.zeros_like

numpy.zeros_like(a, dtype=None, order='K', subok=True) [source]

Return an array of zeros with the same shape and type as a given array.

Parameters:

a : array_like

The shape and data-type of a define these same attributes of the returned array.

dtype : data-type, optional

New in version 1.6.0.

Overrides the data type of the result.

order : {‘C’, ‘F’, ‘A’, or ‘K’}, optional

New in version 1.6.0.

Overrides the memory layout of the result. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible.

subok : bool, optional.

If True, then the newly created array will use the sub-class type of ‘a’, otherwise it will be a base-class array. Defaults to True.
Returns:

out : ndarray

Array of zeros with the same shape and type as a.

See also

ones_like
Return an array of ones with shape and type of input.
empty_like
Return an empty array with shape and type of input.
zeros
Return a new array setting values to zero.
ones
Return a new array setting values to one.
empty
Return a new uninitialized array.

Examples

>>> x = np.arange(6)
>>> x = x.reshape((2, 3))
>>> x
array([[0, 1, 2],
       [3, 4, 5]])
>>> np.zeros_like(x)
array([[0, 0, 0],
       [0, 0, 0]])

>>> y = np.arange(3, dtype=np.float)
>>> y
array([ 0.,  1.,  2.])
>>> np.zeros_like(y)
array([ 0.,  0.,  0.])


numpy.full

  • Array creation routines
  • next
  • previous

Previous topic

numpy.zeros_like

Next topic

numpy.full_like

numpy.full

numpy.full(shape, fill_value, dtype=None, order='C') [source]

Return a new array of given shape and type, filled with fill_value.

Parameters:

shape : int or sequence of ints

Shape of the new array, e.g., (2, 3) or 2.

fill_value : scalar

Fill value.

dtype : data-type, optional

The desired data-type for the array, e.g., numpy.int8. Default is is chosen as np.array(fill_value).dtype.

order : {‘C’, ‘F’}, optional

Whether to store multidimensional data in C- or Fortran-contiguous (row- or column-wise) order in memory.
Returns:

out : ndarray

Array of fill_value with the given shape, dtype, and order.

See also

zeros_like
Return an array of zeros with shape and type of input.
ones_like
Return an array of ones with shape and type of input.
empty_like
Return an empty array with shape and type of input.
full_like
Fill an array with shape and type of input.
zeros
Return a new array setting values to zero.
ones
Return a new array setting values to one.
empty
Return a new uninitialized array.

Examples

>>> np.full((2, 2), np.inf)
array([[ inf,  inf],
       [ inf,  inf]])
>>> np.full((2, 2), 10, dtype=np.int)
array([[10, 10],
       [10, 10]])


numpy.full_like

  • Array creation routines
  • next
  • previous

Previous topic

numpy.full

Next topic

numpy.array

numpy.full_like

numpy.full_like(a, fill_value, dtype=None, order='K', subok=True) [source]

Return a full array with the same shape and type as a given array.

Parameters:

a : array_like

The shape and data-type of a define these same attributes of the returned array.

fill_value : scalar

Fill value.

dtype : data-type, optional

Overrides the data type of the result.

order : {‘C’, ‘F’, ‘A’, or ‘K’}, optional

Overrides the memory layout of the result. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible.

subok : bool, optional.

If True, then the newly created array will use the sub-class type of ‘a’, otherwise it will be a base-class array. Defaults to True.
Returns:

out : ndarray

Array of fill_value with the same shape and type as a.

See also

zeros_like
Return an array of zeros with shape and type of input.
ones_like
Return an array of ones with shape and type of input.
empty_like
Return an empty array with shape and type of input.
zeros
Return a new array setting values to zero.
ones
Return a new array setting values to one.
empty
Return a new uninitialized array.
full
Fill a new array.

Examples

>>> x = np.arange(6, dtype=np.int)
>>> np.full_like(x, 1)
array([1, 1, 1, 1, 1, 1])
>>> np.full_like(x, 0.1)
array([0, 0, 0, 0, 0, 0])
>>> np.full_like(x, 0.1, dtype=np.double)
array([ 0.1,  0.1,  0.1,  0.1,  0.1,  0.1])
>>> np.full_like(x, np.nan, dtype=np.double)
array([ nan,  nan,  nan,  nan,  nan,  nan])

>>> y = np.arange(6, dtype=np.double)
>>> np.full_like(y, 0.1)
array([ 0.1,  0.1,  0.1,  0.1,  0.1,  0.1])


numpy.array

  • Array creation routines
  • next
  • previous

Previous topic

numpy.full_like

Next topic

numpy.asarray

numpy.array

numpy.array(object, dtype=None, copy=True, order=None, subok=False, ndmin=0)

Create an array.

Parameters:

object : array_like

An array, any object exposing the array interface, an object whose __array__ method returns an array, or any (nested) sequence.

dtype : data-type, optional

The desired data-type for the array. If not given, then the type will be determined as the minimum type required to hold the objects in the sequence. This argument can only be used to ‘upcast’ the array. For downcasting, use the .astype(t) method.

copy : bool, optional

If true (default), then the object is copied. Otherwise, a copy will only be made if __array__ returns a copy, if obj is a nested sequence, or if a copy is needed to satisfy any of the other requirements (dtype, order, etc.).

order : {‘C’, ‘F’, ‘A’}, optional

Specify the order of the array. If order is ‘C’ (default), then the array will be in C-contiguous order (last-index varies the fastest). If order is ‘F’, then the returned array will be in Fortran-contiguous order (first-index varies the fastest). If order is ‘A’, then the returned array may be in any order (either C-, Fortran-contiguous, or even discontiguous).

subok : bool, optional

If True, then sub-classes will be passed-through, otherwise the returned array will be forced to be a base-class array (default).

ndmin : int, optional

Specifies the minimum number of dimensions that the resulting array should have. Ones will be pre-pended to the shape as needed to meet this requirement.
Returns:

out : ndarray

An array object satisfying the specified requirements.

See also

empty, empty_like, zeros, zeros_like, ones, ones_like, fill

Examples

>>> np.array([1, 2, 3])
array([1, 2, 3])

Upcasting:

>>> np.array([1, 2, 3.0])
array([ 1.,  2.,  3.])

More than one dimension:

>>> np.array([[1, 2], [3, 4]])
array([[1, 2],
       [3, 4]])

Minimum dimensions 2:

>>> np.array([1, 2, 3], ndmin=2)
array([[1, 2, 3]])

Type provided:

>>> np.array([1, 2, 3], dtype=complex)
array([ 1.+0.j,  2.+0.j,  3.+0.j])

Data-type consisting of more than one element:

>>> x = np.array([(1,2),(3,4)],dtype=[('a','<i4'),('b','<i4')])
>>> x['a']
array([1, 3])

Creating an array from sub-classes:

>>> np.array(np.mat('1 2; 3 4'))
array([[1, 2],
       [3, 4]])

>>> np.array(np.mat('1 2; 3 4'), subok=True)
matrix([[1, 2],
        [3, 4]])


numpy.asarray

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.squeeze

Next topic

numpy.asanyarray

numpy.asarray

numpy.asarray(a, dtype=None, order=None) [source]

Convert the input to an array.

Parameters:

a : array_like

Input data, in any form that can be converted to an array. This includes lists, lists of tuples, tuples, tuples of tuples, tuples of lists and ndarrays.

dtype : data-type, optional

By default, the data-type is inferred from the input data.

order : {‘C’, ‘F’}, optional

Whether to use row-major (‘C’) or column-major (‘F’ for FORTRAN) memory representation. Defaults to ‘C’.
Returns:

out : ndarray

Array interpretation of a. No copy is performed if the input is already an ndarray. If a is a subclass of ndarray, a base class ndarray is returned.

See also

asanyarray
Similar function which passes through subclasses.
ascontiguousarray
Convert input to a contiguous array.
asfarray
Convert input to a floating point ndarray.
asfortranarray
Convert input to an ndarray with column-major memory order.
asarray_chkfinite
Similar function which checks input for NaNs and Infs.
fromiter
Create an array from an iterator.
fromfunction
Construct an array by executing a function on grid positions.

Examples

Convert a list into an array:

>>> a = [1, 2]
>>> np.asarray(a)
array([1, 2])

Existing arrays are not copied:

>>> a = np.array([1, 2])
>>> np.asarray(a) is a
True

If dtype is set, array is copied only if dtype does not match:

>>> a = np.array([1, 2], dtype=np.float32)
>>> np.asarray(a, dtype=np.float32) is a
True
>>> np.asarray(a, dtype=np.float64) is a
False

Contrary to asanyarray, ndarray subclasses are not passed through:

>>> issubclass(np.matrix, np.ndarray)
True
>>> a = np.matrix([[1, 2]])
>>> np.asarray(a) is a
False
>>> np.asanyarray(a) is a
True


numpy.asanyarray

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.asarray

Next topic

numpy.asmatrix

numpy.asanyarray

numpy.asanyarray(a, dtype=None, order=None) [source]

Convert the input to an ndarray, but pass ndarray subclasses through.

Parameters:

a : array_like

Input data, in any form that can be converted to an array. This includes scalars, lists, lists of tuples, tuples, tuples of tuples, tuples of lists, and ndarrays.

dtype : data-type, optional

By default, the data-type is inferred from the input data.

order : {‘C’, ‘F’}, optional

Whether to use row-major (‘C’) or column-major (‘F’) memory representation. Defaults to ‘C’.
Returns:

out : ndarray or an ndarray subclass

Array interpretation of a. If a is an ndarray or a subclass of ndarray, it is returned as-is and no copy is performed.

See also

asarray
Similar function which always returns ndarrays.
ascontiguousarray
Convert input to a contiguous array.
asfarray
Convert input to a floating point ndarray.
asfortranarray
Convert input to an ndarray with column-major memory order.
asarray_chkfinite
Similar function which checks input for NaNs and Infs.
fromiter
Create an array from an iterator.
fromfunction
Construct an array by executing a function on grid positions.

Examples

Convert a list into an array:

>>> a = [1, 2]
>>> np.asanyarray(a)
array([1, 2])

Instances of ndarray subclasses are passed through as-is:

>>> a = np.matrix([1, 2])
>>> np.asanyarray(a) is a
True


numpy.ascontiguousarray

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.asfortranarray

Next topic

numpy.asarray_chkfinite

numpy.ascontiguousarray

numpy.ascontiguousarray(a, dtype=None) [source]

Return a contiguous array in memory (C order).

Parameters:

a : array_like

Input array.

dtype : str or dtype object, optional

Data-type of returned array.
Returns:

out : ndarray

Contiguous array of same shape and content as a, with type dtype if specified.

See also

asfortranarray
Convert input to an ndarray with column-major memory order.
require
Return an ndarray that satisfies requirements.
ndarray.flags
Information about the memory layout of the array.

Examples

>>> x = np.arange(6).reshape(2,3)
>>> np.ascontiguousarray(x, dtype=np.float32)
array([[ 0.,  1.,  2.],
       [ 3.,  4.,  5.]], dtype=float32)
>>> x.flags['C_CONTIGUOUS']
True


numpy.copy

  • Array creation routines
  • next
  • previous

Previous topic

numpy.asmatrix

Next topic

numpy.frombuffer

numpy.copy

numpy.copy(a, order='K') [source]

Return an array copy of the given object.

Parameters:

a : array_like

Input data.

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout of the copy. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible. (Note that this function and :meth:ndarray.copy are very similar, but have different default values for their order= arguments.)
Returns:

arr : ndarray

Array interpretation of a.

Notes

This is equivalent to

>>> np.array(a, copy=True)

Examples

Create an array x, with a reference y and a copy z:

>>> x = np.array([1, 2, 3])
>>> y = x
>>> z = np.copy(x)

Note that, when we modify x, y changes, but not z:

>>> x[0] = 10
>>> x[0] == y[0]
True
>>> x[0] == z[0]
False


numpy.frombuffer

  • Array creation routines
  • next
  • previous

Previous topic

numpy.copy

Next topic

numpy.fromfile

numpy.frombuffer

numpy.frombuffer(buffer, dtype=float, count=-1, offset=0)

Interpret a buffer as a 1-dimensional array.

Parameters:

buffer : buffer_like

An object that exposes the buffer interface.

dtype : data-type, optional

Data-type of the returned array; default: float.

count : int, optional

Number of items to read. -1 means all data in the buffer.

offset : int, optional

Start reading the buffer from this offset; default: 0.

Notes

If the buffer has data that is not in machine byte-order, this should be specified as part of the data-type, e.g.:

>>> dt = np.dtype(int)
>>> dt = dt.newbyteorder('>')
>>> np.frombuffer(buf, dtype=dt)

The data of the resulting array will not be byteswapped, but will be interpreted correctly.

Examples

>>> s = 'hello world'
>>> np.frombuffer(s, dtype='S1', count=5, offset=6)
array(['w', 'o', 'r', 'l', 'd'],
      dtype='|S1')


numpy.fromfile

  • Array creation routines
  • next
  • previous

Previous topic

numpy.frombuffer

Next topic

numpy.fromfunction

numpy.fromfile

numpy.fromfile(file, dtype=float, count=-1, sep='')

Construct an array from data in a text or binary file.

A highly efficient way of reading binary data with a known data-type, as well as parsing simply formatted text files. Data written using the tofile method can be read using this function.

Parameters:

file : file or str

Open file object or filename.

dtype : data-type

Data type of the returned array. For binary files, it is used to determine the size and byte-order of the items in the file.

count : int

Number of items to read. -1 means all items (i.e., the complete file).

sep : str

Separator between items if file is a text file. Empty (“”) separator means the file should be treated as binary. Spaces (” ”) in the separator match zero or more whitespace characters. A separator consisting only of spaces must match at least one whitespace.

See also

load, save, ndarray.tofile

loadtxt
More flexible way of loading data from a text file.

Notes

Do not rely on the combination of tofile and fromfile for data storage, as the binary files generated are are not platform independent. In particular, no byte-order or data-type information is saved. Data can be stored in the platform independent .npy format using save and load instead.

Examples

Construct an ndarray:

>>> dt = np.dtype([('time', [('min', int), ('sec', int)]),
...                ('temp', float)])
>>> x = np.zeros((1,), dtype=dt)
>>> x['time']['min'] = 10; x['temp'] = 98.25
>>> x
array([((10, 0), 98.25)],
      dtype=[('time', [('min', '<i4'), ('sec', '<i4')]), ('temp', '<f8')])

Save the raw data to disk:

>>> import os
>>> fname = os.tmpnam()
>>> x.tofile(fname)

Read the raw data from disk:

>>> np.fromfile(fname, dtype=dt)
array([((10, 0), 98.25)],
      dtype=[('time', [('min', '<i4'), ('sec', '<i4')]), ('temp', '<f8')])

The recommended way to store and load data:

>>> np.save(fname, x)
>>> np.load(fname + '.npy')
array([((10, 0), 98.25)],
      dtype=[('time', [('min', '<i4'), ('sec', '<i4')]), ('temp', '<f8')])


numpy.fromfunction

  • Array creation routines
  • next
  • previous

Previous topic

numpy.fromfile

Next topic

numpy.fromiter

numpy.fromfunction

numpy.fromfunction(function, shape, **kwargs) [source]

Construct an array by executing a function over each coordinate.

The resulting array therefore has a value fn(x, y, z) at coordinate (x, y, z).

Parameters:

function : callable

The function is called with N parameters, where N is the rank of shape. Each parameter represents the coordinates of the array varying along a specific axis. For example, if shape were (2, 2), then the parameters in turn be (0, 0), (0, 1), (1, 0), (1, 1).

shape : (N,) tuple of ints

Shape of the output array, which also determines the shape of the coordinate arrays passed to function.

dtype : data-type, optional

Data-type of the coordinate arrays passed to function. By default, dtype is float.
Returns:

fromfunction : any

The result of the call to function is passed back directly. Therefore the shape of fromfunction is completely determined by function. If function returns a scalar value, the shape of fromfunction would match the shape parameter.

See also

indices, meshgrid

Notes

Keywords other than dtype are passed to function.

Examples

>>> np.fromfunction(lambda i, j: i == j, (3, 3), dtype=int)
array([[ True, False, False],
       [False,  True, False],
       [False, False,  True]], dtype=bool)

>>> np.fromfunction(lambda i, j: i + j, (3, 3), dtype=int)
array([[0, 1, 2],
       [1, 2, 3],
       [2, 3, 4]])


numpy.fromiter

  • Array creation routines
  • next
  • previous

Previous topic

numpy.fromfunction

Next topic

numpy.fromstring

numpy.fromiter

numpy.fromiter(iterable, dtype, count=-1)

Create a new 1-dimensional array from an iterable object.

Parameters:

iterable : iterable object

An iterable object providing data for the array.

dtype : data-type

The data-type of the returned array.

count : int, optional

The number of items to read from iterable. The default is -1, which means all data is read.
Returns:

out : ndarray

The output array.

Notes

Specify count to improve performance. It allows fromiter to pre-allocate the output array, instead of resizing it on demand.

Examples

>>> iterable = (x*x for x in range(5))
>>> np.fromiter(iterable, np.float)
array([  0.,   1.,   4.,   9.,  16.])


numpy.fromstring

  • Input and output
  • next
  • previous

Previous topic

numpy.fromregex

Next topic

numpy.ndarray.tofile

numpy.fromstring

numpy.fromstring(string, dtype=float, count=-1, sep='')

A new 1-D array initialized from raw binary or text data in a string.

Parameters:

string : str

A string containing the data.

dtype : data-type, optional

The data type of the array; default: float. For binary input data, the data must be in exactly this format.

count : int, optional

Read this number of dtype elements from the data. If this is negative (the default), the count will be determined from the length of the data.

sep : str, optional

If not provided or, equivalently, the empty string, the data will be interpreted as binary data; otherwise, as ASCII text with decimal numbers. Also in this latter case, this argument is interpreted as the string separating numbers in the data; extra whitespace between elements is also ignored.
Returns:

arr : ndarray

The constructed array.
Raises:

ValueError

If the string is not the correct size to satisfy the requested dtype and count.

See also

frombuffer, fromfile, fromiter

Examples

>>> np.fromstring('\x01\x02', dtype=np.uint8)
array([1, 2], dtype=uint8)
>>> np.fromstring('1 2', dtype=int, sep=' ')
array([1, 2])
>>> np.fromstring('1, 2', dtype=int, sep=',')
array([1, 2])
>>> np.fromstring('\x01\x02\x03\x04\x05', dtype=np.uint8, count=3)
array([1, 2, 3], dtype=uint8)


numpy.loadtxt

  • Input and output
  • next
  • previous

Previous topic

numpy.savez_compressed

Next topic

numpy.savetxt

numpy.loadtxt

numpy.loadtxt(fname, dtype=<type 'float'>, comments='#', delimiter=None, converters=None, skiprows=0, usecols=None, unpack=False, ndmin=0) [source]

Load data from a text file.

Each row in the text file must have the same number of values.

Parameters:

fname : file or str

File, filename, or generator to read. If the filename extension is .gz or .bz2, the file is first decompressed. Note that generators should return byte strings for Python 3k.

dtype : data-type, optional

Data-type of the resulting array; default: float. If this is a record data-type, the resulting array will be 1-dimensional, and each row will be interpreted as an element of the array. In this case, the number of columns used must match the number of fields in the data-type.

comments : str, optional

The character used to indicate the start of a comment; default: ‘#’.

delimiter : str, optional

The string used to separate values. By default, this is any whitespace.

converters : dict, optional

A dictionary mapping column number to a function that will convert that column to a float. E.g., if column 0 is a date string: converters = {0: datestr2num}. Converters can also be used to provide a default value for missing data (but see also genfromtxt): converters = {3: lambda s: float(s.strip() or 0)}. Default: None.

skiprows : int, optional

Skip the first skiprows lines; default: 0.

usecols : sequence, optional

Which columns to read, with 0 being the first. For example, usecols = (1,4,5) will extract the 2nd, 5th and 6th columns. The default, None, results in all columns being read.

unpack : bool, optional

If True, the returned array is transposed, so that arguments may be unpacked using x, y, z = loadtxt(...). When used with a record data-type, arrays are returned for each field. Default is False.

ndmin : int, optional

The returned array will have at least ndmin dimensions. Otherwise mono-dimensional axes will be squeezed. Legal values: 0 (default), 1 or 2.

New in version 1.6.0.
Returns:

out : ndarray

Data read from the text file.

See also

load, fromstring, fromregex

genfromtxt
Load data with missing values handled as specified.
scipy.io.loadmat
reads MATLAB data files

Notes

This function aims to be a fast reader for simply formatted files. The genfromtxt function provides more sophisticated handling of, e.g., lines with missing values.

Examples

>>> from StringIO import StringIO   # StringIO behaves like a file object
>>> c = StringIO("0 1\n2 3")
>>> np.loadtxt(c)
array([[ 0.,  1.],
       [ 2.,  3.]])

>>> d = StringIO("M 21 72\nF 35 58")
>>> np.loadtxt(d, dtype={'names': ('gender', 'age', 'weight'),
...                      'formats': ('S1', 'i4', 'f4')})
array([('M', 21, 72.0), ('F', 35, 58.0)],
      dtype=[('gender', '|S1'), ('age', '<i4'), ('weight', '<f4')])

>>> c = StringIO("1,0,2\n3,0,4")
>>> x, y = np.loadtxt(c, delimiter=',', usecols=(0, 2), unpack=True)
>>> x
array([ 1.,  3.])
>>> y
array([ 2.,  4.])


numpy.core.records.array

  • Array creation routines
  • next
  • previous

Previous topic

numpy.loadtxt

Next topic

numpy.core.records.fromarrays

numpy.core.records.array

numpy.core.records.array(obj, dtype=None, shape=None, offset=0, strides=None, formats=None, names=None, titles=None, aligned=False, byteorder=None, copy=True) [source]

Construct a record array from a wide-variety of objects.


numpy.core.records.fromarrays

  • Array creation routines
  • next
  • previous

Previous topic

numpy.core.records.array

Next topic

numpy.core.records.fromrecords

numpy.core.records.fromarrays

numpy.core.records.fromarrays(arrayList, dtype=None, shape=None, formats=None, names=None, titles=None, aligned=False, byteorder=None) [source]

create a record array from a (flat) list of arrays

>>> x1=np.array([1,2,3,4])
>>> x2=np.array(['a','dd','xyz','12'])
>>> x3=np.array([1.1,2,3,4])
>>> r = np.core.records.fromarrays([x1,x2,x3],names='a,b,c')
>>> print r[1]
(2, 'dd', 2.0)
>>> x1[1]=34
>>> r.a
array([1, 2, 3, 4])


numpy.core.records.fromrecords

  • Array creation routines
  • next
  • previous

Previous topic

numpy.core.records.fromarrays

Next topic

numpy.core.records.fromstring

numpy.core.records.fromrecords

numpy.core.records.fromrecords(recList, dtype=None, shape=None, formats=None, names=None, titles=None, aligned=False, byteorder=None) [source]

create a recarray from a list of records in text form

The data in the same field can be heterogeneous, they will be promoted to the highest data type. This method is intended for creating smaller record arrays. If used to create large array without formats defined

r=fromrecords([(2,3.,’abc’)]*100000)

it can be slow.

If formats is None, then this will auto-detect formats. Use list of tuples rather than list of lists for faster processing.

>>> r=np.core.records.fromrecords([(456,'dbe',1.2),(2,'de',1.3)],
... names='col1,col2,col3')
>>> print r[0]
(456, 'dbe', 1.2)
>>> r.col1
array([456,   2])
>>> r.col2
chararray(['dbe', 'de'],
      dtype='|S3')
>>> import pickle
>>> print pickle.loads(pickle.dumps(r))
[(456, 'dbe', 1.2) (2, 'de', 1.3)]


numpy.core.records.fromstring

  • Array creation routines
  • next
  • previous

Previous topic

numpy.core.records.fromrecords

Next topic

numpy.core.records.fromfile

numpy.core.records.fromstring

numpy.core.records.fromstring(datastring, dtype=None, shape=None, offset=0, formats=None, names=None, titles=None, aligned=False, byteorder=None) [source]

create a (read-only) record array from binary data contained in a string


numpy.core.records.fromfile

  • Array creation routines
  • next
  • previous

Previous topic

numpy.core.records.fromstring

Next topic

numpy.core.defchararray.array

numpy.core.records.fromfile

numpy.core.records.fromfile(fd, dtype=None, shape=None, offset=0, formats=None, names=None, titles=None, aligned=False, byteorder=None) [source]

Create an array from binary file data

If file is a string then that file is opened, else it is assumed to be a file object.

>>> from tempfile import TemporaryFile
>>> a = np.empty(10,dtype='f8,i4,a5')
>>> a[5] = (0.5,10,'abcde')
>>>
>>> fd=TemporaryFile()
>>> a = a.newbyteorder('<')
>>> a.tofile(fd)
>>>
>>> fd.seek(0)
>>> r=np.core.records.fromfile(fd, formats='f8,i4,a5', shape=10,
... byteorder='<')
>>> print r[5]
(0.5, 10, 'abcde')
>>> r.shape
(10,)


numpy.core.defchararray.asarray

  • Array creation routines
  • next
  • previous

Previous topic

numpy.core.defchararray.array

Next topic

numpy.arange

numpy.core.defchararray.asarray

numpy.core.defchararray.asarray(obj, itemsize=None, unicode=None, order=None) [source]

Convert the input to a chararray, copying the data only if necessary.

Versus a regular Numpy array of type str or unicode, this class adds the following functionality:

  1. values automatically have whitespace removed from the end when indexed
  2. comparison operators automatically remove whitespace from the end when comparing values
  3. vectorized string operations are provided as methods (e.g. str.endswith) and infix operators (e.g. +, *, %)
Parameters:

obj : array of str or unicode-like

itemsize : int, optional

itemsize is the number of characters per scalar in the resulting array. If itemsize is None, and obj is an object array or a Python list, the itemsize will be automatically determined. If itemsize is provided and obj is of type str or unicode, then the obj string will be chunked into itemsize pieces.

unicode : bool, optional

When true, the resulting chararray can contain Unicode characters, when false only 8-bit characters. If unicode is None and obj is one of the following:

  • a chararray,
  • an ndarray of type str or ‘unicode`
  • a Python str or unicode object,

then the unicode setting of the output array will be automatically determined.

order : {‘C’, ‘F’}, optional

Specify the order of the array. If order is ‘C’ (default), then the array will be in C-contiguous order (last-index varies the fastest). If order is ‘F’, then the returned array will be in Fortran-contiguous order (first-index varies the fastest).


numpy.arange

  • Array creation routines
  • next
  • previous

Previous topic

numpy.core.defchararray.asarray

Next topic

numpy.linspace

numpy.arange

numpy.arange([start, ]stop, [step, ]dtype=None)

Return evenly spaced values within a given interval.

Values are generated within the half-open interval [start, stop) (in other words, the interval including start but excluding stop). For integer arguments the function is equivalent to the Python built-in range function, but returns an ndarray rather than a list.

When using a non-integer step, such as 0.1, the results will often not be consistent. It is better to use linspace for these cases.

Parameters:

start : number, optional

Start of interval. The interval includes this value. The default start value is 0.

stop : number

End of interval. The interval does not include this value, except in some cases where step is not an integer and floating point round-off affects the length of out.

step : number, optional

Spacing between values. For any output out, this is the distance between two adjacent values, out[i+1] - out[i]. The default step size is 1. If step is specified, start must also be given.

dtype : dtype

The type of the output array. If dtype is not given, infer the data type from the other input arguments.
Returns:

arange : ndarray

Array of evenly spaced values.

For floating point arguments, the length of the result is ceil((stop - start)/step). Because of floating point overflow, this rule may result in the last element of out being greater than stop.

See also

linspace
Evenly spaced numbers with careful handling of endpoints.
ogrid
Arrays of evenly spaced numbers in N-dimensions.
mgrid
Grid-shaped arrays of evenly spaced numbers in N-dimensions.

Examples

>>> np.arange(3)
array([0, 1, 2])
>>> np.arange(3.0)
array([ 0.,  1.,  2.])
>>> np.arange(3,7)
array([3, 4, 5, 6])
>>> np.arange(3,7,2)
array([3, 5])


numpy.linspace

  • Array creation routines
  • next
  • previous

Previous topic

numpy.arange

Next topic

numpy.logspace

numpy.linspace

numpy.linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None) [source]

Return evenly spaced numbers over a specified interval.

Returns num evenly spaced samples, calculated over the interval [start, stop ].

The endpoint of the interval can optionally be excluded.

Parameters:

start : scalar

The starting value of the sequence.

stop : scalar

The end value of the sequence, unless endpoint is set to False. In that case, the sequence consists of all but the last of num + 1 evenly spaced samples, so that stop is excluded. Note that the step size changes when endpoint is False.

num : int, optional

Number of samples to generate. Default is 50.

endpoint : bool, optional

If True, stop is the last sample. Otherwise, it is not included. Default is True.

retstep : bool, optional

If True, return (samples, step), where step is the spacing between samples.

dtype : dtype

The type of the output array. If dtype is not given, infer the data type from the other input arguments.

New in version 1.9.0.
Returns:

samples : ndarray

There are num equally spaced samples in the closed interval [start, stop] or the half-open interval [start, stop) (depending on whether endpoint is True or False).

step : float (only if retstep is True)

Size of spacing between samples.

See also

arange
Similar to linspace, but uses a step size (instead of the number of samples).
logspace
Samples uniformly distributed in log space.

Examples

>>> np.linspace(2.0, 3.0, num=5)
    array([ 2.  ,  2.25,  2.5 ,  2.75,  3.  ])
>>> np.linspace(2.0, 3.0, num=5, endpoint=False)
    array([ 2. ,  2.2,  2.4,  2.6,  2.8])
>>> np.linspace(2.0, 3.0, num=5, retstep=True)
    (array([ 2.  ,  2.25,  2.5 ,  2.75,  3.  ]), 0.25)

Graphical illustration:

>>> import matplotlib.pyplot as plt
>>> N = 8
>>> y = np.zeros(N)
>>> x1 = np.linspace(0, 10, N, endpoint=True)
>>> x2 = np.linspace(0, 10, N, endpoint=False)
>>> plt.plot(x1, y, 'o')
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.plot(x2, y + 0.5, 'o')
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.ylim([-0.5, 1])
(-0.5, 1)
>>> plt.show()

(Source code, png, pdf)


numpy.logspace

  • Array creation routines
  • next
  • previous

Previous topic

numpy.linspace

Next topic

numpy.meshgrid

numpy.logspace

numpy.logspace(start, stop, num=50, endpoint=True, base=10.0, dtype=None) [source]

Return numbers spaced evenly on a log scale.

In linear space, the sequence starts at base ** start (base to the power of start) and ends with base ** stop (see endpoint below).

Parameters:

start : float

base ** start is the starting value of the sequence.

stop : float

base ** stop is the final value of the sequence, unless endpoint is False. In that case, num + 1 values are spaced over the interval in log-space, of which all but the last (a sequence of length num) are returned.

num : integer, optional

Number of samples to generate. Default is 50.

endpoint : boolean, optional

If true, stop is the last sample. Otherwise, it is not included. Default is True.

base : float, optional

The base of the log space. The step size between the elements in ln(samples) / ln(base) (or log_base(samples)) is uniform. Default is 10.0.

dtype : dtype

The type of the output array. If dtype is not given, infer the data type from the other input arguments.
Returns:

samples : ndarray

num samples, equally spaced on a log scale.

See also

arange
Similar to linspace, with the step size specified instead of the number of samples. Note that, when used with a float endpoint, the endpoint may or may not be included.
linspace
Similar to logspace, but with the samples uniformly distributed in linear space, instead of log space.

Notes

Logspace is equivalent to the code

>>> y = np.linspace(start, stop, num=num, endpoint=endpoint)
...
>>> power(base, y).astype(dtype)
...

Examples

>>> np.logspace(2.0, 3.0, num=4)
    array([  100.        ,   215.443469  ,   464.15888336,  1000.        ])
>>> np.logspace(2.0, 3.0, num=4, endpoint=False)
    array([ 100.        ,  177.827941  ,  316.22776602,  562.34132519])
>>> np.logspace(2.0, 3.0, num=4, base=2.0)
    array([ 4.        ,  5.0396842 ,  6.34960421,  8.        ])

Graphical illustration:

>>> import matplotlib.pyplot as plt
>>> N = 10
>>> x1 = np.logspace(0.1, 1, N, endpoint=True)
>>> x2 = np.logspace(0.1, 1, N, endpoint=False)
>>> y = np.zeros(N)
>>> plt.plot(x1, y, 'o')
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.plot(x2, y + 0.5, 'o')
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.ylim([-0.5, 1])
(-0.5, 1)
>>> plt.show()

(Source code, png, pdf)


numpy.meshgrid

  • Array creation routines
  • next
  • previous

Previous topic

numpy.logspace

Next topic

numpy.mgrid

numpy.meshgrid

numpy.meshgrid(*xi, **kwargs) [source]

Return coordinate matrices from coordinate vectors.

Make N-D coordinate arrays for vectorized evaluations of N-D scalar/vector fields over N-D grids, given one-dimensional coordinate arrays x1, x2,..., xn.

Changed in version 1.9: 1-D and 0-D cases are allowed.

Parameters:

x1, x2,..., xn : array_like

1-D arrays representing the coordinates of a grid.

indexing : {‘xy’, ‘ij’}, optional

Cartesian (‘xy’, default) or matrix (‘ij’) indexing of output. See Notes for more details.

New in version 1.7.0.

sparse : bool, optional

If True a sparse grid is returned in order to conserve memory. Default is False.

New in version 1.7.0.

copy : bool, optional

If False, a view into the original arrays are returned in order to conserve memory. Default is True. Please note that sparse=False, copy=False will likely return non-contiguous arrays. Furthermore, more than one element of a broadcast array may refer to a single memory location. If you need to write to the arrays, make copies first.

New in version 1.7.0.
Returns:

X1, X2,..., XN : ndarray

For vectors x1, x2,..., ‘xn’ with lengths Ni=len(xi) , return (N1, N2, N3,...Nn) shaped arrays if indexing=’ij’ or (N2, N1, N3,...Nn) shaped arrays if indexing=’xy’ with the elements of xi repeated to fill the matrix along the first dimension for x1, the second for x2 and so on.

See also

index_tricks.mgrid
Construct a multi-dimensional “meshgrid” using indexing notation.
index_tricks.ogrid
Construct an open multi-dimensional “meshgrid” using indexing notation.

Notes

This function supports both indexing conventions through the indexing keyword argument. Giving the string ‘ij’ returns a meshgrid with matrix indexing, while ‘xy’ returns a meshgrid with Cartesian indexing. In the 2-D case with inputs of length M and N, the outputs are of shape (N, M) for ‘xy’ indexing and (M, N) for ‘ij’ indexing. In the 3-D case with inputs of length M, N and P, outputs are of shape (N, M, P) for ‘xy’ indexing and (M, N, P) for ‘ij’ indexing. The difference is illustrated by the following code snippet:

xv, yv = meshgrid(x, y, sparse=False, indexing='ij')
for i in range(nx):
    for j in range(ny):
        # treat xv[i,j], yv[i,j]

xv, yv = meshgrid(x, y, sparse=False, indexing='xy')
for i in range(nx):
    for j in range(ny):
        # treat xv[j,i], yv[j,i]

In the 1-D and 0-D case, the indexing and sparse keywords have no effect.

Examples

>>> nx, ny = (3, 2)
>>> x = np.linspace(0, 1, nx)
>>> y = np.linspace(0, 1, ny)
>>> xv, yv = meshgrid(x, y)
>>> xv
array([[ 0. ,  0.5,  1. ],
       [ 0. ,  0.5,  1. ]])
>>> yv
array([[ 0.,  0.,  0.],
       [ 1.,  1.,  1.]])
>>> xv, yv = meshgrid(x, y, sparse=True)  # make sparse output arrays
>>> xv
array([[ 0. ,  0.5,  1. ]])
>>> yv
array([[ 0.],
       [ 1.]])

meshgrid is very useful to evaluate functions on a grid.

>>> x = np.arange(-5, 5, 0.1)
>>> y = np.arange(-5, 5, 0.1)
>>> xx, yy = meshgrid(x, y, sparse=True)
>>> z = np.sin(xx**2 + yy**2) / (xx**2 + yy**2)
>>> h = plt.contourf(x,y,z)


numpy.mgrid

  • Array creation routines
  • next
  • previous

Previous topic

numpy.meshgrid

Next topic

numpy.ogrid

numpy.mgrid

numpy.mgrid = <numpy.lib.index_tricks.nd_grid object at 0x0000000004640D68>

nd_grid instance which returns a dense multi-dimensional “meshgrid”.

An instance of numpy.lib.index_tricks.nd_grid which returns an dense (or fleshed out) mesh-grid when indexed, so that each returned argument has the same shape. The dimensions and number of the output arrays are equal to the number of indexing dimensions. If the step length is not a complex number, then the stop is not inclusive.

However, if the step length is a complex number (e.g. 5j), then the integer part of its magnitude is interpreted as specifying the number of points to create between the start and stop values, where the stop value is inclusive.

Returns: mesh-grid ndarrays all of the same dimensions

See also

numpy.lib.index_tricks.nd_grid
class of ogrid and mgrid objects
ogrid
like mgrid but returns open (not fleshed out) mesh grids
r_
array concatenator

Examples

>>> np.mgrid[0:5,0:5]
array([[[0, 0, 0, 0, 0],
        [1, 1, 1, 1, 1],
        [2, 2, 2, 2, 2],
        [3, 3, 3, 3, 3],
        [4, 4, 4, 4, 4]],
       [[0, 1, 2, 3, 4],
        [0, 1, 2, 3, 4],
        [0, 1, 2, 3, 4],
        [0, 1, 2, 3, 4],
        [0, 1, 2, 3, 4]]])
>>> np.mgrid[-1:1:5j]
array([-1. , -0.5,  0. ,  0.5,  1. ])


numpy.ogrid

  • Indexing routines
  • next
  • previous

Previous topic

numpy.ix

Next topic

numpy.ravel_multi_index

numpy.ogrid

numpy.ogrid = <numpy.lib.index_tricks.nd_grid object at 0x0000000004640DD8>

nd_grid instance which returns an open multi-dimensional “meshgrid”.

An instance of numpy.lib.index_tricks.nd_grid which returns an open (i.e. not fleshed out) mesh-grid when indexed, so that only one dimension of each returned array is greater than 1. The dimension and number of the output arrays are equal to the number of indexing dimensions. If the step length is not a complex number, then the stop is not inclusive.

However, if the step length is a complex number (e.g. 5j), then the integer part of its magnitude is interpreted as specifying the number of points to create between the start and stop values, where the stop value is inclusive.

Returns: mesh-grid ndarrays with only one dimension

See also

np.lib.index_tricks.nd_grid
class of ogrid and mgrid objects
mgrid
like ogrid but returns dense (or fleshed out) mesh grids
r_
array concatenator

Examples

>>> from numpy import ogrid
>>> ogrid[-1:1:5j]
array([-1. , -0.5,  0. ,  0.5,  1. ])
>>> ogrid[0:5,0:5]
[array([[0],
        [1],
        [2],
        [3],
        [4]]), array([[0, 1, 2, 3, 4]])]


numpy.diag

  • Indexing routines
  • next
  • previous

Previous topic

numpy.compress

Next topic

numpy.diagonal

numpy.diag

numpy.diag(v, k=0) [source]

Extract a diagonal or construct a diagonal array.

See the more detailed documentation for numpy.diagonal if you use this function to extract a diagonal and wish to write to the resulting array; whether it returns a copy or a view depends on what version of numpy you are using.

Parameters:

v : array_like

If v is a 2-D array, return a copy of its k-th diagonal. If v is a 1-D array, return a 2-D array with v on the k-th diagonal.

k : int, optional

Diagonal in question. The default is 0. Use k>0 for diagonals above the main diagonal, and k<0 for diagonals below the main diagonal.
Returns:

out : ndarray

The extracted diagonal or constructed diagonal array.

See also

diagonal
Return specified diagonals.
diagflat
Create a 2-D array with the flattened input as a diagonal.
trace
Sum along diagonals.
triu
Upper triangle of an array.
tril
Lower triangle of an array.

Examples

>>> x = np.arange(9).reshape((3,3))
>>> x
array([[0, 1, 2],
       [3, 4, 5],
       [6, 7, 8]])

>>> np.diag(x)
array([0, 4, 8])
>>> np.diag(x, k=1)
array([1, 5])
>>> np.diag(x, k=-1)
array([3, 7])

>>> np.diag(np.diag(x))
array([[0, 0, 0],
       [0, 4, 0],
       [0, 0, 8]])


numpy.diagflat

  • Array creation routines
  • next
  • previous

Previous topic

numpy.diag

Next topic

numpy.tri

numpy.diagflat

numpy.diagflat(v, k=0) [source]

Create a two-dimensional array with the flattened input as a diagonal.

Parameters:

v : array_like

Input data, which is flattened and set as the k-th diagonal of the output.

k : int, optional

Diagonal to set; 0, the default, corresponds to the “main” diagonal, a positive (negative) k giving the number of the diagonal above (below) the main.
Returns:

out : ndarray

The 2-D output array.

See also

diag
MATLAB work-alike for 1-D and 2-D arrays.
diagonal
Return specified diagonals.
trace
Sum along diagonals.

Examples

>>> np.diagflat([[1,2], [3,4]])
array([[1, 0, 0, 0],
       [0, 2, 0, 0],
       [0, 0, 3, 0],
       [0, 0, 0, 4]])

>>> np.diagflat([1,2], 1)
array([[0, 1, 0],
       [0, 0, 2],
       [0, 0, 0]])


numpy.tri

  • Array creation routines
  • next
  • previous

Previous topic

numpy.diagflat

Next topic

numpy.tril

numpy.tri

numpy.tri(N, M=None, k=0, dtype=<type 'float'>) [source]

An array with ones at and below the given diagonal and zeros elsewhere.

Parameters:

N : int

Number of rows in the array.

M : int, optional

Number of columns in the array. By default, M is taken equal to N.

k : int, optional

The sub-diagonal at and below which the array is filled. k = 0 is the main diagonal, while k < 0 is below it, and k > 0 is above. The default is 0.

dtype : dtype, optional

Data type of the returned array. The default is float.
Returns:

tri : ndarray of shape (N, M)

Array with its lower triangle filled with ones and zero elsewhere; in other words T[i,j] == 1 for i <= j + k, 0 otherwise.

Examples

>>> np.tri(3, 5, 2, dtype=int)
array([[1, 1, 1, 0, 0],
       [1, 1, 1, 1, 0],
       [1, 1, 1, 1, 1]])

>>> np.tri(3, 5, -1)
array([[ 0.,  0.,  0.,  0.,  0.],
       [ 1.,  0.,  0.,  0.,  0.],
       [ 1.,  1.,  0.,  0.,  0.]])


numpy.tril

  • Array creation routines
  • next
  • previous

Previous topic

numpy.tri

Next topic

numpy.triu

numpy.tril

numpy.tril(m, k=0) [source]

Lower triangle of an array.

Return a copy of an array with elements above the k-th diagonal zeroed.

Parameters:

m : array_like, shape (M, N)

Input array.

k : int, optional

Diagonal above which to zero elements. k = 0 (the default) is the main diagonal, k < 0 is below it and k > 0 is above.
Returns:

tril : ndarray, shape (M, N)

Lower triangle of m, of same shape and data-type as m.

See also

triu
same thing, only for the upper triangle

Examples

>>> np.tril([[1,2,3],[4,5,6],[7,8,9],[10,11,12]], -1)
array([[ 0,  0,  0],
       [ 4,  0,  0],
       [ 7,  8,  0],
       [10, 11, 12]])


numpy.triu

  • Array creation routines
  • next
  • previous

Previous topic

numpy.tril

Next topic

numpy.vander

numpy.triu

numpy.triu(m, k=0) [source]

Upper triangle of an array.

Return a copy of a matrix with the elements below the k-th diagonal zeroed.

Please refer to the documentation for tril for further details.

See also

tril
lower triangle of an array

Examples

>>> np.triu([[1,2,3],[4,5,6],[7,8,9],[10,11,12]], -1)
array([[ 1,  2,  3],
       [ 4,  5,  6],
       [ 0,  8,  9],
       [ 0,  0, 12]])


numpy.vander

  • Array creation routines
  • next
  • previous

Previous topic

numpy.triu

Next topic

numpy.mat

numpy.vander

numpy.vander(x, N=None, increasing=False) [source]

Generate a Vandermonde matrix.

The columns of the output matrix are powers of the input vector. The order of the powers is determined by the increasing boolean argument. Specifically, when increasing is False, the i-th output column is the input vector raised element-wise to the power of N - i - 1. Such a matrix with a geometric progression in each row is named for Alexandre- Theophile Vandermonde.

Parameters:

x : array_like

1-D input array.

N : int, optional

Number of columns in the output. If N is not specified, a square array is returned (N = len(x)).

increasing : bool, optional

Order of the powers of the columns. If True, the powers increase from left to right, if False (the default) they are reversed.

New in version 1.9.0.
Returns:

out : ndarray

Vandermonde matrix. If increasing is False, the first column is x^(N-1), the second x^(N-2) and so forth. If increasing is True, the columns are x^0, x^1, ..., x^(N-1).

See also

polynomial.polynomial.polyvander

Examples

>>> x = np.array([1, 2, 3, 5])
>>> N = 3
>>> np.vander(x, N)
array([[ 1,  1,  1],
       [ 4,  2,  1],
       [ 9,  3,  1],
       [25,  5,  1]])

>>> np.column_stack([x**(N-1-i) for i in range(N)])
array([[ 1,  1,  1],
       [ 4,  2,  1],
       [ 9,  3,  1],
       [25,  5,  1]])

>>> x = np.array([1, 2, 3, 5])
>>> np.vander(x)
array([[  1,   1,   1,   1],
       [  8,   4,   2,   1],
       [ 27,   9,   3,   1],
       [125,  25,   5,   1]])
>>> np.vander(x, increasing=True)
array([[  1,   1,   1,   1],
       [  1,   2,   4,   8],
       [  1,   3,   9,  27],
       [  1,   5,  25, 125]])

The determinant of a square Vandermonde matrix is the product of the differences between the values of the input vector:

>>> np.linalg.det(np.vander(x))
48.000000000000043
>>> (5-3)*(5-2)*(5-1)*(3-2)*(3-1)*(2-1)
48


numpy.mat

  • Array creation routines
  • next
  • previous

Previous topic

numpy.vander

Next topic

numpy.bmat

numpy.mat

numpy.mat(data, dtype=None) [source]

Interpret the input as a matrix.

Unlike matrix, asmatrix does not make a copy if the input is already a matrix or an ndarray. Equivalent to matrix(data, copy=False).

Parameters:

data : array_like

Input data.
Returns:

mat : matrix

data interpreted as a matrix.

Examples

>>> x = np.array([[1, 2], [3, 4]])

>>> m = np.asmatrix(x)

>>> x[0,0] = 5

>>> m
matrix([[5, 2],
        [3, 4]])


Array manipulation routines

  • next
  • previous

Table Of Contents

  • Array manipulation routines
    • Basic operations
    • Changing array shape
    • Transpose-like operations
    • Changing number of dimensions
    • Changing kind of array
    • Joining arrays
    • Splitting arrays
    • Tiling arrays
    • Adding and removing elements
    • Rearranging elements

Previous topic

numpy.bmat

Next topic

numpy.copyto

Array manipulation routines

Basic operations

copyto(dst, src[, casting, where, preservena]) Copies values from one array to another, broadcasting as necessary.

Changing array shape

reshape(a, newshape[, order]) | Gives a new shape to an array without changing its data.
ravel(a[, order]) | Return a flattened array.
ndarray.flat | A 1-D iterator over the array.
ndarray.flatten([order]) | Return a copy of the array collapsed into one dimension.

Transpose-like operations

rollaxis(a, axis[, start]) | Roll the specified axis backwards, until it lies in a given position.
swapaxes(a, axis1, axis2) | Interchange two axes of an array.
ndarray.T | Same as self.transpose(), except that self is returned if self.ndim < 2.
transpose(a[, axes]) | Permute the dimensions of an array.

Changing number of dimensions

atleast_1d(*arys) | Convert inputs to arrays with at least one dimension.
atleast_2d(*arys) | View inputs as arrays with at least two dimensions.
atleast_3d(*arys) | View inputs as arrays with at least three dimensions.
broadcast | Produce an object that mimics broadcasting.
broadcast_arrays(*args) | Broadcast any number of arrays against each other.
expand_dims(a, axis) | Expand the shape of an array.
squeeze(a[, axis]) | Remove single-dimensional entries from the shape of an array.

Changing kind of array

asarray(a[, dtype, order]) | Convert the input to an array.
asanyarray(a[, dtype, order]) | Convert the input to an ndarray, but pass ndarray subclasses through.
asmatrix(data[, dtype]) | Interpret the input as a matrix.
asfarray(a[, dtype]) | Return an array converted to a float type.
asfortranarray(a[, dtype]) | Return an array laid out in Fortran order in memory.
ascontiguousarray(a[, dtype]) | Return a contiguous array in memory (C order).
asarray_chkfinite(a[, dtype, order]) | Convert the input to an array, checking for NaNs or Infs.
asscalar(a) | Convert an array of size 1 to its scalar equivalent.
require(a[, dtype, requirements]) | Return an ndarray of the provided type that satisfies requirements.

Joining arrays

column_stack(tup) | Stack 1-D arrays as columns into a 2-D array.
concatenate((a1, a2, ...)[, axis]) | Join a sequence of arrays together.
dstack(tup) | Stack arrays in sequence depth wise (along third axis).
hstack(tup) | Stack arrays in sequence horizontally (column wise).
vstack(tup) | Stack arrays in sequence vertically (row wise).

Splitting arrays

array_split(ary, indices_or_sections[, axis]) | Split an array into multiple sub-arrays.
dsplit(ary, indices_or_sections) | Split array into multiple sub-arrays along the 3rd axis (depth).
hsplit(ary, indices_or_sections) | Split an array into multiple sub-arrays horizontally (column-wise).
split(ary, indices_or_sections[, axis]) | Split an array into multiple sub-arrays.
vsplit(ary, indices_or_sections) | Split an array into multiple sub-arrays vertically (row-wise).

Tiling arrays

tile(A, reps) | Construct an array by repeating A the number of times given by reps.
repeat(a, repeats[, axis]) | Repeat elements of an array.

Adding and removing elements

delete(arr, obj[, axis]) | Return a new array with sub-arrays along an axis deleted.
insert(arr, obj, values[, axis]) | Insert values along the given axis before the given indices.
append(arr, values[, axis]) | Append values to the end of an array.
resize(a, new_shape) | Return a new array with the specified shape.
trim_zeros(filt[, trim]) | Trim the leading and/or trailing zeros from a 1-D array or sequence.
unique(ar[, return_index, return_inverse, ...]) | Find the unique elements of an array.

Rearranging elements

fliplr(m) | Flip array in the left/right direction.
flipud(m) | Flip array in the up/down direction.
reshape(a, newshape[, order]) | Gives a new shape to an array without changing its data.
roll(a, shift[, axis]) | Roll array elements along a given axis.
rot90(m[, k]) | Rotate an array by 90 degrees in the counter-clockwise direction.


numpy.copyto

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.rot90

Next topic

numpy.reshape

numpy.copyto

numpy.copyto(dst, src, casting='same_kind', where=None, preservena=False)

Copies values from one array to another, broadcasting as necessary.

Raises a TypeError if the casting rule is violated, and if where is provided, it selects which elements to copy.

New in version 1.7.0.

Parameters:

dst : ndarray

The array into which values are copied.

src : array_like

The array from which values are copied.

casting : {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

Controls what kind of data casting may occur when copying.

  • ‘no’ means the data types should not be cast at all.
  • ‘equiv’ means only byte-order changes are allowed.
  • ‘safe’ means only casts which can preserve values are allowed.
  • ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.
  • ‘unsafe’ means any data conversions may be done.

where : array_like of bool, optional

A boolean array which is broadcasted to match the dimensions of dst, and selects elements to copy from src to dst wherever it contains the value True.

preservena : bool, optional

If set to True, leaves any NA values in dst untouched. This is similar to the “hard mask” feature in numpy.ma.


numpy.reshape

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.flipud

Next topic

numpy.roll

numpy.reshape

numpy.reshape(a, newshape, order='C') [source]

Gives a new shape to an array without changing its data.

Parameters:

a : array_like

Array to be reshaped.

newshape : int or tuple of ints

The new shape should be compatible with the original shape. If an integer, then the result will be a 1-D array of that length. One shape dimension can be -1. In this case, the value is inferred from the length of the array and remaining dimensions.

order : {‘C’, ‘F’, ‘A’}, optional

Read the elements of a using this index order, and place the elements into the reshaped array using this index order. ‘C’ means to read / write the elements using C-like index order, with the last axis index changing fastest, back to the first axis index changing slowest. ‘F’ means to read / write the elements using Fortran-like index order, with the first index changing fastest, and the last index changing slowest. Note that the ‘C’ and ‘F’ options take no account of the memory layout of the underlying array, and only refer to the order of indexing. ‘A’ means to read / write the elements in Fortran-like index order if a is Fortran contiguous in memory, C-like order otherwise.
Returns:

reshaped_array : ndarray

This will be a new view object if possible; otherwise, it will be a copy. Note there is no guarantee of the memory layout (C- or Fortran- contiguous) of the returned array.

See also

ndarray.reshape
Equivalent method.

Notes

It is not always possible to change the shape of an array without copying the data. If you want an error to be raise if the data is copied, you should assign the new shape to the shape attribute of the array:

>>> a = np.zeros((10, 2))
# A transpose make the array non-contiguous
>>> b = a.T
# Taking a view makes it possible to modify the shape without modifying the
# initial object.
>>> c = b.view()
>>> c.shape = (20)
AttributeError: incompatible shape for a non-contiguous array

The order keyword gives the index ordering both for fetching the values from a, and then placing the values into the output array. For example, let’s say you have an array:

>>> a = np.arange(6).reshape((3, 2))
>>> a
array([[0, 1],
       [2, 3],
       [4, 5]])

You can think of reshaping as first raveling the array (using the given index order), then inserting the elements from the raveled array into the new array using the same kind of index ordering as was used for the raveling.

>>> np.reshape(a, (2, 3)) # C-like index ordering
array([[0, 1, 2],
       [3, 4, 5]])
>>> np.reshape(np.ravel(a), (2, 3)) # equivalent to C ravel then C reshape
array([[0, 1, 2],
       [3, 4, 5]])
>>> np.reshape(a, (2, 3), order='F') # Fortran-like index ordering
array([[0, 4, 3],
       [2, 1, 5]])
>>> np.reshape(np.ravel(a, order='F'), (2, 3), order='F')
array([[0, 4, 3],
       [2, 1, 5]])

Examples

>>> a = np.array([[1,2,3], [4,5,6]])
>>> np.reshape(a, 6)
array([1, 2, 3, 4, 5, 6])
>>> np.reshape(a, 6, order='F')
array([1, 4, 2, 5, 3, 6])

>>> np.reshape(a, (3,-1))       # the unspecified value is inferred to be 2
array([[1, 2],
       [3, 4],
       [5, 6]])


numpy.ravel

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.reshape

Next topic

numpy.ndarray.flat

numpy.ravel

numpy.ravel(a, order='C') [source]

Return a flattened array.

A 1-D array, containing the elements of the input, is returned. A copy is made only if needed.

Parameters:

a : array_like

Input array. The elements in a are read in the order specified by order, and packed as a 1-D array.

order : {‘C’,’F’, ‘A’, ‘K’}, optional

The elements of a are read using this index order. ‘C’ means to index the elements in C-like order, with the last axis index changing fastest, back to the first axis index changing slowest. ‘F’ means to index the elements in Fortran-like index order, with the first index changing fastest, and the last index changing slowest. Note that the ‘C’ and ‘F’ options take no account of the memory layout of the underlying array, and only refer to the order of axis indexing. ‘A’ means to read the elements in Fortran-like index order if a is Fortran contiguous in memory, C-like order otherwise. ‘K’ means to read the elements in the order they occur in memory, except for reversing the data when strides are negative. By default, ‘C’ index order is used.
Returns:

1d_array : ndarray

Output of the same dtype as a, and of shape (a.size,).

See also

ndarray.flat
1-D iterator over an array.
ndarray.flatten
1-D array copy of the elements of an array in row-major order.

Notes

In C-like (row-major) order, in two dimensions, the row index varies the slowest, and the column index the quickest. This can be generalized to multiple dimensions, where row-major order implies that the index along the first axis varies slowest, and the index along the last quickest. The opposite holds for Fortran-like, or column-major, index ordering.

Examples

It is equivalent to reshape(-1, order=order).

>>> x = np.array([[1, 2, 3], [4, 5, 6]])
>>> print np.ravel(x)
[1 2 3 4 5 6]

>>> print x.reshape(-1)
[1 2 3 4 5 6]

>>> print np.ravel(x, order='F')
[1 4 2 5 3 6]

When order is ‘A’, it will preserve the array’s ‘C’ or ‘F’ ordering:

>>> print np.ravel(x.T)
[1 4 2 5 3 6]
>>> print np.ravel(x.T, order='A')
[1 2 3 4 5 6]

When order is ‘K’, it will preserve orderings that are neither ‘C’ nor ‘F’, but won’t reverse axes:

>>> a = np.arange(3)[::-1]; a
array([2, 1, 0])
>>> a.ravel(order='C')
array([2, 1, 0])
>>> a.ravel(order='K')
array([2, 1, 0])

>>> a = np.arange(12).reshape(2,3,2).swapaxes(1,2); a
array([[[ 0,  2,  4],
        [ 1,  3,  5]],
       [[ 6,  8, 10],
        [ 7,  9, 11]]])
>>> a.ravel(order='C')
array([ 0,  2,  4,  1,  3,  5,  6,  8, 10,  7,  9, 11])
>>> a.ravel(order='K')
array([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11])


numpy.rollaxis

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.ndarray.flatten

Next topic

numpy.swapaxes

numpy.rollaxis

numpy.rollaxis(a, axis, start=0) [source]

Roll the specified axis backwards, until it lies in a given position.

Parameters:

a : ndarray

Input array.

axis : int

The axis to roll backwards. The positions of the other axes do not change relative to one another.

start : int, optional

The axis is rolled until it lies before this position. The default, 0, results in a “complete” roll.
Returns:

res : ndarray

Output array.

See also

roll
Roll the elements of an array by a number of positions along a given axis.

Examples

>>> a = np.ones((3,4,5,6))
>>> np.rollaxis(a, 3, 1).shape
(3, 6, 4, 5)
>>> np.rollaxis(a, 2).shape
(5, 3, 4, 6)
>>> np.rollaxis(a, 1, 4).shape
(3, 5, 6, 4)


numpy.swapaxes

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.rollaxis

Next topic

numpy.ndarray.T

numpy.swapaxes

numpy.swapaxes(a, axis1, axis2) [source]

Interchange two axes of an array.

Parameters:

a : array_like

Input array.

axis1 : int

First axis.

axis2 : int

Second axis.
Returns:

a_swapped : ndarray

If a is an ndarray, then a view of a is returned; otherwise a new array is created.

Examples

>>> x = np.array([[1,2,3]])
>>> np.swapaxes(x,0,1)
array([[1],
       [2],
       [3]])

>>> x = np.array([[[0,1],[2,3]],[[4,5],[6,7]]])
>>> x
array([[[0, 1],
        [2, 3]],
       [[4, 5],
        [6, 7]]])

>>> np.swapaxes(x,0,2)
array([[[0, 4],
        [2, 6]],
       [[1, 5],
        [3, 7]]])


numpy.transpose

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.ndarray.T

Next topic

numpy.atleast_1d

numpy.transpose

numpy.transpose(a, axes=None) [source]

Permute the dimensions of an array.

Parameters:

a : array_like

Input array.

axes : list of ints, optional

By default, reverse the dimensions, otherwise permute the axes according to the values given.
Returns:

p : ndarray

a with its axes permuted. A view is returned whenever possible.

See also

rollaxis

Examples

>>> x = np.arange(4).reshape((2,2))
>>> x
array([[0, 1],
       [2, 3]])

>>> np.transpose(x)
array([[0, 2],
       [1, 3]])

>>> x = np.ones((1, 2, 3))
>>> np.transpose(x, (1, 0, 2)).shape
(2, 1, 3)


numpy.atleast_1d

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.transpose

Next topic

numpy.atleast_2d

numpy.atleast_1d

numpy.atleast_1d(*arys) [source]

Convert inputs to arrays with at least one dimension.

Scalar inputs are converted to 1-dimensional arrays, whilst higher-dimensional inputs are preserved.

Parameters:

arys1, arys2, ... : array_like

One or more input arrays.
Returns:

ret : ndarray

An array, or sequence of arrays, each with a.ndim >= 1. Copies are made only if necessary.

See also

atleast_2d, atleast_3d

Examples

>>> np.atleast_1d(1.0)
array([ 1.])

>>> x = np.arange(9.0).reshape(3,3)
>>> np.atleast_1d(x)
array([[ 0.,  1.,  2.],
       [ 3.,  4.,  5.],
       [ 6.,  7.,  8.]])
>>> np.atleast_1d(x) is x
True

>>> np.atleast_1d(1, [3, 4])
[array([1]), array([3, 4])]


numpy.atleast_2d

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.atleast_1d

Next topic

numpy.atleast_3d

numpy.atleast_2d

numpy.atleast_2d(*arys) [source]

View inputs as arrays with at least two dimensions.

Parameters:

arys1, arys2, ... : array_like

One or more array-like sequences. Non-array inputs are converted to arrays. Arrays that already have two or more dimensions are preserved.
Returns:

res, res2, ... : ndarray

An array, or tuple of arrays, each with a.ndim >= 2. Copies are avoided where possible, and views with two or more dimensions are returned.

See also

atleast_1d, atleast_3d

Examples

>>> np.atleast_2d(3.0)
array([[ 3.]])

>>> x = np.arange(3.0)
>>> np.atleast_2d(x)
array([[ 0.,  1.,  2.]])
>>> np.atleast_2d(x).base is x
True

>>> np.atleast_2d(1, [1, 2], [[1, 2]])
[array([[1]]), array([[1, 2]]), array([[1, 2]])]


numpy.atleast_3d

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.atleast_2d

Next topic

numpy.broadcast

numpy.atleast_3d

numpy.atleast_3d(*arys) [source]

View inputs as arrays with at least three dimensions.

Parameters:

arys1, arys2, ... : array_like

One or more array-like sequences. Non-array inputs are converted to arrays. Arrays that already have three or more dimensions are preserved.
Returns:

res1, res2, ... : ndarray

An array, or tuple of arrays, each with a.ndim >= 3. Copies are avoided where possible, and views with three or more dimensions are returned. For example, a 1-D array of shape (N,) becomes a view of shape (1, N, 1), and a 2-D array of shape (M, N) becomes a view of shape (M, N, 1).

See also

atleast_1d, atleast_2d

Examples

>>> np.atleast_3d(3.0)
array([[[ 3.]]])

>>> x = np.arange(3.0)
>>> np.atleast_3d(x).shape
(1, 3, 1)

>>> x = np.arange(12.0).reshape(4,3)
>>> np.atleast_3d(x).shape
(4, 3, 1)
>>> np.atleast_3d(x).base is x
True

>>> for arr in np.atleast_3d([1, 2], [[1, 2]], [[[1, 2]]]):
...     print arr, arr.shape
...
[[[1]
  [2]]] (1, 2, 1)
[[[1]
  [2]]] (1, 2, 1)
[[[1 2]]] (1, 1, 2)


numpy.broadcast_arrays

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.broadcast.reset

Next topic

numpy.expand_dims

numpy.broadcast_arrays

numpy.broadcast_arrays(*args) [source]

Broadcast any number of arrays against each other.

Parameters:

`*args` : array_likes

The arrays to broadcast.
Returns:

broadcasted : list of arrays

These arrays are views on the original arrays. They are typically not contiguous. Furthermore, more than one element of a broadcasted array may refer to a single memory location. If you need to write to the arrays, make copies first.

Examples

>>> x = np.array([[1,2,3]])
>>> y = np.array([[1],[2],[3]])
>>> np.broadcast_arrays(x, y)
[array([[1, 2, 3],
       [1, 2, 3],
       [1, 2, 3]]), array([[1, 1, 1],
       [2, 2, 2],
       [3, 3, 3]])]

Here is a useful idiom for getting contiguous copies instead of non-contiguous views.

>>> [np.array(a) for a in np.broadcast_arrays(x, y)]
[array([[1, 2, 3],
       [1, 2, 3],
       [1, 2, 3]]), array([[1, 1, 1],
       [2, 2, 2],
       [3, 3, 3]])]


numpy.expand_dims

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.broadcast_arrays

Next topic

numpy.squeeze

numpy.expand_dims

numpy.expand_dims(a, axis) [source]

Expand the shape of an array.

Insert a new axis, corresponding to a given position in the array shape.

Parameters:

a : array_like

Input array.

axis : int

Position (amongst axes) where new axis is to be inserted.
Returns:

res : ndarray

Output array. The number of dimensions is one greater than that of the input array.

See also

doc.indexing, atleast_1d, atleast_2d, atleast_3d

Examples

>>> x = np.array([1,2])
>>> x.shape
(2,)

The following is equivalent to x[np.newaxis,:] or x[np.newaxis]:

>>> y = np.expand_dims(x, axis=0)
>>> y
array([[1, 2]])
>>> y.shape
(1, 2)

>>> y = np.expand_dims(x, axis=1)  # Equivalent to x[:,newaxis]
>>> y
array([[1],
       [2]])
>>> y.shape
(2, 1)

Note that some examples may use None instead of np.newaxis. These are the same objects:

>>> np.newaxis is None
True


numpy.squeeze

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.expand_dims

Next topic

numpy.asarray

numpy.squeeze

numpy.squeeze(a, axis=None) [source]

Remove single-dimensional entries from the shape of an array.

Parameters:

a : array_like

Input data.

axis : None or int or tuple of ints, optional

New in version 1.7.0.

Selects a subset of the single-dimensional entries in the shape. If an axis is selected with shape entry greater than one, an error is raised.
Returns:

squeezed : ndarray

The input array, but with all or a subset of the dimensions of length 1 removed. This is always a itself or a view into a.

Examples

>>> x = np.array([[[0], [1], [2]]])
>>> x.shape
(1, 3, 1)
>>> np.squeeze(x).shape
(3,)
>>> np.squeeze(x, axis=(2,)).shape
(1, 3)


numpy.asfarray

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.asmatrix

Next topic

numpy.asfortranarray

numpy.asfarray

numpy.asfarray(a, dtype=<type 'numpy.float64'>) [source]

Return an array converted to a float type.

Parameters:

a : array_like

The input array.

dtype : str or dtype object, optional

Float type code to coerce input array a. If dtype is one of the ‘int’ dtypes, it is replaced with float64.
Returns:

out : ndarray

The input a as a float ndarray.

Examples

>>> np.asfarray([2, 3])
array([ 2.,  3.])
>>> np.asfarray([2, 3], dtype='float')
array([ 2.,  3.])
>>> np.asfarray([2, 3], dtype='int8')
array([ 2.,  3.])


numpy.asfortranarray

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.asfarray

Next topic

numpy.ascontiguousarray

numpy.asfortranarray

numpy.asfortranarray(a, dtype=None) [source]

Return an array laid out in Fortran order in memory.

Parameters:

a : array_like

Input array.

dtype : str or dtype object, optional

By default, the data-type is inferred from the input data.
Returns:

out : ndarray

The input a in Fortran, or column-major, order.

See also

ascontiguousarray
Convert input to a contiguous (C order) array.
asanyarray
Convert input to an ndarray with either row or column-major memory order.
require
Return an ndarray that satisfies requirements.
ndarray.flags
Information about the memory layout of the array.

Examples

>>> x = np.arange(6).reshape(2,3)
>>> y = np.asfortranarray(x)
>>> x.flags['F_CONTIGUOUS']
False
>>> y.flags['F_CONTIGUOUS']
True


numpy.asarray_chkfinite

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.ascontiguousarray

Next topic

numpy.asscalar

numpy.asarray_chkfinite

numpy.asarray_chkfinite(a, dtype=None, order=None) [source]

Convert the input to an array, checking for NaNs or Infs.

Parameters:

a : array_like

Input data, in any form that can be converted to an array. This includes lists, lists of tuples, tuples, tuples of tuples, tuples of lists and ndarrays. Success requires no NaNs or Infs.

dtype : data-type, optional

By default, the data-type is inferred from the input data.

order : {‘C’, ‘F’}, optional

Whether to use row-major (‘C’) or column-major (‘FORTRAN’) memory representation. Defaults to ‘C’.
Returns:

out : ndarray

Array interpretation of a. No copy is performed if the input is already an ndarray. If a is a subclass of ndarray, a base class ndarray is returned.
Raises:

ValueError

Raises ValueError if a contains NaN (Not a Number) or Inf (Infinity).

See also

asarray
Create and array.
asanyarray
Similar function which passes through subclasses.
ascontiguousarray
Convert input to a contiguous array.
asfarray
Convert input to a floating point ndarray.
asfortranarray
Convert input to an ndarray with column-major memory order.
fromiter
Create an array from an iterator.
fromfunction
Construct an array by executing a function on grid positions.

Examples

Convert a list into an array. If all elements are finite asarray_chkfinite is identical to asarray.

>>> a = [1, 2]
>>> np.asarray_chkfinite(a, dtype=float)
array([1., 2.])

Raises ValueError if array_like contains Nans or Infs.

>>> a = [1, 2, np.inf]
>>> try:
...     np.asarray_chkfinite(a)
... except ValueError:
...     print 'ValueError'
...
ValueError


numpy.asscalar

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.asarray_chkfinite

Next topic

numpy.require

numpy.asscalar

numpy.asscalar(a) [source]

Convert an array of size 1 to its scalar equivalent.

Parameters:

a : ndarray

Input array of size 1.
Returns:

out : scalar

Scalar representation of a. The output data type is the same type returned by the input’s item method.

Examples

>>> np.asscalar(np.array([24]))
24


numpy.require

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.asscalar

Next topic

numpy.column_stack

numpy.require

numpy.require(a, dtype=None, requirements=None) [source]

Return an ndarray of the provided type that satisfies requirements.

This function is useful to be sure that an array with the correct flags is returned for passing to compiled code (perhaps through ctypes).

Parameters:

a : array_like

The object to be converted to a type-and-requirement-satisfying array.

dtype : data-type

The required data-type, the default data-type is float64).

requirements : str or list of str

The requirements list can be any of the following

  • ‘F_CONTIGUOUS’ (‘F’) - ensure a Fortran-contiguous array
  • ‘C_CONTIGUOUS’ (‘C’) - ensure a C-contiguous array
  • ‘ALIGNED’ (‘A’) - ensure a data-type aligned array
  • ‘WRITEABLE’ (‘W’) - ensure a writable array
  • ‘OWNDATA’ (‘O’) - ensure an array that owns its own data

See also

asarray
Convert input to an ndarray.
asanyarray
Convert to an ndarray, but pass through ndarray subclasses.
ascontiguousarray
Convert input to a contiguous array.
asfortranarray
Convert input to an ndarray with column-major memory order.
ndarray.flags
Information about the memory layout of the array.

Notes

The returned array will be guaranteed to have the listed requirements by making a copy if needed.

Examples

>>> x = np.arange(6).reshape(2,3)
>>> x.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : False
  WRITEABLE : True
  ALIGNED : True
  UPDATEIFCOPY : False

>>> y = np.require(x, dtype=np.float32, requirements=['A', 'O', 'W', 'F'])
>>> y.flags
  C_CONTIGUOUS : False
  F_CONTIGUOUS : True
  OWNDATA : True
  WRITEABLE : True
  ALIGNED : True
  UPDATEIFCOPY : False


numpy.column_stack

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.require

Next topic

numpy.concatenate

numpy.column_stack

numpy.column_stack(tup) [source]

Stack 1-D arrays as columns into a 2-D array.

Take a sequence of 1-D arrays and stack them as columns to make a single 2-D array. 2-D arrays are stacked as-is, just like with hstack. 1-D arrays are turned into 2-D columns first.

Parameters:

tup : sequence of 1-D or 2-D arrays.

Arrays to stack. All of them must have the same first dimension.
Returns:

stacked : 2-D array

The array formed by stacking the given arrays.

See also

hstack, vstack, concatenate

Examples

>>> a = np.array((1,2,3))
>>> b = np.array((2,3,4))
>>> np.column_stack((a,b))
array([[1, 2],
       [2, 3],
       [3, 4]])


numpy.concatenate

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.column_stack

Next topic

numpy.dstack

numpy.concatenate

numpy.concatenate((a1, a2, ...), axis=0)

Join a sequence of arrays together.

Parameters:

a1, a2, ... : sequence of array_like

The arrays must have the same shape, except in the dimension corresponding to axis (the first, by default).

axis : int, optional

The axis along which the arrays will be joined. Default is 0.
Returns:

res : ndarray

The concatenated array.

See also

ma.concatenate
Concatenate function that preserves input masks.
array_split
Split an array into multiple sub-arrays of equal or near-equal size.
split
Split array into a list of multiple sub-arrays of equal size.
hsplit
Split array into multiple sub-arrays horizontally (column wise)
vsplit
Split array into multiple sub-arrays vertically (row wise)
dsplit
Split array into multiple sub-arrays along the 3rd axis (depth).
hstack
Stack arrays in sequence horizontally (column wise)
vstack
Stack arrays in sequence vertically (row wise)
dstack
Stack arrays in sequence depth wise (along third dimension)

Notes

When one or more of the arrays to be concatenated is a MaskedArray, this function will return a MaskedArray object instead of an ndarray, but the input masks are not preserved. In cases where a MaskedArray is expected as input, use the ma.concatenate function from the masked array module instead.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> b = np.array([[5, 6]])
>>> np.concatenate((a, b), axis=0)
array([[1, 2],
       [3, 4],
       [5, 6]])
>>> np.concatenate((a, b.T), axis=1)
array([[1, 2, 5],
       [3, 4, 6]])

This function will not preserve masking of MaskedArray inputs.

>>> a = np.ma.arange(3)
>>> a[1] = np.ma.masked
>>> b = np.arange(2, 5)
>>> a
masked_array(data = [0 -- 2],
             mask = [False  True False],
       fill_value = 999999)
>>> b
array([2, 3, 4])
>>> np.concatenate([a, b])
masked_array(data = [0 1 2 2 3 4],
             mask = False,
       fill_value = 999999)
>>> np.ma.concatenate([a, b])
masked_array(data = [0 -- 2 2 3 4],
             mask = [False  True False False False False],
       fill_value = 999999)


numpy.dstack

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.concatenate

Next topic

numpy.hstack

numpy.dstack

numpy.dstack(tup) [source]

Stack arrays in sequence depth wise (along third axis).

Takes a sequence of arrays and stack them along the third axis to make a single array. Rebuilds arrays divided by dsplit. This is a simple way to stack 2D arrays (images) into a single 3D array for processing.

Parameters:

tup : sequence of arrays

Arrays to stack. All of them must have the same shape along all but the third axis.
Returns:

stacked : ndarray

The array formed by stacking the given arrays.

See also

vstack
Stack along first axis.
hstack
Stack along second axis.
concatenate
Join arrays.
dsplit
Split array along third axis.

Notes

Equivalent to np.concatenate(tup, axis=2).

Examples

>>> a = np.array((1,2,3))
>>> b = np.array((2,3,4))
>>> np.dstack((a,b))
array([[[1, 2],
        [2, 3],
        [3, 4]]])

>>> a = np.array([[1],[2],[3]])
>>> b = np.array([[2],[3],[4]])
>>> np.dstack((a,b))
array([[[1, 2]],
       [[2, 3]],
       [[3, 4]]])


numpy.hstack

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.dstack

Next topic

numpy.vstack

numpy.hstack

numpy.hstack(tup) [source]

Stack arrays in sequence horizontally (column wise).

Take a sequence of arrays and stack them horizontally to make a single array. Rebuild arrays divided by hsplit.

Parameters:

tup : sequence of ndarrays

All arrays must have the same shape along all but the second axis.
Returns:

stacked : ndarray

The array formed by stacking the given arrays.

See also

vstack
Stack arrays in sequence vertically (row wise).
dstack
Stack arrays in sequence depth wise (along third axis).
concatenate
Join a sequence of arrays together.
hsplit
Split array along second axis.

Notes

Equivalent to np.concatenate(tup, axis=1)

Examples

>>> a = np.array((1,2,3))
>>> b = np.array((2,3,4))
>>> np.hstack((a,b))
array([1, 2, 3, 2, 3, 4])
>>> a = np.array([[1],[2],[3]])
>>> b = np.array([[2],[3],[4]])
>>> np.hstack((a,b))
array([[1, 2],
       [2, 3],
       [3, 4]])


numpy.vstack

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.hstack

Next topic

numpy.array_split

numpy.vstack

numpy.vstack(tup) [source]

Stack arrays in sequence vertically (row wise).

Take a sequence of arrays and stack them vertically to make a single array. Rebuild arrays divided by vsplit.

Parameters:

tup : sequence of ndarrays

Tuple containing arrays to be stacked. The arrays must have the same shape along all but the first axis.
Returns:

stacked : ndarray

The array formed by stacking the given arrays.

See also

hstack
Stack arrays in sequence horizontally (column wise).
dstack
Stack arrays in sequence depth wise (along third dimension).
concatenate
Join a sequence of arrays together.
vsplit
Split array into a list of multiple sub-arrays vertically.

Notes

Equivalent to np.concatenate(tup, axis=0) if tup contains arrays that are at least 2-dimensional.

Examples

>>> a = np.array([1, 2, 3])
>>> b = np.array([2, 3, 4])
>>> np.vstack((a,b))
array([[1, 2, 3],
       [2, 3, 4]])

>>> a = np.array([[1], [2], [3]])
>>> b = np.array([[2], [3], [4]])
>>> np.vstack((a,b))
array([[1],
       [2],
       [3],
       [2],
       [3],
       [4]])


numpy.array_split

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.vstack

Next topic

numpy.dsplit

numpy.array_split

numpy.array_split(ary, indices_or_sections, axis=0) [source]

Split an array into multiple sub-arrays.

Please refer to the split documentation. The only difference between these functions is that array_split allows indices_or_sections to be an integer that does not equally divide the axis.

See also

split
Split array into multiple sub-arrays of equal size.

Examples

>>> x = np.arange(8.0)
>>> np.array_split(x, 3)
    [array([ 0.,  1.,  2.]), array([ 3.,  4.,  5.]), array([ 6.,  7.])]


numpy.dsplit

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.array_split

Next topic

numpy.hsplit

numpy.dsplit

numpy.dsplit(ary, indices_or_sections) [source]

Split array into multiple sub-arrays along the 3rd axis (depth).

Please refer to the split documentation. dsplit is equivalent to split with axis=2, the array is always split along the third axis provided the array dimension is greater than or equal to 3.

See also

split
Split an array into multiple sub-arrays of equal size.

Examples

>>> x = np.arange(16.0).reshape(2, 2, 4)
>>> x
array([[[  0.,   1.,   2.,   3.],
        [  4.,   5.,   6.,   7.]],
       [[  8.,   9.,  10.,  11.],
        [ 12.,  13.,  14.,  15.]]])
>>> np.dsplit(x, 2)
[array([[[  0.,   1.],
        [  4.,   5.]],
       [[  8.,   9.],
        [ 12.,  13.]]]),
 array([[[  2.,   3.],
        [  6.,   7.]],
       [[ 10.,  11.],
        [ 14.,  15.]]])]
>>> np.dsplit(x, np.array([3, 6]))
[array([[[  0.,   1.,   2.],
        [  4.,   5.,   6.]],
       [[  8.,   9.,  10.],
        [ 12.,  13.,  14.]]]),
 array([[[  3.],
        [  7.]],
       [[ 11.],
        [ 15.]]]),
 array([], dtype=float64)]


numpy.hsplit

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.dsplit

Next topic

numpy.split

numpy.hsplit

numpy.hsplit(ary, indices_or_sections) [source]

Split an array into multiple sub-arrays horizontally (column-wise).

Please refer to the split documentation. hsplit is equivalent to split with axis=1, the array is always split along the second axis regardless of the array dimension.

See also

split
Split an array into multiple sub-arrays of equal size.

Examples

>>> x = np.arange(16.0).reshape(4, 4)
>>> x
array([[  0.,   1.,   2.,   3.],
       [  4.,   5.,   6.,   7.],
       [  8.,   9.,  10.,  11.],
       [ 12.,  13.,  14.,  15.]])
>>> np.hsplit(x, 2)
[array([[  0.,   1.],
       [  4.,   5.],
       [  8.,   9.],
       [ 12.,  13.]]),
 array([[  2.,   3.],
       [  6.,   7.],
       [ 10.,  11.],
       [ 14.,  15.]])]
>>> np.hsplit(x, np.array([3, 6]))
[array([[  0.,   1.,   2.],
       [  4.,   5.,   6.],
       [  8.,   9.,  10.],
       [ 12.,  13.,  14.]]),
 array([[  3.],
       [  7.],
       [ 11.],
       [ 15.]]),
 array([], dtype=float64)]

With a higher dimensional array the split is still along the second axis.

>>> x = np.arange(8.0).reshape(2, 2, 2)
>>> x
array([[[ 0.,  1.],
        [ 2.,  3.]],
       [[ 4.,  5.],
        [ 6.,  7.]]])
>>> np.hsplit(x, 2)
[array([[[ 0.,  1.]],
       [[ 4.,  5.]]]),
 array([[[ 2.,  3.]],
       [[ 6.,  7.]]])]


numpy.split

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.hsplit

Next topic

numpy.vsplit

numpy.split

numpy.split(ary, indices_or_sections, axis=0) [source]

Split an array into multiple sub-arrays.

Parameters:

ary : ndarray

Array to be divided into sub-arrays.

indices_or_sections : int or 1-D array

If indices_or_sections is an integer, N, the array will be divided into N equal arrays along axis. If such a split is not possible, an error is raised.

If indices_or_sections is a 1-D array of sorted integers, the entries indicate where along axis the array is split. For example, [2, 3] would, for axis=0, result in

  • ary[:2]
  • ary[2:3]
  • ary[3:]

If an index exceeds the dimension of the array along axis, an empty sub-array is returned correspondingly.

axis : int, optional

The axis along which to split, default is 0.
Returns:

sub-arrays : list of ndarrays

A list of sub-arrays.
Raises:

ValueError

If indices_or_sections is given as an integer, but a split does not result in equal division.

See also

array_split
Split an array into multiple sub-arrays of equal or near-equal size. Does not raise an exception if an equal division cannot be made.
hsplit
Split array into multiple sub-arrays horizontally (column-wise).
vsplit
Split array into multiple sub-arrays vertically (row wise).
dsplit
Split array into multiple sub-arrays along the 3rd axis (depth).
concatenate
Join arrays together.
hstack
Stack arrays in sequence horizontally (column wise).
vstack
Stack arrays in sequence vertically (row wise).
dstack
Stack arrays in sequence depth wise (along third dimension).

Examples

>>> x = np.arange(9.0)
>>> np.split(x, 3)
[array([ 0.,  1.,  2.]), array([ 3.,  4.,  5.]), array([ 6.,  7.,  8.])]

>>> x = np.arange(8.0)
>>> np.split(x, [3, 5, 6, 10])
[array([ 0.,  1.,  2.]),
 array([ 3.,  4.]),
 array([ 5.]),
 array([ 6.,  7.]),
 array([], dtype=float64)]


numpy.vsplit

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.split

Next topic

numpy.tile

numpy.vsplit

numpy.vsplit(ary, indices_or_sections) [source]

Split an array into multiple sub-arrays vertically (row-wise).

Please refer to the split documentation. vsplit is equivalent to split with axis=0 (default), the array is always split along the first axis regardless of the array dimension.

See also

split
Split an array into multiple sub-arrays of equal size.

Examples

>>> x = np.arange(16.0).reshape(4, 4)
>>> x
array([[  0.,   1.,   2.,   3.],
       [  4.,   5.,   6.,   7.],
       [  8.,   9.,  10.,  11.],
       [ 12.,  13.,  14.,  15.]])
>>> np.vsplit(x, 2)
[array([[ 0.,  1.,  2.,  3.],
       [ 4.,  5.,  6.,  7.]]),
 array([[  8.,   9.,  10.,  11.],
       [ 12.,  13.,  14.,  15.]])]
>>> np.vsplit(x, np.array([3, 6]))
[array([[  0.,   1.,   2.,   3.],
       [  4.,   5.,   6.,   7.],
       [  8.,   9.,  10.,  11.]]),
 array([[ 12.,  13.,  14.,  15.]]),
 array([], dtype=float64)]

With a higher dimensional array the split is still along the first axis.

>>> x = np.arange(8.0).reshape(2, 2, 2)
>>> x
array([[[ 0.,  1.],
        [ 2.,  3.]],
       [[ 4.,  5.],
        [ 6.,  7.]]])
>>> np.vsplit(x, 2)
[array([[[ 0.,  1.],
        [ 2.,  3.]]]),
 array([[[ 4.,  5.],
        [ 6.,  7.]]])]


numpy.tile

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.vsplit

Next topic

numpy.repeat

numpy.tile

numpy.tile(A, reps) [source]

Construct an array by repeating A the number of times given by reps.

If reps has length d, the result will have dimension of max(d, A.ndim).

If A.ndim < d, A is promoted to be d-dimensional by prepending new axes. So a shape (3,) array is promoted to (1, 3) for 2-D replication, or shape (1, 1, 3) for 3-D replication. If this is not the desired behavior, promote A to d-dimensions manually before calling this function.

If A.ndim > d, reps is promoted to A.ndim by pre-pending 1’s to it. Thus for an A of shape (2, 3, 4, 5), a reps of (2, 2) is treated as (1, 1, 2, 2).

Parameters:

A : array_like

The input array.

reps : array_like

The number of repetitions of A along each axis.
Returns:

c : ndarray

The tiled output array.

See also

repeat
Repeat elements of an array.

Examples

>>> a = np.array([0, 1, 2])
>>> np.tile(a, 2)
array([0, 1, 2, 0, 1, 2])
>>> np.tile(a, (2, 2))
array([[0, 1, 2, 0, 1, 2],
       [0, 1, 2, 0, 1, 2]])
>>> np.tile(a, (2, 1, 2))
array([[[0, 1, 2, 0, 1, 2]],
       [[0, 1, 2, 0, 1, 2]]])

>>> b = np.array([[1, 2], [3, 4]])
>>> np.tile(b, 2)
array([[1, 2, 1, 2],
       [3, 4, 3, 4]])
>>> np.tile(b, (2, 1))
array([[1, 2],
       [3, 4],
       [1, 2],
       [3, 4]])


numpy.repeat

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.tile

Next topic

numpy.delete

numpy.repeat

numpy.repeat(a, repeats, axis=None) [source]

Repeat elements of an array.

Parameters:

a : array_like

Input array.

repeats : {int, array of ints}

The number of repetitions for each element. repeats is broadcasted to fit the shape of the given axis.

axis : int, optional

The axis along which to repeat values. By default, use the flattened input array, and return a flat output array.
Returns:

repeated_array : ndarray

Output array which has the same shape as a, except along the given axis.

See also

tile
Tile an array.

Examples

>>> x = np.array([[1,2],[3,4]])
>>> np.repeat(x, 2)
array([1, 1, 2, 2, 3, 3, 4, 4])
>>> np.repeat(x, 3, axis=1)
array([[1, 1, 1, 2, 2, 2],
       [3, 3, 3, 4, 4, 4]])
>>> np.repeat(x, [1, 2], axis=0)
array([[1, 2],
       [3, 4],
       [3, 4]])


numpy.delete

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.repeat

Next topic

numpy.insert

numpy.delete

numpy.delete(arr, obj, axis=None) [source]

Return a new array with sub-arrays along an axis deleted. For a one dimensional array, this returns those entries not returned by arr[obj].

Parameters:

arr : array_like

Input array.

obj : slice, int or array of ints

Indicate which sub-arrays to remove.

axis : int, optional

The axis along which to delete the subarray defined by obj. If axis is None, obj is applied to the flattened array.
Returns:

out : ndarray

A copy of arr with the elements specified by obj removed. Note that delete does not occur in-place. If axis is None, out is a flattened array.

See also

insert
Insert elements into an array.
append
Append elements at the end of an array.

Notes

Often it is preferable to use a boolean mask. For example:

>>> mask = np.ones(len(arr), dtype=bool)
>>> mask[[0,2,4]] = False
>>> result = arr[mask,...]

Is equivalent to np.delete(arr, [0,2,4], axis=0), but allows further use of mask.

Examples

>>> arr = np.array([[1,2,3,4], [5,6,7,8], [9,10,11,12]])
>>> arr
array([[ 1,  2,  3,  4],
       [ 5,  6,  7,  8],
       [ 9, 10, 11, 12]])
>>> np.delete(arr, 1, 0)
array([[ 1,  2,  3,  4],
       [ 9, 10, 11, 12]])

>>> np.delete(arr, np.s_[::2], 1)
array([[ 2,  4],
       [ 6,  8],
       [10, 12]])
>>> np.delete(arr, [1,3,5], None)
array([ 1,  3,  5,  7,  8,  9, 10, 11, 12])


numpy.insert

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.delete

Next topic

numpy.append

numpy.insert

numpy.insert(arr, obj, values, axis=None) [source]

Insert values along the given axis before the given indices.

Parameters:

arr : array_like

Input array.

obj : int, slice or sequence of ints

Object that defines the index or indices before which values is inserted.

New in version 1.8.0.

Support for multiple insertions when obj is a single scalar or a sequence with one element (similar to calling insert multiple times).

values : array_like

Values to insert into arr. If the type of values is different from that of arr, values is converted to the type of arr. values should be shaped so that arr[...,obj,...] = values is legal.

axis : int, optional

Axis along which to insert values. If axis is None then arr is flattened first.
Returns:

out : ndarray

A copy of arr with values inserted. Note that insert does not occur in-place: a new array is returned. If axis is None, out is a flattened array.

See also

append
Append elements at the end of an array.
concatenate
Join a sequence of arrays together.
delete
Delete elements from an array.

Notes

Note that for higher dimensional inserts obj=0 behaves very different from obj=[0] just like arr[:,0,:] = values is different from arr[:,[0],:] = values.

Examples

>>> a = np.array([[1, 1], [2, 2], [3, 3]])
>>> a
array([[1, 1],
       [2, 2],
       [3, 3]])
>>> np.insert(a, 1, 5)
array([1, 5, 1, 2, 2, 3, 3])
>>> np.insert(a, 1, 5, axis=1)
array([[1, 5, 1],
       [2, 5, 2],
       [3, 5, 3]])

Difference between sequence and scalars: >>> np.insert(a, [1], [[1],[2],[3]], axis=1) array([[1, 1, 1],

[2, 2, 2], [3, 3, 3]])
>>> np.array_equal(np.insert(a, 1, [1, 2, 3], axis=1),
...                np.insert(a, [1], [[1],[2],[3]], axis=1))
True

>>> b = a.flatten()
>>> b
array([1, 1, 2, 2, 3, 3])
>>> np.insert(b, [2, 2], [5, 6])
array([1, 1, 5, 6, 2, 2, 3, 3])

>>> np.insert(b, slice(2, 4), [5, 6])
array([1, 1, 5, 2, 6, 2, 3, 3])

>>> np.insert(b, [2, 2], [7.13, False]) # type casting
array([1, 1, 7, 0, 2, 2, 3, 3])

>>> x = np.arange(8).reshape(2, 4)
>>> idx = (1, 3)
>>> np.insert(x, idx, 999, axis=1)
array([[  0, 999,   1,   2, 999,   3],
       [  4, 999,   5,   6, 999,   7]])


numpy.append

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.insert

Next topic

numpy.resize

numpy.append

numpy.append(arr, values, axis=None) [source]

Append values to the end of an array.

Parameters:

arr : array_like

Values are appended to a copy of this array.

values : array_like

These values are appended to a copy of arr. It must be of the correct shape (the same shape as arr, excluding axis). If axis is not specified, values can be any shape and will be flattened before use.

axis : int, optional

The axis along which values are appended. If axis is not given, both arr and values are flattened before use.
Returns:

append : ndarray

A copy of arr with values appended to axis. Note that append does not occur in-place: a new array is allocated and filled. If axis is None, out is a flattened array.

See also

insert
Insert elements into an array.
delete
Delete elements from an array.

Examples

>>> np.append([1, 2, 3], [[4, 5, 6], [7, 8, 9]])
array([1, 2, 3, 4, 5, 6, 7, 8, 9])

When axis is specified, values must have the correct shape.

>>> np.append([[1, 2, 3], [4, 5, 6]], [[7, 8, 9]], axis=0)
array([[1, 2, 3],
       [4, 5, 6],
       [7, 8, 9]])
>>> np.append([[1, 2, 3], [4, 5, 6]], [7, 8, 9], axis=0)
Traceback (most recent call last):
...
ValueError: arrays must have same number of dimensions


numpy.resize

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.append

Next topic

numpy.trim_zeros

numpy.resize

numpy.resize(a, new_shape) [source]

Return a new array with the specified shape.

If the new array is larger than the original array, then the new array is filled with repeated copies of a. Note that this behavior is different from a.resize(new_shape) which fills with zeros instead of repeated copies of a.

Parameters:

a : array_like

Array to be resized.

new_shape : int or tuple of int

Shape of resized array.
Returns:

reshaped_array : ndarray

The new array is formed from the data in the old array, repeated if necessary to fill out the required number of elements. The data are repeated in the order that they are stored in memory.

See also

ndarray.resize
resize an array in-place.

Examples

>>> a=np.array([[0,1],[2,3]])
>>> np.resize(a,(1,4))
array([[0, 1, 2, 3]])
>>> np.resize(a,(2,4))
array([[0, 1, 2, 3],
       [0, 1, 2, 3]])


numpy.trim_zeros

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.resize

Next topic

numpy.unique

numpy.trim_zeros

numpy.trim_zeros(filt, trim='fb') [source]

Trim the leading and/or trailing zeros from a 1-D array or sequence.

Parameters:

filt : 1-D array or sequence

Input array.

trim : str, optional

A string with ‘f’ representing trim from front and ‘b’ to trim from back. Default is ‘fb’, trim zeros from both front and back of the array.
Returns:

trimmed : 1-D array or sequence

The result of trimming the input. The input data type is preserved.

Examples

>>> a = np.array((0, 0, 0, 1, 2, 3, 0, 2, 1, 0))
>>> np.trim_zeros(a)
array([1, 2, 3, 0, 2, 1])

>>> np.trim_zeros(a, 'b')
array([0, 0, 0, 1, 2, 3, 0, 2, 1])

The input data type is preserved, list/tuple in means list/tuple out.

>>> np.trim_zeros([0, 1, 2, 0])
[1, 2]


numpy.unique

  • Set routines
  • next
  • previous

Previous topic

numpy.union1d

Next topic

numpy.in1d

numpy.unique

numpy.unique(ar, return_index=False, return_inverse=False, return_counts=False) [source]

Find the unique elements of an array.

Returns the sorted unique elements of an array. There are two optional outputs in addition to the unique elements: the indices of the input array that give the unique values, and the indices of the unique array that reconstruct the input array.

Parameters:

ar : array_like

Input array. This will be flattened if it is not already 1-D.

return_index : bool, optional

If True, also return the indices of ar that result in the unique array.

return_inverse : bool, optional

If True, also return the indices of the unique array that can be used to reconstruct ar.

return_counts : bool, optional

New in version 1.9.0.

If True, also return the number of times each unique value comes up in ar.
Returns:

unique : ndarray

The sorted unique values.

unique_indices : ndarray, optional

The indices of the first occurrences of the unique values in the (flattened) original array. Only provided if return_index is True.

unique_inverse : ndarray, optional

The indices to reconstruct the (flattened) original array from the unique array. Only provided if return_inverse is True.

unique_counts : ndarray, optional

New in version 1.9.0.

The number of times each of the unique values comes up in the original array. Only provided if return_counts is True.

See also

numpy.lib.arraysetops
Module with a number of other functions for performing set operations on arrays.

Examples

>>> np.unique([1, 1, 2, 2, 3, 3])
array([1, 2, 3])
>>> a = np.array([[1, 1], [2, 3]])
>>> np.unique(a)
array([1, 2, 3])

Return the indices of the original array that give the unique values:

>>> a = np.array(['a', 'b', 'b', 'c', 'a'])
>>> u, indices = np.unique(a, return_index=True)
>>> u
array(['a', 'b', 'c'],
       dtype='|S1')
>>> indices
array([0, 1, 3])
>>> a[indices]
array(['a', 'b', 'c'],
       dtype='|S1')

Reconstruct the input array from the unique values:

>>> a = np.array([1, 2, 6, 4, 2, 3, 2])
>>> u, indices = np.unique(a, return_inverse=True)
>>> u
array([1, 2, 3, 4, 6])
>>> indices
array([0, 1, 4, 3, 1, 2, 1])
>>> u[indices]
array([1, 2, 6, 4, 2, 3, 2])


numpy.fliplr

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.unique

Next topic

numpy.flipud

numpy.fliplr

numpy.fliplr(m) [source]

Flip array in the left/right direction.

Flip the entries in each row in the left/right direction. Columns are preserved, but appear in a different order than before.

Parameters:

m : array_like

Input array, must be at least 2-D.
Returns:

f : ndarray

A view of m with the columns reversed. Since a view is returned, this operation is [image].

See also

flipud
Flip array in the up/down direction.
rot90
Rotate array counterclockwise.

Notes

Equivalent to A[:,::-1]. Requires the array to be at least 2-D.

Examples

>>> A = np.diag([1.,2.,3.])
>>> A
array([[ 1.,  0.,  0.],
       [ 0.,  2.,  0.],
       [ 0.,  0.,  3.]])
>>> np.fliplr(A)
array([[ 0.,  0.,  1.],
       [ 0.,  2.,  0.],
       [ 3.,  0.,  0.]])

>>> A = np.random.randn(2,3,5)
>>> np.all(np.fliplr(A)==A[:,::-1,...])
True


numpy.flipud

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.fliplr

Next topic

numpy.reshape

numpy.flipud

numpy.flipud(m) [source]

Flip array in the up/down direction.

Flip the entries in each column in the up/down direction. Rows are preserved, but appear in a different order than before.

Parameters:

m : array_like

Input array.
Returns:

out : array_like

A view of m with the rows reversed. Since a view is returned, this operation is [image].

See also

fliplr
Flip array in the left/right direction.
rot90
Rotate array counterclockwise.

Notes

Equivalent to A[::-1,...]. Does not require the array to be two-dimensional.

Examples

>>> A = np.diag([1.0, 2, 3])
>>> A
array([[ 1.,  0.,  0.],
       [ 0.,  2.,  0.],
       [ 0.,  0.,  3.]])
>>> np.flipud(A)
array([[ 0.,  0.,  3.],
       [ 0.,  2.,  0.],
       [ 1.,  0.,  0.]])

>>> A = np.random.randn(2,3,5)
>>> np.all(np.flipud(A)==A[::-1,...])
True

>>> np.flipud([1,2])
array([2, 1])


numpy.roll

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.reshape

Next topic

numpy.rot90

numpy.roll

numpy.roll(a, shift, axis=None) [source]

Roll array elements along a given axis.

Elements that roll beyond the last position are re-introduced at the first.

Parameters:

a : array_like

Input array.

shift : int

The number of places by which elements are shifted.

axis : int, optional

The axis along which elements are shifted. By default, the array is flattened before shifting, after which the original shape is restored.
Returns:

res : ndarray

Output array, with the same shape as a.

See also

rollaxis
Roll the specified axis backwards, until it lies in a given position.

Examples

>>> x = np.arange(10)
>>> np.roll(x, 2)
array([8, 9, 0, 1, 2, 3, 4, 5, 6, 7])

>>> x2 = np.reshape(x, (2,5))
>>> x2
array([[0, 1, 2, 3, 4],
       [5, 6, 7, 8, 9]])
>>> np.roll(x2, 1)
array([[9, 0, 1, 2, 3],
       [4, 5, 6, 7, 8]])
>>> np.roll(x2, 1, axis=0)
array([[5, 6, 7, 8, 9],
       [0, 1, 2, 3, 4]])
>>> np.roll(x2, 1, axis=1)
array([[4, 0, 1, 2, 3],
       [9, 5, 6, 7, 8]])


numpy.rot90

  • Array manipulation routines
  • next
  • previous

Previous topic

numpy.roll

Next topic

Binary operations

numpy.rot90

numpy.rot90(m, k=1) [source]

Rotate an array by 90 degrees in the counter-clockwise direction.

The first two dimensions are rotated; therefore, the array must be at least 2-D.

Parameters:

m : array_like

Array of two or more dimensions.

k : integer

Number of times the array is rotated by 90 degrees.
Returns:

y : ndarray

Rotated array.

See also

fliplr
Flip an array horizontally.
flipud
Flip an array vertically.

Examples

>>> m = np.array([[1,2],[3,4]], int)
>>> m
array([[1, 2],
       [3, 4]])
>>> np.rot90(m)
array([[2, 4],
       [1, 3]])
>>> np.rot90(m, 2)
array([[4, 3],
       [2, 1]])


Binary operations

  • next
  • previous

Table Of Contents

  • Binary operations
    • Elementwise bit operations
    • Bit packing
    • Output formatting

Previous topic

numpy.rot90

Next topic

numpy.bitwise_and

Binary operations

Elementwise bit operations

bitwise_and(x1, x2[, out]) | Compute the bit-wise AND of two arrays element-wise.
bitwise_or(x1, x2[, out]) | Compute the bit-wise OR of two arrays element-wise.
bitwise_xor(x1, x2[, out]) | Compute the bit-wise XOR of two arrays element-wise.
invert(x[, out]) | Compute bit-wise inversion, or bit-wise NOT, element-wise.
left_shift(x1, x2[, out]) | Shift the bits of an integer to the left.
right_shift(x1, x2[, out]) | Shift the bits of an integer to the right.

Bit packing

packbits(myarray[, axis]) | Packs the elements of a binary-valued array into bits in a uint8 array.
unpackbits(myarray[, axis]) | Unpacks elements of a uint8 array into a binary-valued output array.

Output formatting

binary_repr(num[, width]) Return the binary representation of the input number as a string.


numpy.bitwise_and

  • Binary operations
  • next
  • previous

Previous topic

numpy.binary_repr

Next topic

numpy.bitwise_or

numpy.bitwise_and

numpy.bitwise_and(x1, x2[, out]) = <ufunc 'bitwise_and'>

Compute the bit-wise AND of two arrays element-wise.

Computes the bit-wise AND of the underlying binary representation of the integers in the input arrays. This ufunc implements the C/Python operator &.

Parameters:

x1, x2 : array_like

Only integer and boolean types are handled.
Returns:

out : array_like

Result.

See also

logical_and, bitwise_or, bitwise_xor

binary_repr
Return the binary representation of the input number as a string.

Examples

The number 13 is represented by 00001101. Likewise, 17 is represented by 00010001. The bit-wise AND of 13 and 17 is therefore 000000001, or 1:

>>> np.bitwise_and(13, 17)
1

>>> np.bitwise_and(14, 13)
12
>>> np.binary_repr(12)
'1100'
>>> np.bitwise_and([14,3], 13)
array([12,  1])

>>> np.bitwise_and([11,7], [4,25])
array([0, 1])
>>> np.bitwise_and(np.array([2,5,255]), np.array([3,14,16]))
array([ 2,  4, 16])
>>> np.bitwise_and([True, True], [False, True])
array([False,  True], dtype=bool)


numpy.bitwise_or

  • Binary operations
  • next
  • previous

Previous topic

numpy.bitwise_and

Next topic

numpy.bitwise_xor

numpy.bitwise_or

numpy.bitwise_or(x1, x2[, out]) = <ufunc 'bitwise_or'>

Compute the bit-wise OR of two arrays element-wise.

Computes the bit-wise OR of the underlying binary representation of the integers in the input arrays. This ufunc implements the C/Python operator |.

Parameters:

x1, x2 : array_like

Only integer and boolean types are handled.

out : ndarray, optional

Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output. See doc.ufuncs.
Returns:

out : array_like

Result.

See also

logical_or, bitwise_and, bitwise_xor

binary_repr
Return the binary representation of the input number as a string.

Examples

The number 13 has the binaray representation 00001101. Likewise, 16 is represented by 00010000. The bit-wise OR of 13 and 16 is then 000111011, or 29:

>>> np.bitwise_or(13, 16)
29
>>> np.binary_repr(29)
'11101'

>>> np.bitwise_or(32, 2)
34
>>> np.bitwise_or([33, 4], 1)
array([33,  5])
>>> np.bitwise_or([33, 4], [1, 2])
array([33,  6])

>>> np.bitwise_or(np.array([2, 5, 255]), np.array([4, 4, 4]))
array([  6,   5, 255])
>>> np.array([2, 5, 255]) | np.array([4, 4, 4])
array([  6,   5, 255])
>>> np.bitwise_or(np.array([2, 5, 255, 2147483647L], dtype=np.int32),
...               np.array([4, 4, 4, 2147483647L], dtype=np.int32))
array([         6,          5,        255, 2147483647])
>>> np.bitwise_or([True, True], [False, True])
array([ True,  True], dtype=bool)


numpy.bitwise_xor

  • Binary operations
  • next
  • previous

Previous topic

numpy.bitwise_or

Next topic

numpy.invert

numpy.bitwise_xor

numpy.bitwise_xor(x1, x2[, out]) = <ufunc 'bitwise_xor'>

Compute the bit-wise XOR of two arrays element-wise.

Computes the bit-wise XOR of the underlying binary representation of the integers in the input arrays. This ufunc implements the C/Python operator ^.

Parameters:

x1, x2 : array_like

Only integer and boolean types are handled.
Returns:

out : array_like

Result.

See also

logical_xor, bitwise_and, bitwise_or

binary_repr
Return the binary representation of the input number as a string.

Examples

The number 13 is represented by 00001101. Likewise, 17 is represented by 00010001. The bit-wise XOR of 13 and 17 is therefore 00011100, or 28:

>>> np.bitwise_xor(13, 17)
28
>>> np.binary_repr(28)
'11100'

>>> np.bitwise_xor(31, 5)
26
>>> np.bitwise_xor([31,3], 5)
array([26,  6])

>>> np.bitwise_xor([31,3], [5,6])
array([26,  5])
>>> np.bitwise_xor([True, True], [False, True])
array([ True, False], dtype=bool)


numpy.invert

  • Binary operations
  • next
  • previous

Previous topic

numpy.bitwise_xor

Next topic

numpy.left_shift

numpy.invert

numpy.invert(x[, out]) = <ufunc 'invert'>

Compute bit-wise inversion, or bit-wise NOT, element-wise.

Computes the bit-wise NOT of the underlying binary representation of the integers in the input arrays. This ufunc implements the C/Python operator ~.

For signed integer inputs, the two’s complement is returned. In a two’s-complement system negative numbers are represented by the two’s complement of the absolute value. This is the most common method of representing signed integers on computers [R32]. A N-bit two’s-complement system can represent every integer in the range [image] to [image].

Parameters:

x1 : array_like

Only integer and boolean types are handled.
Returns:

out : array_like

Result.

See also

bitwise_and, bitwise_or, bitwise_xor, logical_not

binary_repr
Return the binary representation of the input number as a string.

Notes

bitwise_not is an alias for invert:

>>> np.bitwise_not is np.invert
True

References

[R32] (1, 2) Wikipedia, “Two’s complement”, http://en.wikipedia.org/wiki/Two’s_complement

Examples

We’ve seen that 13 is represented by 00001101. The invert or bit-wise NOT of 13 is then:

>>> np.invert(np.array([13], dtype=uint8))
array([242], dtype=uint8)
>>> np.binary_repr(x, width=8)
'00001101'
>>> np.binary_repr(242, width=8)
'11110010'

The result depends on the bit-width:

>>> np.invert(np.array([13], dtype=uint16))
array([65522], dtype=uint16)
>>> np.binary_repr(x, width=16)
'0000000000001101'
>>> np.binary_repr(65522, width=16)
'1111111111110010'

When using signed integer types the result is the two’s complement of the result for the unsigned type:

>>> np.invert(np.array([13], dtype=int8))
array([-14], dtype=int8)
>>> np.binary_repr(-14, width=8)
'11110010'

Booleans are accepted as well:

>>> np.invert(array([True, False]))
array([False,  True], dtype=bool)


numpy.left_shift

  • Binary operations
  • next
  • previous

Previous topic

numpy.invert

Next topic

numpy.right_shift

numpy.left_shift

numpy.left_shift(x1, x2[, out]) = <ufunc 'left_shift'>

Shift the bits of an integer to the left.

Bits are shifted to the left by appending x2 0s at the right of x1. Since the internal representation of numbers is in binary format, this operation is equivalent to multiplying x1 by 2**x2.

Parameters:

x1 : array_like of integer type

Input values.

x2 : array_like of integer type

Number of zeros to append to x1. Has to be non-negative.
Returns:

out : array of integer type

Return x1 with bits shifted x2 times to the left.

See also

right_shift
Shift the bits of an integer to the right.
binary_repr
Return the binary representation of the input number as a string.

Examples

>>> np.binary_repr(5)
'101'
>>> np.left_shift(5, 2)
20
>>> np.binary_repr(20)
'10100'

>>> np.left_shift(5, [1,2,3])
array([10, 20, 40])


numpy.right_shift

  • Binary operations
  • next
  • previous

Previous topic

numpy.left_shift

Next topic

numpy.packbits

numpy.right_shift

numpy.right_shift(x1, x2[, out]) = <ufunc 'right_shift'>

Shift the bits of an integer to the right.

Bits are shifted to the right x2. Because the internal representation of numbers is in binary format, this operation is equivalent to dividing x1 by 2**x2.

Parameters:

x1 : array_like, int

Input values.

x2 : array_like, int

Number of bits to remove at the right of x1.
Returns:

out : ndarray, int

Return x1 with bits shifted x2 times to the right.

See also

left_shift
Shift the bits of an integer to the left.
binary_repr
Return the binary representation of the input number as a string.

Examples

>>> np.binary_repr(10)
'1010'
>>> np.right_shift(10, 1)
5
>>> np.binary_repr(5)
'101'

>>> np.right_shift(10, [1,2,3])
array([5, 2, 1])


numpy.packbits

  • Binary operations
  • next
  • previous

Previous topic

numpy.right_shift

Next topic

numpy.unpackbits

numpy.packbits

numpy.packbits(myarray, axis=None)

Packs the elements of a binary-valued array into bits in a uint8 array.

The result is padded to full bytes by inserting zero bits at the end.

Parameters:

myarray : array_like

An integer type array whose elements should be packed to bits.

axis : int, optional

The dimension over which bit-packing is done. None implies packing the flattened array.
Returns:

packed : ndarray

Array of type uint8 whose elements represent bits corresponding to the logical (0 or nonzero) value of the input elements. The shape of packed has the same number of dimensions as the input (unless axis is None, in which case the output is 1-D).

See also

unpackbits
Unpacks elements of a uint8 array into a binary-valued output array.

Examples

>>> a = np.array([[[1,0,1],
...                [0,1,0]],
...               [[1,1,0],
...                [0,0,1]]])
>>> b = np.packbits(a, axis=-1)
>>> b
array([[[160],[64]],[[192],[32]]], dtype=uint8)

Note that in binary 160 = 1010 0000, 64 = 0100 0000, 192 = 1100 0000, and 32 = 0010 0000.


numpy.unpackbits

  • Binary operations
  • next
  • previous

Previous topic

numpy.packbits

Next topic

numpy.binary_repr

numpy.unpackbits

numpy.unpackbits(myarray, axis=None)

Unpacks elements of a uint8 array into a binary-valued output array.

Each element of myarray represents a bit-field that should be unpacked into a binary-valued output array. The shape of the output array is either 1-D (if axis is None) or the same shape as the input array with unpacking done along the axis specified.

Parameters:

myarray : ndarray, uint8 type

Input array.

axis : int, optional

Unpacks along this axis.
Returns:

unpacked : ndarray, uint8 type

The elements are binary-valued (0 or 1).

See also

packbits
Packs the elements of a binary-valued array into bits in a uint8 array.

Examples

>>> a = np.array([[2], [7], [23]], dtype=np.uint8)
>>> a
array([[ 2],
       [ 7],
       [23]], dtype=uint8)
>>> b = np.unpackbits(a, axis=1)
>>> b
array([[0, 0, 0, 0, 0, 0, 1, 0],
       [0, 0, 0, 0, 0, 1, 1, 1],
       [0, 0, 0, 1, 0, 1, 1, 1]], dtype=uint8)


numpy.binary_repr

  • Input and output
  • next
  • previous

Previous topic

numpy.set_string_function

Next topic

numpy.base_repr

numpy.binary_repr

numpy.binary_repr(num, width=None) [source]

Return the binary representation of the input number as a string.

For negative numbers, if width is not given, a minus sign is added to the front. If width is given, the two’s complement of the number is returned, with respect to that width.

In a two’s-complement system negative numbers are represented by the two’s complement of the absolute value. This is the most common method of representing signed integers on computers [R16]. A N-bit two’s-complement system can represent every integer in the range [image] to [image].

Parameters:

num : int

Only an integer decimal number can be used.

width : int, optional

The length of the returned string if num is positive, the length of the two’s complement if num is negative.
Returns:

bin : str

Binary representation of num or two’s complement of num.

See also

base_repr
Return a string representation of a number in the given base system.

Notes

binary_repr is equivalent to using base_repr with base 2, but about 25x faster.

References

[R16] (1, 2) Wikipedia, “Two’s complement”, http://en.wikipedia.org/wiki/Two’s_complement

Examples

>>> np.binary_repr(3)
'11'
>>> np.binary_repr(-3)
'-11'
>>> np.binary_repr(3, width=4)
'0011'

The two’s complement is returned when the input number is negative and width is specified:

>>> np.binary_repr(-3, width=4)
'1101'


String operations

  • next
  • previous

Table Of Contents

  • String operations
    • String operations
    • Comparison
    • String information
    • Convenience class

Previous topic

numpy.binary_repr

Next topic

numpy.core.defchararray.add

String operations

This module provides a set of vectorized string operations for arrays of type numpy.string_ or numpy.unicode_. All of them are based on the string methods in the Python standard library.

String operations

add(x1, x2) | Return element-wise string concatenation for two arrays of str or unicode.
multiply(a, i) | Return (a * i), that is string multiple concatenation, element-wise.
mod(a, values) | Return (a % i), that is pre-Python 2.6 string formatting (iterpolation), element-wise for a pair of array_likes of str or unicode.
capitalize(a) | Return a copy of a with only the first character of each element capitalized.
center(a, width[, fillchar]) | Return a copy of a with its elements centered in a string of length width.
decode(a[, encoding, errors]) | Calls str.decode element-wise.
encode(a[, encoding, errors]) | Calls str.encode element-wise.
join(sep, seq) | Return a string which is the concatenation of the strings in the sequence seq.
ljust(a, width[, fillchar]) | Return an array with the elements of a left-justified in a string of length width.
lower(a) | Return an array with the elements converted to lowercase.
lstrip(a[, chars]) | For each element in a, return a copy with the leading characters removed.
partition(a, sep) | Partition each element in a around sep.
replace(a, old, new[, count]) | For each element in a, return a copy of the string with all occurrences of substring old replaced by new.
rjust(a, width[, fillchar]) | Return an array with the elements of a right-justified in a string of length width.
rpartition(a, sep) | Partition (split) each element around the right-most separator.
rsplit(a[, sep, maxsplit]) | For each element in a, return a list of the words in the string, using sep as the delimiter string.
rstrip(a[, chars]) | For each element in a, return a copy with the trailing characters removed.
split(a[, sep, maxsplit]) | For each element in a, return a list of the words in the string, using sep as the delimiter string.
splitlines(a[, keepends]) | For each element in a, return a list of the lines in the element, breaking at line boundaries.
strip(a[, chars]) | For each element in a, return a copy with the leading and trailing characters removed.
swapcase(a) | Return element-wise a copy of the string with uppercase characters converted to lowercase and vice versa.
title(a) | Return element-wise title cased version of string or unicode.
translate(a, table[, deletechars]) | For each element in a, return a copy of the string where all characters occurring in the optional argument deletechars are removed, and the remaining characters have been mapped through the given translation table.
upper(a) | Return an array with the elements converted to uppercase.
zfill(a, width) | Return the numeric string left-filled with zeros

Comparison

Unlike the standard numpy comparison operators, the ones in the char module strip trailing whitespace characters before performing the comparison.

equal(x1, x2) | Return (x1 == x2) element-wise.
not_equal(x1, x2) | Return (x1 != x2) element-wise.
greater_equal(x1, x2) | Return (x1 >= x2) element-wise.
less_equal(x1, x2) | Return (x1 <= x2) element-wise.
greater(x1, x2) | Return (x1 > x2) element-wise.
less(x1, x2) | Return (x1 < x2) element-wise.

String information

count(a, sub[, start, end]) | Returns an array with the number of non-overlapping occurrences of substring sub in the range [start, end].
find(a, sub[, start, end]) | For each element, return the lowest index in the string where substring sub is found.
index(a, sub[, start, end]) | Like find, but raises ValueError when the substring is not found.
isalpha(a) | Returns true for each element if all characters in the string are alphabetic and there is at least one character, false otherwise.
isdecimal(a) | For each element, return True if there are only decimal characters in the element.
isdigit(a) | Returns true for each element if all characters in the string are digits and there is at least one character, false otherwise.
islower(a) | Returns true for each element if all cased characters in the string are lowercase and there is at least one cased character, false otherwise.
isnumeric(a) | For each element, return True if there are only numeric characters in the element.
isspace(a) | Returns true for each element if there are only whitespace characters in the string and there is at least one character, false otherwise.
istitle(a) | Returns true for each element if the element is a titlecased string and there is at least one character, false otherwise.
isupper(a) | Returns true for each element if all cased characters in the string are uppercase and there is at least one character, false otherwise.
rfind(a, sub[, start, end]) | For each element in a, return the highest index in the string where substring sub is found, such that sub is contained within [start, end].
rindex(a, sub[, start, end]) | Like rfind, but raises ValueError when the substring sub is not found.
startswith(a, prefix[, start, end]) | Returns a boolean array which is True where the string element in a starts with prefix, otherwise False.

Convenience class

chararray Provides a convenient view on arrays of string and unicode values.


numpy.core.defchararray.add

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.zfill

Next topic

numpy.core.defchararray.multiply

numpy.core.defchararray.add

numpy.core.defchararray.add(x1, x2) [source]

Return element-wise string concatenation for two arrays of str or unicode.

Arrays x1 and x2 must have the same shape.

Parameters:

x1 : array_like of str or unicode

Input array.

x2 : array_like of str or unicode

Input array.
Returns:

add : ndarray

Output array of string_ or unicode_, depending on input types of the same shape as x1 and x2.


numpy.core.defchararray.multiply

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.add

Next topic

numpy.core.defchararray.mod

numpy.core.defchararray.multiply

numpy.core.defchararray.multiply(a, i) [source]

Return (a * i), that is string multiple concatenation, element-wise.

Values in i of less than 0 are treated as 0 (which yields an empty string).

Parameters:

a : array_like of str or unicode

i : array_like of ints
Returns:

out : ndarray

Output array of str or unicode, depending on input types


numpy.core.defchararray.mod

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.multiply

Next topic

numpy.core.defchararray.capitalize

numpy.core.defchararray.mod

numpy.core.defchararray.mod(a, values) [source]

Return (a % i), that is pre-Python 2.6 string formatting (iterpolation), element-wise for a pair of array_likes of str or unicode.

Parameters:

a : array_like of str or unicode

values : array_like of values

These values will be element-wise interpolated into the string.
Returns:

out : ndarray

Output array of str or unicode, depending on input types

See also

str.__mod__


numpy.core.defchararray.capitalize

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.mod

Next topic

numpy.core.defchararray.center

numpy.core.defchararray.capitalize

numpy.core.defchararray.capitalize(a) [source]

Return a copy of a with only the first character of each element capitalized.

Calls str.capitalize element-wise.

For 8-bit strings, this method is locale-dependent.

Parameters:

a : array_like of str or unicode

Input array of strings to capitalize.
Returns:

out : ndarray

Output array of str or unicode, depending on input types

See also

str.capitalize

Examples

>>> c = np.array(['a1b2','1b2a','b2a1','2a1b'],'S4'); c
array(['a1b2', '1b2a', 'b2a1', '2a1b'],
    dtype='|S4')
>>> np.char.capitalize(c)
array(['A1b2', '1b2a', 'B2a1', '2a1b'],
    dtype='|S4')


numpy.core.defchararray.center

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.capitalize

Next topic

numpy.core.defchararray.decode

numpy.core.defchararray.center

numpy.core.defchararray.center(a, width, fillchar=' ') [source]

Return a copy of a with its elements centered in a string of length width.

Calls str.center element-wise.

Parameters:

a : array_like of str or unicode

width : int

The length of the resulting strings

fillchar : str or unicode, optional

The padding character to use (default is space).
Returns:

out : ndarray

Output array of str or unicode, depending on input types

See also

str.center


numpy.core.defchararray.decode

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.center

Next topic

numpy.core.defchararray.encode

numpy.core.defchararray.decode

numpy.core.defchararray.decode(a, encoding=None, errors=None) [source]

Calls str.decode element-wise.

The set of available codecs comes from the Python standard library, and may be extended at runtime. For more information, see the codecs module.

Parameters:

a : array_like of str or unicode

encoding : str, optional

The name of an encoding

errors : str, optional

Specifies how to handle encoding errors
Returns:

out : ndarray

See also

str.decode

Notes

The type of the result will depend on the encoding specified.

Examples

>>> c = np.array(['aAaAaA', '  aA  ', 'abBABba'])
>>> c
array(['aAaAaA', '  aA  ', 'abBABba'],
    dtype='|S7')
>>> np.char.encode(c, encoding='cp037')
array(['\x81\xc1\x81\xc1\x81\xc1', '@@\x81\xc1@@',
    '\x81\x82\xc2\xc1\xc2\x82\x81'],
    dtype='|S7')


numpy.core.defchararray.encode

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.decode

Next topic

numpy.core.defchararray.join

numpy.core.defchararray.encode

numpy.core.defchararray.encode(a, encoding=None, errors=None) [source]

Calls str.encode element-wise.

The set of available codecs comes from the Python standard library, and may be extended at runtime. For more information, see the codecs module.

Parameters:

a : array_like of str or unicode

encoding : str, optional

The name of an encoding

errors : str, optional

Specifies how to handle encoding errors
Returns:

out : ndarray

See also

str.encode

Notes

The type of the result will depend on the encoding specified.


numpy.core.defchararray.join

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.encode

Next topic

numpy.core.defchararray.ljust

numpy.core.defchararray.join

numpy.core.defchararray.join(sep, seq) [source]

Return a string which is the concatenation of the strings in the sequence seq.

Calls str.join element-wise.

Parameters:

sep : array_like of str or unicode

seq : array_like of str or unicode
Returns:

out : ndarray

Output array of str or unicode, depending on input types

See also

str.join


numpy.core.defchararray.ljust

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.join

Next topic

numpy.core.defchararray.lower

numpy.core.defchararray.ljust

numpy.core.defchararray.ljust(a, width, fillchar=' ') [source]

Return an array with the elements of a left-justified in a string of length width.

Calls str.ljust element-wise.

Parameters:

a : array_like of str or unicode

width : int

The length of the resulting strings

fillchar : str or unicode, optional

The character to use for padding
Returns:

out : ndarray

Output array of str or unicode, depending on input type

See also

str.ljust


numpy.core.defchararray.lower

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.ljust

Next topic

numpy.core.defchararray.lstrip

numpy.core.defchararray.lower

numpy.core.defchararray.lower(a) [source]

Return an array with the elements converted to lowercase.

Call str.lower element-wise.

For 8-bit strings, this method is locale-dependent.

Parameters:

a : array_like, {str, unicode}

Input array.
Returns:

out : ndarray, {str, unicode}

Output array of str or unicode, depending on input type

See also

str.lower

Examples

>>> c = np.array(['A1B C', '1BCA', 'BCA1']); c
array(['A1B C', '1BCA', 'BCA1'],
      dtype='|S5')
>>> np.char.lower(c)
array(['a1b c', '1bca', 'bca1'],
      dtype='|S5')


numpy.core.defchararray.lstrip

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.lower

Next topic

numpy.core.defchararray.partition

numpy.core.defchararray.lstrip

numpy.core.defchararray.lstrip(a, chars=None) [source]

For each element in a, return a copy with the leading characters removed.

Calls str.lstrip element-wise.

Parameters:

a : array-like, {str, unicode}

Input array.

chars : {str, unicode}, optional

The chars argument is a string specifying the set of characters to be removed. If omitted or None, the chars argument defaults to removing whitespace. The chars argument is not a prefix; rather, all combinations of its values are stripped.
Returns:

out : ndarray, {str, unicode}

Output array of str or unicode, depending on input type

See also

str.lstrip

Examples

>>> c = np.array(['aAaAaA', '  aA  ', 'abBABba'])
>>> c
array(['aAaAaA', '  aA  ', 'abBABba'],
    dtype='|S7')

The ‘a’ variable is unstripped from c[1] because whitespace leading.

>>> np.char.lstrip(c, 'a')
array(['AaAaA', '  aA  ', 'bBABba'],
    dtype='|S7')

>>> np.char.lstrip(c, 'A') # leaves c unchanged
array(['aAaAaA', '  aA  ', 'abBABba'],
    dtype='|S7')
>>> (np.char.lstrip(c, ' ') == np.char.lstrip(c, '')).all()
... # XXX: is this a regression? this line now returns False
... # np.char.lstrip(c,'') does not modify c at all.
True
>>> (np.char.lstrip(c, ' ') == np.char.lstrip(c, None)).all()
True


numpy.core.defchararray.partition

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.lstrip

Next topic

numpy.core.defchararray.replace

numpy.core.defchararray.partition

numpy.core.defchararray.partition(a, sep) [source]

Partition each element in a around sep.

Calls str.partition element-wise.

For each element in a, split the element as the first occurrence of sep, and return 3 strings containing the part before the separator, the separator itself, and the part after the separator. If the separator is not found, return 3 strings containing the string itself, followed by two empty strings.

Parameters:

a : array_like, {str, unicode}

Input array

sep : {str, unicode}

Separator to split each string element in a.
Returns:

out : ndarray, {str, unicode}

Output array of str or unicode, depending on input type. The output array will have an extra dimension with 3 elements per input element.

See also

str.partition


numpy.core.defchararray.replace

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.partition

Next topic

numpy.core.defchararray.rjust

numpy.core.defchararray.replace

numpy.core.defchararray.replace(a, old, new, count=None) [source]

For each element in a, return a copy of the string with all occurrences of substring old replaced by new.

Calls str.replace element-wise.

Parameters:

a : array-like of str or unicode

old, new : str or unicode

count : int, optional

If the optional argument count is given, only the first count occurrences are replaced.
Returns:

out : ndarray

Output array of str or unicode, depending on input type

See also

str.replace


numpy.core.defchararray.rjust

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.replace

Next topic

numpy.core.defchararray.rpartition

numpy.core.defchararray.rjust

numpy.core.defchararray.rjust(a, width, fillchar=' ') [source]

Return an array with the elements of a right-justified in a string of length width.

Calls str.rjust element-wise.

Parameters:

a : array_like of str or unicode

width : int

The length of the resulting strings

fillchar : str or unicode, optional

The character to use for padding
Returns:

out : ndarray

Output array of str or unicode, depending on input type

See also

str.rjust


numpy.core.defchararray.rpartition

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.rjust

Next topic

numpy.core.defchararray.rsplit

numpy.core.defchararray.rpartition

numpy.core.defchararray.rpartition(a, sep) [source]

Partition (split) each element around the right-most separator.

Calls str.rpartition element-wise.

For each element in a, split the element as the last occurrence of sep, and return 3 strings containing the part before the separator, the separator itself, and the part after the separator. If the separator is not found, return 3 strings containing the string itself, followed by two empty strings.

Parameters:

a : array_like of str or unicode

Input array

sep : str or unicode

Right-most separator to split each element in array.
Returns:

out : ndarray

Output array of string or unicode, depending on input type. The output array will have an extra dimension with 3 elements per input element.

See also

str.rpartition


numpy.core.defchararray.rsplit

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.rpartition

Next topic

numpy.core.defchararray.rstrip

numpy.core.defchararray.rsplit

numpy.core.defchararray.rsplit(a, sep=None, maxsplit=None) [source]

For each element in a, return a list of the words in the string, using sep as the delimiter string.

Calls str.rsplit element-wise.

Except for splitting from the right, rsplit behaves like split.

Parameters:

a : array_like of str or unicode

sep : str or unicode, optional

If sep is not specified or None, any whitespace string is a separator.

maxsplit : int, optional

If maxsplit is given, at most maxsplit splits are done, the rightmost ones.
Returns:

out : ndarray

Array of list objects

See also

str.rsplit, split


numpy.core.defchararray.rstrip

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.rsplit

Next topic

numpy.core.defchararray.split

numpy.core.defchararray.rstrip

numpy.core.defchararray.rstrip(a, chars=None) [source]

For each element in a, return a copy with the trailing characters removed.

Calls str.rstrip element-wise.

Parameters:

a : array-like of str or unicode

chars : str or unicode, optional

The chars argument is a string specifying the set of characters to be removed. If omitted or None, the chars argument defaults to removing whitespace. The chars argument is not a suffix; rather, all combinations of its values are stripped.
Returns:

out : ndarray

Output array of str or unicode, depending on input type

See also

str.rstrip

Examples

>>> c = np.array(['aAaAaA', 'abBABba'], dtype='S7'); c
array(['aAaAaA', 'abBABba'],
    dtype='|S7')
>>> np.char.rstrip(c, 'a')
array(['aAaAaA', 'abBABb'],
    dtype='|S7')
>>> np.char.rstrip(c, 'A')
array(['aAaAa', 'abBABba'],
    dtype='|S7')


numpy.core.defchararray.split

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.rstrip

Next topic

numpy.core.defchararray.splitlines

numpy.core.defchararray.split

numpy.core.defchararray.split(a, sep=None, maxsplit=None) [source]

For each element in a, return a list of the words in the string, using sep as the delimiter string.

Calls str.rsplit element-wise.

Parameters:

a : array_like of str or unicode

sep : str or unicode, optional

If sep is not specified or None, any whitespace string is a separator.

maxsplit : int, optional

If maxsplit is given, at most maxsplit splits are done.
Returns:

out : ndarray

Array of list objects

See also

str.split, rsplit


numpy.core.defchararray.splitlines

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.split

Next topic

numpy.core.defchararray.strip

numpy.core.defchararray.splitlines

numpy.core.defchararray.splitlines(a, keepends=None) [source]

For each element in a, return a list of the lines in the element, breaking at line boundaries.

Calls str.splitlines element-wise.

Parameters:

a : array_like of str or unicode

keepends : bool, optional

Line breaks are not included in the resulting list unless keepends is given and true.
Returns:

out : ndarray

Array of list objects

See also

str.splitlines


numpy.core.defchararray.strip

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.splitlines

Next topic

numpy.core.defchararray.swapcase

numpy.core.defchararray.strip

numpy.core.defchararray.strip(a, chars=None) [source]

For each element in a, return a copy with the leading and trailing characters removed.

Calls str.rstrip element-wise.

Parameters:

a : array-like of str or unicode

chars : str or unicode, optional

The chars argument is a string specifying the set of characters to be removed. If omitted or None, the chars argument defaults to removing whitespace. The chars argument is not a prefix or suffix; rather, all combinations of its values are stripped.
Returns:

out : ndarray

Output array of str or unicode, depending on input type

See also

str.strip

Examples

>>> c = np.array(['aAaAaA', '  aA  ', 'abBABba'])
>>> c
array(['aAaAaA', '  aA  ', 'abBABba'],
    dtype='|S7')
>>> np.char.strip(c)
array(['aAaAaA', 'aA', 'abBABba'],
    dtype='|S7')
>>> np.char.strip(c, 'a') # 'a' unstripped from c[1] because whitespace leads
array(['AaAaA', '  aA  ', 'bBABb'],
    dtype='|S7')
>>> np.char.strip(c, 'A') # 'A' unstripped from c[1] because (unprinted) ws trails
array(['aAaAa', '  aA  ', 'abBABba'],
    dtype='|S7')


numpy.core.defchararray.swapcase

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.strip

Next topic

numpy.core.defchararray.title

numpy.core.defchararray.swapcase

numpy.core.defchararray.swapcase(a) [source]

Return element-wise a copy of the string with uppercase characters converted to lowercase and vice versa.

Calls str.swapcase element-wise.

For 8-bit strings, this method is locale-dependent.

Parameters:

a : array_like, {str, unicode}

Input array.
Returns:

out : ndarray, {str, unicode}

Output array of str or unicode, depending on input type

See also

str.swapcase

Examples

>>> c=np.array(['a1B c','1b Ca','b Ca1','cA1b'],'S5'); c
array(['a1B c', '1b Ca', 'b Ca1', 'cA1b'],
    dtype='|S5')
>>> np.char.swapcase(c)
array(['A1b C', '1B cA', 'B cA1', 'Ca1B'],
    dtype='|S5')


numpy.core.defchararray.title

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.swapcase

Next topic

numpy.core.defchararray.translate

numpy.core.defchararray.title

numpy.core.defchararray.title(a) [source]

Return element-wise title cased version of string or unicode.

Title case words start with uppercase characters, all remaining cased characters are lowercase.

Calls str.title element-wise.

For 8-bit strings, this method is locale-dependent.

Parameters:

a : array_like, {str, unicode}

Input array.
Returns:

out : ndarray

Output array of str or unicode, depending on input type

See also

str.title

Examples

>>> c=np.array(['a1b c','1b ca','b ca1','ca1b'],'S5'); c
array(['a1b c', '1b ca', 'b ca1', 'ca1b'],
    dtype='|S5')
>>> np.char.title(c)
array(['A1B C', '1B Ca', 'B Ca1', 'Ca1B'],
    dtype='|S5')


numpy.core.defchararray.translate

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.title

Next topic

numpy.core.defchararray.upper

numpy.core.defchararray.translate

numpy.core.defchararray.translate(a, table, deletechars=None) [source]

For each element in a, return a copy of the string where all characters occurring in the optional argument deletechars are removed, and the remaining characters have been mapped through the given translation table.

Calls str.translate element-wise.

Parameters:

a : array-like of str or unicode

table : str of length 256

deletechars : str
Returns:

out : ndarray

Output array of str or unicode, depending on input type

See also

str.translate


numpy.core.defchararray.upper

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.translate

Next topic

numpy.core.defchararray.zfill

numpy.core.defchararray.upper

numpy.core.defchararray.upper(a) [source]

Return an array with the elements converted to uppercase.

Calls str.upper element-wise.

For 8-bit strings, this method is locale-dependent.

Parameters:

a : array_like, {str, unicode}

Input array.
Returns:

out : ndarray, {str, unicode}

Output array of str or unicode, depending on input type

See also

str.upper

Examples

>>> c = np.array(['a1b c', '1bca', 'bca1']); c
array(['a1b c', '1bca', 'bca1'],
    dtype='|S5')
>>> np.char.upper(c)
array(['A1B C', '1BCA', 'BCA1'],
    dtype='|S5')


numpy.core.defchararray.zfill

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.upper

Next topic

numpy.core.defchararray.equal

numpy.core.defchararray.zfill

numpy.core.defchararray.zfill(a, width) [source]

Return the numeric string left-filled with zeros

Calls str.zfill element-wise.

Parameters:

a : array_like, {str, unicode}

Input array.

width : int

Width of string to left-fill elements in a.
Returns:

out : ndarray, {str, unicode}

Output array of str or unicode, depending on input type

See also

str.zfill


numpy.core.defchararray.equal

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.zfill

Next topic

numpy.core.defchararray.not_equal

numpy.core.defchararray.equal

numpy.core.defchararray.equal(x1, x2) [source]

Return (x1 == x2) element-wise.

Unlike numpy.equal, this comparison is performed by first stripping whitespace characters from the end of the string. This behavior is provided for backward-compatibility with numarray.

Parameters:

x1, x2 : array_like of str or unicode

Input arrays of the same shape.
Returns:

out : {ndarray, bool}

Output array of bools, or a single bool if x1 and x2 are scalars.

See also

not_equal, greater_equal, less_equal, greater, less


numpy.core.defchararray.not_equal

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.equal

Next topic

numpy.core.defchararray.greater_equal

numpy.core.defchararray.not_equal

numpy.core.defchararray.not_equal(x1, x2) [source]

Return (x1 != x2) element-wise.

Unlike numpy.not_equal, this comparison is performed by first stripping whitespace characters from the end of the string. This behavior is provided for backward-compatibility with numarray.

Parameters:

x1, x2 : array_like of str or unicode

Input arrays of the same shape.
Returns:

out : {ndarray, bool}

Output array of bools, or a single bool if x1 and x2 are scalars.

See also

equal, greater_equal, less_equal, greater, less


numpy.core.defchararray.greater_equal

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.not_equal

Next topic

numpy.core.defchararray.less_equal

numpy.core.defchararray.greater_equal

numpy.core.defchararray.greater_equal(x1, x2) [source]

Return (x1 >= x2) element-wise.

Unlike numpy.greater_equal, this comparison is performed by first stripping whitespace characters from the end of the string. This behavior is provided for backward-compatibility with numarray.

Parameters:

x1, x2 : array_like of str or unicode

Input arrays of the same shape.
Returns:

out : {ndarray, bool}

Output array of bools, or a single bool if x1 and x2 are scalars.

See also

equal, not_equal, less_equal, greater, less


numpy.core.defchararray.less_equal

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.greater_equal

Next topic

numpy.core.defchararray.greater

numpy.core.defchararray.less_equal

numpy.core.defchararray.less_equal(x1, x2) [source]

Return (x1 <= x2) element-wise.

Unlike numpy.less_equal, this comparison is performed by first stripping whitespace characters from the end of the string. This behavior is provided for backward-compatibility with numarray.

Parameters:

x1, x2 : array_like of str or unicode

Input arrays of the same shape.
Returns:

out : {ndarray, bool}

Output array of bools, or a single bool if x1 and x2 are scalars.

See also

equal, not_equal, greater_equal, greater, less


numpy.core.defchararray.greater

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.less_equal

Next topic

numpy.core.defchararray.less

numpy.core.defchararray.greater

numpy.core.defchararray.greater(x1, x2) [source]

Return (x1 > x2) element-wise.

Unlike numpy.greater, this comparison is performed by first stripping whitespace characters from the end of the string. This behavior is provided for backward-compatibility with numarray.

Parameters:

x1, x2 : array_like of str or unicode

Input arrays of the same shape.
Returns:

out : {ndarray, bool}

Output array of bools, or a single bool if x1 and x2 are scalars.

See also

equal, not_equal, greater_equal, less_equal, less


numpy.core.defchararray.less

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.greater

Next topic

numpy.core.defchararray.count

numpy.core.defchararray.less

numpy.core.defchararray.less(x1, x2) [source]

Return (x1 < x2) element-wise.

Unlike numpy.greater, this comparison is performed by first stripping whitespace characters from the end of the string. This behavior is provided for backward-compatibility with numarray.

Parameters:

x1, x2 : array_like of str or unicode

Input arrays of the same shape.
Returns:

out : {ndarray, bool}

Output array of bools, or a single bool if x1 and x2 are scalars.

See also

equal, not_equal, greater_equal, less_equal, greater


numpy.core.defchararray.count

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.less

Next topic

numpy.core.defchararray.find

numpy.core.defchararray.count

numpy.core.defchararray.count(a, sub, start=0, end=None) [source]

Returns an array with the number of non-overlapping occurrences of substring sub in the range [start, end].

Calls str.count element-wise.

Parameters:

a : array_like of str or unicode

sub : str or unicode

The substring to search for.

start, end : int, optional

Optional arguments start and end are interpreted as slice notation to specify the range in which to count.
Returns:

out : ndarray

Output array of ints.

See also

str.count

Examples

>>> c = np.array(['aAaAaA', '  aA  ', 'abBABba'])
>>> c
array(['aAaAaA', '  aA  ', 'abBABba'],
    dtype='|S7')
>>> np.char.count(c, 'A')
array([3, 1, 1])
>>> np.char.count(c, 'aA')
array([3, 1, 0])
>>> np.char.count(c, 'A', start=1, end=4)
array([2, 1, 1])
>>> np.char.count(c, 'A', start=1, end=3)
array([1, 0, 0])


numpy.core.defchararray.find

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.count

Next topic

numpy.core.defchararray.index

numpy.core.defchararray.find

numpy.core.defchararray.find(a, sub, start=0, end=None) [source]

For each element, return the lowest index in the string where substring sub is found.

Calls str.find element-wise.

For each element, return the lowest index in the string where substring sub is found, such that sub is contained in the range [start, end].

Parameters:

a : array_like of str or unicode

sub : str or unicode

start, end : int, optional

Optional arguments start and end are interpreted as in slice notation.
Returns:

out : ndarray or int

Output array of ints. Returns -1 if sub is not found.

See also

str.find


numpy.core.defchararray.index

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.find

Next topic

numpy.core.defchararray.isalpha

numpy.core.defchararray.index

numpy.core.defchararray.index(a, sub, start=0, end=None) [source]

Like find, but raises ValueError when the substring is not found.

Calls str.index element-wise.

Parameters:

a : array_like of str or unicode

sub : str or unicode

start, end : int, optional
Returns:

out : ndarray

Output array of ints. Returns -1 if sub is not found.

See also

find, str.find


numpy.core.defchararray.isalpha

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.index

Next topic

numpy.core.defchararray.isdecimal

numpy.core.defchararray.isalpha

numpy.core.defchararray.isalpha(a) [source]

Returns true for each element if all characters in the string are alphabetic and there is at least one character, false otherwise.

Calls str.isalpha element-wise.

For 8-bit strings, this method is locale-dependent.

Parameters:

a : array_like of str or unicode
Returns:

out : ndarray

Output array of bools

See also

str.isalpha


numpy.core.defchararray.isdecimal

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.isalpha

Next topic

numpy.core.defchararray.isdigit

numpy.core.defchararray.isdecimal

numpy.core.defchararray.isdecimal(a) [source]

For each element, return True if there are only decimal characters in the element.

Calls unicode.isdecimal element-wise.

Decimal characters include digit characters, and all characters that that can be used to form decimal-radix numbers, e.g. U+0660, ARABIC-INDIC DIGIT ZERO.

Parameters:

a : array_like, unicode

Input array.
Returns:

out : ndarray, bool

Array of booleans identical in shape to a.

See also

unicode.isdecimal


numpy.core.defchararray.isdigit

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.isdecimal

Next topic

numpy.core.defchararray.islower

numpy.core.defchararray.isdigit

numpy.core.defchararray.isdigit(a) [source]

Returns true for each element if all characters in the string are digits and there is at least one character, false otherwise.

Calls str.isdigit element-wise.

For 8-bit strings, this method is locale-dependent.

Parameters:

a : array_like of str or unicode
Returns:

out : ndarray

Output array of bools

See also

str.isdigit


numpy.core.defchararray.islower

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.isdigit

Next topic

numpy.core.defchararray.isnumeric

numpy.core.defchararray.islower

numpy.core.defchararray.islower(a) [source]

Returns true for each element if all cased characters in the string are lowercase and there is at least one cased character, false otherwise.

Calls str.islower element-wise.

For 8-bit strings, this method is locale-dependent.

Parameters:

a : array_like of str or unicode
Returns:

out : ndarray

Output array of bools

See also

str.islower


numpy.core.defchararray.isnumeric

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.islower

Next topic

numpy.core.defchararray.isspace

numpy.core.defchararray.isnumeric

numpy.core.defchararray.isnumeric(a) [source]

For each element, return True if there are only numeric characters in the element.

Calls unicode.isnumeric element-wise.

Numeric characters include digit characters, and all characters that have the Unicode numeric value property, e.g. U+2155, VULGAR FRACTION ONE FIFTH.

Parameters:

a : array_like, unicode

Input array.
Returns:

out : ndarray, bool

Array of booleans of same shape as a.

See also

unicode.isnumeric


numpy.core.defchararray.isspace

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.isnumeric

Next topic

numpy.core.defchararray.istitle

numpy.core.defchararray.isspace

numpy.core.defchararray.isspace(a) [source]

Returns true for each element if there are only whitespace characters in the string and there is at least one character, false otherwise.

Calls str.isspace element-wise.

For 8-bit strings, this method is locale-dependent.

Parameters:

a : array_like of str or unicode
Returns:

out : ndarray

Output array of bools

See also

str.isspace


numpy.core.defchararray.istitle

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.isspace

Next topic

numpy.core.defchararray.isupper

numpy.core.defchararray.istitle

numpy.core.defchararray.istitle(a) [source]

Returns true for each element if the element is a titlecased string and there is at least one character, false otherwise.

Call str.istitle element-wise.

For 8-bit strings, this method is locale-dependent.

Parameters:

a : array_like of str or unicode
Returns:

out : ndarray

Output array of bools

See also

str.istitle


numpy.core.defchararray.isupper

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.istitle

Next topic

numpy.core.defchararray.rfind

numpy.core.defchararray.isupper

numpy.core.defchararray.isupper(a) [source]

Returns true for each element if all cased characters in the string are uppercase and there is at least one character, false otherwise.

Call str.isupper element-wise.

For 8-bit strings, this method is locale-dependent.

Parameters:

a : array_like of str or unicode
Returns:

out : ndarray

Output array of bools

See also

str.isupper


numpy.core.defchararray.rfind

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.isupper

Next topic

numpy.core.defchararray.rindex

numpy.core.defchararray.rfind

numpy.core.defchararray.rfind(a, sub, start=0, end=None) [source]

For each element in a, return the highest index in the string where substring sub is found, such that sub is contained within [start, end].

Calls str.rfind element-wise.

Parameters:

a : array-like of str or unicode

sub : str or unicode

start, end : int, optional

Optional arguments start and end are interpreted as in slice notation.
Returns:

out : ndarray

Output array of ints. Return -1 on failure.

See also

str.rfind


numpy.core.defchararray.rindex

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.rfind

Next topic

numpy.core.defchararray.startswith

numpy.core.defchararray.rindex

numpy.core.defchararray.rindex(a, sub, start=0, end=None) [source]

Like rfind, but raises ValueError when the substring sub is not found.

Calls str.rindex element-wise.

Parameters:

a : array-like of str or unicode

sub : str or unicode

start, end : int, optional
Returns:

out : ndarray

Output array of ints.

See also

rfind, str.rindex


numpy.core.defchararray.startswith

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.rindex

Next topic

numpy.core.defchararray.chararray

numpy.core.defchararray.startswith

numpy.core.defchararray.startswith(a, prefix, start=0, end=None) [source]

Returns a boolean array which is True where the string element in a starts with prefix, otherwise False.

Calls str.startswith element-wise.

Parameters:

a : array_like of str or unicode

prefix : str

start, end : int, optional

With optional start, test beginning at that position. With optional end, stop comparing at that position.
Returns:

out : ndarray

Array of booleans

See also

str.startswith


numpy.core.defchararray.chararray

  • String operations
  • next
  • previous

Previous topic

numpy.core.defchararray.startswith

Next topic

numpy.core.defchararray.chararray.T

numpy.core.defchararray.chararray

class numpy.core.defchararray.chararray [source]

Provides a convenient view on arrays of string and unicode values.

Note

The chararray class exists for backwards compatibility with Numarray, it is not recommended for new development. Starting from numpy 1.4, if one needs arrays of strings, it is recommended to use arrays of dtype object_, string_ or unicode_, and use the free functions in the numpy.char module for fast vectorized string operations.

Versus a regular Numpy array of type str or unicode, this class adds the following functionality:

  1. values automatically have whitespace removed from the end when indexed
  2. comparison operators automatically remove whitespace from the end when comparing values
  3. vectorized string operations are provided as methods (e.g. endswith) and infix operators (e.g. "+", "*", "%")

chararrays should be created using numpy.char.array or numpy.char.asarray, rather than this constructor directly.

This constructor creates the array, using buffer (with offset and strides) if it is not None. If buffer is None, then constructs a new array with strides in “C order”, unless both len(shape) >= 2 and order='Fortran', in which case strides is in “Fortran order”.

Parameters:

shape : tuple

Shape of the array.

itemsize : int, optional

Length of each array element, in number of characters. Default is 1.

unicode : bool, optional

Are the array elements of type unicode (True) or string (False). Default is False.

buffer : int, optional

Memory address of the start of the array data. Default is None, in which case a new array is created.

offset : int, optional

Fixed stride displacement from the beginning of an axis? Default is 0. Needs to be >=0.

strides : array_like of ints, optional

Strides for the array (see ndarray.strides for full description). Default is None.

order : {‘C’, ‘F’}, optional

The order in which the array data is stored in memory: ‘C’ -> “row major” order (the default), ‘F’ -> “column major” (Fortran) order.

Examples

>>> charar = np.chararray((3, 3))
>>> charar[:] = 'a'
>>> charar
chararray([['a', 'a', 'a'],
       ['a', 'a', 'a'],
       ['a', 'a', 'a']],
      dtype='|S1')

>>> charar = np.chararray(charar.shape, itemsize=5)
>>> charar[:] = 'abc'
>>> charar
chararray([['abc', 'abc', 'abc'],
       ['abc', 'abc', 'abc'],
       ['abc', 'abc', 'abc']],
      dtype='|S5')

Attributes

T | Same as self.transpose(), except that self is returned if self.ndim < 2.
base | Base object if memory is from some other object.
ctypes | An object to simplify the interaction of the array with the ctypes module.
data | Python buffer object pointing to the start of the array’s data.
dtype | Data-type of the array’s elements.
flags | Information about the memory layout of the array.
flat | A 1-D iterator over the array.
imag | The imaginary part of the array.
itemsize | Length of one array element in bytes.
nbytes | Total bytes consumed by the elements of the array.
ndim | Number of array dimensions.
real | The real part of the array.
shape | Tuple of array dimensions.
size | Number of elements in the array.
strides | Tuple of bytes to step in each dimension when traversing an array.

Methods

astype(dtype[, order, casting, subok, copy]) | Copy of the array, cast to a specified type.
copy([order]) | Return a copy of the array.
count(sub[, start, end]) | Returns an array with the number of non-overlapping occurrences of substring sub in the range [start, end].
decode([encoding, errors]) | Calls str.decode element-wise.
dump(file) | Dump a pickle of the array to the specified file.
dumps() | Returns the pickle of the array as a string.
encode([encoding, errors]) | Calls str.encode element-wise.
endswith(suffix[, start, end]) | Returns a boolean array which is True where the string element in self ends with suffix, otherwise False.
expandtabs([tabsize]) | Return a copy of each string element where all tab characters are replaced by one or more spaces.
fill(value) | Fill the array with a scalar value.
find(sub[, start, end]) | For each element, return the lowest index in the string where substring sub is found.
flatten([order]) | Return a copy of the array collapsed into one dimension.
getfield(dtype[, offset]) | Returns a field of the given array as a certain type.
index(sub[, start, end]) | Like find, but raises ValueError when the substring is not found.
isalnum() | Returns true for each element if all characters in the string are alphanumeric and there is at least one character, false otherwise.
isalpha() | Returns true for each element if all characters in the string are alphabetic and there is at least one character, false otherwise.
isdecimal() | For each element in self, return True if there are only decimal characters in the element.
isdigit() | Returns true for each element if all characters in the string are digits and there is at least one character, false otherwise.
islower() | Returns true for each element if all cased characters in the string are lowercase and there is at least one cased character, false otherwise.
isnumeric() | For each element in self, return True if there are only numeric characters in the element.
isspace() | Returns true for each element if there are only whitespace characters in the string and there is at least one character, false otherwise.
istitle() | Returns true for each element if the element is a titlecased string and there is at least one character, false otherwise.
isupper() | Returns true for each element if all cased characters in the string are uppercase and there is at least one character, false otherwise.
item(*args) | Copy an element of an array to a standard Python scalar and return it.
join(seq) | Return a string which is the concatenation of the strings in the sequence seq.
ljust(width[, fillchar]) | Return an array with the elements of self left-justified in a string of length width.
lower() | Return an array with the elements of self converted to lowercase.
lstrip([chars]) | For each element in self, return a copy with the leading characters removed.
nonzero() | Return the indices of the elements that are non-zero.
put(indices, values[, mode]) | Set a.flat[n] = values[n] for all n in indices.
ravel([order]) | Return a flattened array.
repeat(repeats[, axis]) | Repeat elements of an array.
replace(old, new[, count]) | For each element in self, return a copy of the string with all occurrences of substring old replaced by new.
reshape(shape[, order]) | Returns an array containing the same data with a new shape.
resize(new_shape[, refcheck]) | Change shape and size of array in-place.
rfind(sub[, start, end]) | For each element in self, return the highest index in the string where substring sub is found, such that sub is contained within [start, end].
rindex(sub[, start, end]) | Like rfind, but raises ValueError when the substring sub is not found.
rjust(width[, fillchar]) | Return an array with the elements of self right-justified in a string of length width.
rsplit([sep, maxsplit]) | For each element in self, return a list of the words in the string, using sep as the delimiter string.
rstrip([chars]) | For each element in self, return a copy with the trailing characters removed.
searchsorted(v[, side, sorter]) | Find indices where elements of v should be inserted in a to maintain order.
setfield(val, dtype[, offset]) | Put a value into a specified place in a field defined by a data-type.
setflags([write, align, uic]) | Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively.
sort([axis, kind, order]) | Sort an array, in-place.
split([sep, maxsplit]) | For each element in self, return a list of the words in the string, using sep as the delimiter string.
splitlines([keepends]) | For each element in self, return a list of the lines in the element, breaking at line boundaries.
squeeze([axis]) | Remove single-dimensional entries from the shape of a.
startswith(prefix[, start, end]) | Returns a boolean array which is True where the string element in self starts with prefix, otherwise False.
strip([chars]) | For each element in self, return a copy with the leading and trailing characters removed.
swapaxes(axis1, axis2) | Return a view of the array with axis1 and axis2 interchanged.
swapcase() | For each element in self, return a copy of the string with uppercase characters converted to lowercase and vice versa.
take(indices[, axis, out, mode]) | Return an array formed from the elements of a at the given indices.
title() | For each element in self, return a titlecased version of the string: words start with uppercase characters, all remaining cased characters are lowercase.
tofile(fid[, sep, format]) | Write array to a file as text or binary (default).
tolist() | Return the array as a (possibly nested) list.
tostring([order]) | Construct Python bytes containing the raw data bytes in the array.
translate(table[, deletechars]) | For each element in self, return a copy of the string where all characters occurring in the optional argument deletechars are removed, and the remaining characters have been mapped through the given translation table.
transpose(*axes) | Returns a view of the array with axes transposed.
upper() | Return an array with the elements of self converted to uppercase.
view([dtype, type]) | New view of array with the same data.
zfill(width) | Return the numeric string left-filled with zeros in a string of length width.
argsort


numpy.core.defchararray.chararray.T

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray

Next topic

numpy.core.defchararray.chararray.base

numpy.core.defchararray.chararray.T

chararray.T

Same as self.transpose(), except that self is returned if self.ndim < 2.

Examples

>>> x = np.array([[1.,2.],[3.,4.]])
>>> x
array([[ 1.,  2.],
       [ 3.,  4.]])
>>> x.T
array([[ 1.,  3.],
       [ 2.,  4.]])
>>> x = np.array([1.,2.,3.,4.])
>>> x
array([ 1.,  2.,  3.,  4.])
>>> x.T
array([ 1.,  2.,  3.,  4.])


numpy.core.defchararray.chararray.base

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.T

Next topic

numpy.core.defchararray.chararray.ctypes

numpy.core.defchararray.chararray.base

chararray.base

Base object if memory is from some other object.

Examples

The base of an array that owns its memory is None:

>>> x = np.array([1,2,3,4])
>>> x.base is None
True

Slicing creates a view, whose memory is shared with x:

>>> y = x[2:]
>>> y.base is x
True


numpy.core.defchararray.chararray.ctypes

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.base

Next topic

numpy.core.defchararray.chararray.data

numpy.core.defchararray.chararray.ctypes

chararray.ctypes

An object to simplify the interaction of the array with the ctypes module.

This attribute creates an object that makes it easier to use arrays when calling shared libraries with the ctypes module. The returned object has, among others, data, shape, and strides attributes (see Notes below) which themselves return ctypes objects that can be used as arguments to a shared library.

Parameters:

None
Returns:

c : Python object

Possessing attributes data, shape, strides, etc.

See also

numpy.ctypeslib

Notes

Below are the public attributes of this object which were documented in “Guide to NumPy” (we have omitted undocumented public attributes, as well as documented private attributes):

  • data: A pointer to the memory area of the array as a Python integer. This memory area may contain data that is not aligned, or not in correct byte-order. The memory area may not even be writeable. The array flags and data-type of this array should be respected when passing this attribute to arbitrary C-code to avoid trouble that can include Python crashing. User Beware! The value of this attribute is exactly the same as self._array_interface_[‘data’][0].
  • shape (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the C-integer corresponding to dtype(‘p’) on this platform. This base-type could be c_int, c_long, or c_longlong depending on the platform. The c_intp type is defined accordingly in numpy.ctypeslib. The ctypes array contains the shape of the underlying array.
  • strides (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the same as for the shape attribute. This ctypes array contains the strides information from the underlying array. This strides information is important for showing how many bytes must be jumped to get to the next element in the array.
  • data_as(obj): Return the data pointer cast to a particular c-types object. For example, calling self._as_parameter_ is equivalent to self.data_as(ctypes.c_void_p). Perhaps you want to use the data as a pointer to a ctypes array of floating-point data: self.data_as(ctypes.POINTER(ctypes.c_double)).
  • shape_as(obj): Return the shape tuple as an array of some other c-types type. For example: self.shape_as(ctypes.c_short).
  • strides_as(obj): Return the strides tuple as an array of some other c-types type. For example: self.strides_as(ctypes.c_longlong).

Be careful using the ctypes attribute - especially on temporary arrays or arrays constructed on the fly. For example, calling (a+b).ctypes.data_as(ctypes.c_void_p) returns a pointer to memory that is invalid because the array created as (a+b) is deallocated before the next Python statement. You can avoid this problem using either c=a+b or ct=(a+b).ctypes. In the latter case, ct will hold a reference to the array until ct is deleted or re-assigned.

If the ctypes module is not available, then the ctypes attribute of array objects still returns something useful, but ctypes objects are not returned and errors may be raised instead. In particular, the object will still have the as parameter attribute which will return an integer equal to the data attribute.

Examples

>>> import ctypes
>>> x
array([[0, 1],
       [2, 3]])
>>> x.ctypes.data
30439712
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long))
<ctypes.LP_c_long object at 0x01F01300>
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long)).contents
c_long(0)
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_longlong)).contents
c_longlong(4294967296L)
>>> x.ctypes.shape
<numpy.core._internal.c_long_Array_2 object at 0x01FFD580>
>>> x.ctypes.shape_as(ctypes.c_long)
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides_as(ctypes.c_longlong)
<numpy.core._internal.c_longlong_Array_2 object at 0x01F01300>


numpy.core.defchararray.chararray.data

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.ctypes

Next topic

numpy.core.defchararray.chararray.dtype

numpy.core.defchararray.chararray.data

chararray.data

Python buffer object pointing to the start of the array’s data.


numpy.core.defchararray.chararray.dtype

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.data

Next topic

numpy.core.defchararray.chararray.flags

numpy.core.defchararray.chararray.dtype

chararray.dtype

Data-type of the array’s elements.

Parameters: None
Returns: d : numpy dtype object

See also

numpy.dtype

Examples

>>> x
array([[0, 1],
       [2, 3]])
>>> x.dtype
dtype('int32')
>>> type(x.dtype)
<type 'numpy.dtype'>


numpy.core.defchararray.chararray.flags

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.dtype

Next topic

numpy.core.defchararray.chararray.flat

numpy.core.defchararray.chararray.flags

chararray.flags

Information about the memory layout of the array.

Notes

The flags object can be accessed dictionary-like (as in a.flags['WRITEABLE']), or by using lowercased attribute names (as in a.flags.writeable). Short flag names are only supported in dictionary access.

Only the UPDATEIFCOPY, WRITEABLE, and ALIGNED flags can be changed by the user, via direct assignment to the attribute or dictionary entry, or by calling ndarray.setflags.

The array flags cannot be set arbitrarily:

  • UPDATEIFCOPY can only be set False.
  • ALIGNED can only be set True if the data is truly aligned.
  • WRITEABLE can only be set True if the array owns its own memory or the ultimate owner of the memory exposes a writeable buffer interface or is a string.

Arrays can be both C-style and Fortran-style contiguous simultaneously. This is clear for 1-dimensional arrays, but can also be true for higher dimensional arrays.

Even for contiguous arrays a stride for a given dimension arr.strides[dim] may be arbitrary if arr.shape[dim] == 1 or the array has no elements. It does not generally hold that self.strides[-1] == self.itemsize for C-style contiguous arrays or self.strides[0] == self.itemsize for Fortran-style contiguous arrays is true.

Attributes

C_CONTIGUOUS (C) | The data is in a single, C-style contiguous segment.
F_CONTIGUOUS (F) | The data is in a single, Fortran-style contiguous segment.
OWNDATA (O) | The array owns the memory it uses or borrows it from another object.
WRITEABLE (W) | The data area can be written to. Setting this to False locks the data, making it read-only. A view (slice, etc.) inherits WRITEABLE from its base array at creation time, but a view of a writeable array may be subsequently locked while the base array remains writeable. (The opposite is not true, in that a view of a locked array may not be made writeable. However, currently, locking a base object does not lock any views that already reference it, so under that circumstance it is possible to alter the contents of a locked array via a previously created writeable view onto it.) Attempting to change a non-writeable array raises a RuntimeError exception.
ALIGNED (A) | The data and all elements are aligned appropriately for the hardware.
UPDATEIFCOPY (U) | This array is a copy of some other array. When this array is deallocated, the base array will be updated with the contents of this array.
FNC | F_CONTIGUOUS and not C_CONTIGUOUS.
FORC | F_CONTIGUOUS or C_CONTIGUOUS (one-segment test).
BEHAVED (B) | ALIGNED and WRITEABLE.
CARRAY (CA) | BEHAVED and C_CONTIGUOUS.
FARRAY (FA) | BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS.


numpy.core.defchararray.chararray.flat

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.flags

Next topic

numpy.core.defchararray.chararray.imag

numpy.core.defchararray.chararray.flat

chararray.flat

A 1-D iterator over the array.

This is a numpy.flatiter instance, which acts similarly to, but is not a subclass of, Python’s built-in iterator object.

See also

flatten
Return a copy of the array collapsed into one dimension.

flatiter

Examples

>>> x = np.arange(1, 7).reshape(2, 3)
>>> x
array([[1, 2, 3],
       [4, 5, 6]])
>>> x.flat[3]
4
>>> x.T
array([[1, 4],
       [2, 5],
       [3, 6]])
>>> x.T.flat[3]
5
>>> type(x.flat)
<type 'numpy.flatiter'>

An assignment example:

>>> x.flat = 3; x
array([[3, 3, 3],
       [3, 3, 3]])
>>> x.flat[[1,4]] = 1; x
array([[3, 1, 3],
       [3, 1, 3]])


numpy.core.defchararray.chararray.imag

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.flat

Next topic

numpy.core.defchararray.chararray.itemsize

numpy.core.defchararray.chararray.imag

chararray.imag

The imaginary part of the array.

Examples

>>> x = np.sqrt([1+0j, 0+1j])
>>> x.imag
array([ 0.        ,  0.70710678])
>>> x.imag.dtype
dtype('float64')


numpy.core.defchararray.chararray.itemsize

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.imag

Next topic

numpy.core.defchararray.chararray.nbytes

numpy.core.defchararray.chararray.itemsize

chararray.itemsize

Length of one array element in bytes.

Examples

>>> x = np.array([1,2,3], dtype=np.float64)
>>> x.itemsize
8
>>> x = np.array([1,2,3], dtype=np.complex128)
>>> x.itemsize
16


numpy.core.defchararray.chararray.nbytes

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.itemsize

Next topic

numpy.core.defchararray.chararray.ndim

numpy.core.defchararray.chararray.nbytes

chararray.nbytes

Total bytes consumed by the elements of the array.

Notes

Does not include memory consumed by non-element attributes of the array object.

Examples

>>> x = np.zeros((3,5,2), dtype=np.complex128)
>>> x.nbytes
480
>>> np.prod(x.shape) * x.itemsize
480


numpy.core.defchararray.chararray.ndim

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.nbytes

Next topic

numpy.core.defchararray.chararray.real

numpy.core.defchararray.chararray.ndim

chararray.ndim

Number of array dimensions.

Examples

>>> x = np.array([1, 2, 3])
>>> x.ndim
1
>>> y = np.zeros((2, 3, 4))
>>> y.ndim
3


numpy.core.defchararray.chararray.real

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.ndim

Next topic

numpy.core.defchararray.chararray.shape

numpy.core.defchararray.chararray.real

chararray.real

The real part of the array.

See also

numpy.real
equivalent function

Examples

>>> x = np.sqrt([1+0j, 0+1j])
>>> x.real
array([ 1.        ,  0.70710678])
>>> x.real.dtype
dtype('float64')


numpy.core.defchararray.chararray.shape

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.real

Next topic

numpy.core.defchararray.chararray.size

numpy.core.defchararray.chararray.shape

chararray.shape

Tuple of array dimensions.

Notes

May be used to “reshape” the array, as long as this would not require a change in the total number of elements

Examples

>>> x = np.array([1, 2, 3, 4])
>>> x.shape
(4,)
>>> y = np.zeros((2, 3, 4))
>>> y.shape
(2, 3, 4)
>>> y.shape = (3, 8)
>>> y
array([[ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])
>>> y.shape = (3, 6)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: total size of new array must be unchanged


numpy.core.defchararray.chararray.size

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.shape

Next topic

numpy.core.defchararray.chararray.strides

numpy.core.defchararray.chararray.size

chararray.size

Number of elements in the array.

Equivalent to np.prod(a.shape), i.e., the product of the array’s dimensions.

Examples

>>> x = np.zeros((3, 5, 2), dtype=np.complex128)
>>> x.size
30
>>> np.prod(x.shape)
30


numpy.core.defchararray.chararray.strides

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.size

Next topic

numpy.core.defchararray.chararray.astype

numpy.core.defchararray.chararray.strides

chararray.strides

Tuple of bytes to step in each dimension when traversing an array.

The byte offset of element (i[0], i[1], ..., i[n]) in an array a is:

offset = sum(np.array(i) * a.strides)

A more detailed explanation of strides can be found in the “ndarray.rst” file in the NumPy reference guide.

See also

numpy.lib.stride_tricks.as_strided

Notes

Imagine an array of 32-bit integers (each 4 bytes):

x = np.array([[0, 1, 2, 3, 4],
              [5, 6, 7, 8, 9]], dtype=np.int32)

This array is stored in memory as 40 bytes, one after the other (known as a contiguous block of memory). The strides of an array tell us how many bytes we have to skip in memory to move to the next position along a certain axis. For example, we have to skip 4 bytes (1 value) to move to the next column, but 20 bytes (5 values) to get to the same position in the next row. As such, the strides for the array x will be (20, 4).

Examples

>>> y = np.reshape(np.arange(2*3*4), (2,3,4))
>>> y
array([[[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]],
       [[12, 13, 14, 15],
        [16, 17, 18, 19],
        [20, 21, 22, 23]]])
>>> y.strides
(48, 16, 4)
>>> y[1,1,1]
17
>>> offset=sum(y.strides * np.array((1,1,1)))
>>> offset/y.itemsize
17

>>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0)
>>> x.strides
(32, 4, 224, 1344)
>>> i = np.array([3,5,2,2])
>>> offset = sum(i * x.strides)
>>> x[3,5,2,2]
813
>>> offset / x.itemsize
813


numpy.core.defchararray.chararray.astype

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.strides

Next topic

numpy.core.defchararray.chararray.copy

numpy.core.defchararray.chararray.astype

chararray.astype(dtype, order='K', casting='unsafe', subok=True, copy=True)

Copy of the array, cast to a specified type.

Parameters:

dtype : str or dtype

Typecode or data-type to which the array is cast.

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout order of the result. ‘C’ means C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran contiguous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements appear in memory as possible. Default is ‘K’.

casting : {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

Controls what kind of data casting may occur. Defaults to ‘unsafe’ for backwards compatibility.

  • ‘no’ means the data types should not be cast at all.
  • ‘equiv’ means only byte-order changes are allowed.
  • ‘safe’ means only casts which can preserve values are allowed.
  • ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.
  • ‘unsafe’ means any data conversions may be done.

subok : bool, optional

If True, then sub-classes will be passed-through (default), otherwise the returned array will be forced to be a base-class array.

copy : bool, optional

By default, astype always returns a newly allocated array. If this is set to false, and the dtype, order, and subok requirements are satisfied, the input array is returned instead of a copy.
Returns:

arr_t : ndarray

Unless copy is False and the other conditions for returning the input array are satisfied (see description for copy input paramter), arr_t is a new array of the same shape as the input array, with dtype, order given by dtype, order.
Raises:

ComplexWarning

When casting from complex to float or int. To avoid this, one should use a.real.astype(t).

Notes

Starting in NumPy 1.9, astype method now returns an error if the string dtype to cast to is not long enough in ‘safe’ casting mode to hold the max value of integer/float array that is being casted. Previously the casting was allowed even if the result was truncated.

Examples

>>> x = np.array([1, 2, 2.5])
>>> x
array([ 1. ,  2. ,  2.5])

>>> x.astype(int)
array([1, 2, 2])


numpy.core.defchararray.chararray.copy

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.astype

Next topic

numpy.core.defchararray.chararray.count

numpy.core.defchararray.chararray.copy

chararray.copy(order='C')

Return a copy of the array.

Parameters:

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout of the copy. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible. (Note that this function and :func:numpy.copy are very similar, but have different default values for their order= arguments.)

See also

numpy.copy, numpy.copyto

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
       [0, 0, 0]])

>>> y
array([[1, 2, 3],
       [4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True


numpy.core.defchararray.chararray.count

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.copy

Next topic

numpy.core.defchararray.chararray.decode

numpy.core.defchararray.chararray.count

chararray.count(sub, start=0, end=None) [source]

Returns an array with the number of non-overlapping occurrences of substring sub in the range [start, end].

See also

char.count


numpy.core.defchararray.chararray.decode

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.count

Next topic

numpy.core.defchararray.chararray.dump

numpy.core.defchararray.chararray.decode

chararray.decode(encoding=None, errors=None) [source]

Calls str.decode element-wise.

See also

char.decode


numpy.core.defchararray.chararray.dump

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.decode

Next topic

numpy.core.defchararray.chararray.dumps

numpy.core.defchararray.chararray.dump

chararray.dump(file)

Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.

Parameters:

file : str

A string naming the dump file.


numpy.core.defchararray.chararray.dumps

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.dump

Next topic

numpy.core.defchararray.chararray.encode

numpy.core.defchararray.chararray.dumps

chararray.dumps()

Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an array.

Parameters: None


numpy.core.defchararray.chararray.encode

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.dumps

Next topic

numpy.core.defchararray.chararray.endswith

numpy.core.defchararray.chararray.encode

chararray.encode(encoding=None, errors=None) [source]

Calls str.encode element-wise.

See also

char.encode


numpy.core.defchararray.chararray.endswith

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.encode

Next topic

numpy.core.defchararray.chararray.expandtabs

numpy.core.defchararray.chararray.endswith

chararray.endswith(suffix, start=0, end=None) [source]

Returns a boolean array which is True where the string element in self ends with suffix, otherwise False.

See also

char.endswith


numpy.core.defchararray.chararray.expandtabs

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.endswith

Next topic

numpy.core.defchararray.chararray.fill

numpy.core.defchararray.chararray.expandtabs

chararray.expandtabs(tabsize=8) [source]

Return a copy of each string element where all tab characters are replaced by one or more spaces.

See also

char.expandtabs


numpy.core.defchararray.chararray.fill

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.expandtabs

Next topic

numpy.core.defchararray.chararray.find

numpy.core.defchararray.chararray.fill

chararray.fill(value)

Fill the array with a scalar value.

Parameters:

value : scalar

All elements of a will be assigned this value.

Examples

>>> a = np.array([1, 2])
>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([ 1.,  1.])


numpy.core.defchararray.chararray.find

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.fill

Next topic

numpy.core.defchararray.chararray.flatten

numpy.core.defchararray.chararray.find

chararray.find(sub, start=0, end=None) [source]

For each element, return the lowest index in the string where substring sub is found.

See also

char.find


numpy.core.defchararray.chararray.flatten

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.find

Next topic

numpy.core.defchararray.chararray.getfield

numpy.core.defchararray.chararray.flatten

chararray.flatten(order='C')

Return a copy of the array collapsed into one dimension.

Parameters:

order : {‘C’, ‘F’, ‘A’}, optional

Whether to flatten in C (row-major), Fortran (column-major) order, or preserve the C/Fortran ordering from a. The default is ‘C’.
Returns:

y : ndarray

A copy of the input array, flattened to one dimension.

See also

ravel
Return a flattened array.
flat
A 1-D flat iterator over the array.

Examples

>>> a = np.array([[1,2], [3,4]])
>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten('F')
array([1, 3, 2, 4])


numpy.core.defchararray.chararray.getfield

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.flatten

Next topic

numpy.core.defchararray.chararray.index

numpy.core.defchararray.chararray.getfield

chararray.getfield(dtype, offset=0)

Returns a field of the given array as a certain type.

A field is a view of the array data with a given data-type. The values in the view are determined by the given type and the offset into the current array in bytes. The offset needs to be such that the view dtype fits in the array dtype; for example an array of dtype complex128 has 16-byte elements. If taking a view with a 32-bit integer (4 bytes), the offset needs to be between 0 and 12 bytes.

Parameters:

dtype : str or dtype

The data type of the view. The dtype size of the view can not be larger than that of the array itself.

offset : int

Number of bytes to skip before beginning the element view.

Examples

>>> x = np.diag([1.+1.j]*2)
>>> x[1, 1] = 2 + 4.j
>>> x
array([[ 1.+1.j,  0.+0.j],
       [ 0.+0.j,  2.+4.j]])
>>> x.getfield(np.float64)
array([[ 1.,  0.],
       [ 0.,  2.]])

By choosing an offset of 8 bytes we can select the complex part of the array for our view:

>>> x.getfield(np.float64, offset=8)
array([[ 1.,  0.],
   [ 0.,  4.]])


numpy.core.defchararray.chararray.index

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.getfield

Next topic

numpy.core.defchararray.chararray.isalnum

numpy.core.defchararray.chararray.index

chararray.index(sub, start=0, end=None) [source]

Like find, but raises ValueError when the substring is not found.

See also

char.index


numpy.core.defchararray.chararray.isalnum

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.index

Next topic

numpy.core.defchararray.chararray.isalpha

numpy.core.defchararray.chararray.isalnum

chararray.isalnum() [source]

Returns true for each element if all characters in the string are alphanumeric and there is at least one character, false otherwise.

See also

char.isalnum


numpy.core.defchararray.chararray.isalpha

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.isalnum

Next topic

numpy.core.defchararray.chararray.isdecimal

numpy.core.defchararray.chararray.isalpha

chararray.isalpha() [source]

Returns true for each element if all characters in the string are alphabetic and there is at least one character, false otherwise.

See also

char.isalpha


numpy.core.defchararray.chararray.isdecimal

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.isalpha

Next topic

numpy.core.defchararray.chararray.isdigit

numpy.core.defchararray.chararray.isdecimal

chararray.isdecimal() [source]

For each element in self, return True if there are only decimal characters in the element.

See also

char.isdecimal


numpy.core.defchararray.chararray.isdigit

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.isdecimal

Next topic

numpy.core.defchararray.chararray.islower

numpy.core.defchararray.chararray.isdigit

chararray.isdigit() [source]

Returns true for each element if all characters in the string are digits and there is at least one character, false otherwise.

See also

char.isdigit


numpy.core.defchararray.chararray.islower

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.isdigit

Next topic

numpy.core.defchararray.chararray.isnumeric

numpy.core.defchararray.chararray.islower

chararray.islower() [source]

Returns true for each element if all cased characters in the string are lowercase and there is at least one cased character, false otherwise.

See also

char.islower


numpy.core.defchararray.chararray.isnumeric

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.islower

Next topic

numpy.core.defchararray.chararray.isspace

numpy.core.defchararray.chararray.isnumeric

chararray.isnumeric() [source]

For each element in self, return True if there are only numeric characters in the element.

See also

char.isnumeric


numpy.core.defchararray.chararray.isspace

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.isnumeric

Next topic

numpy.core.defchararray.chararray.istitle

numpy.core.defchararray.chararray.isspace

chararray.isspace() [source]

Returns true for each element if there are only whitespace characters in the string and there is at least one character, false otherwise.

See also

char.isspace


numpy.core.defchararray.chararray.istitle

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.isspace

Next topic

numpy.core.defchararray.chararray.isupper

numpy.core.defchararray.chararray.istitle

chararray.istitle() [source]

Returns true for each element if the element is a titlecased string and there is at least one character, false otherwise.

See also

char.istitle


numpy.core.defchararray.chararray.isupper

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.istitle

Next topic

numpy.core.defchararray.chararray.item

numpy.core.defchararray.chararray.isupper

chararray.isupper() [source]

Returns true for each element if all cased characters in the string are uppercase and there is at least one character, false otherwise.

See also

char.isupper


numpy.core.defchararray.chararray.item

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.isupper

Next topic

numpy.core.defchararray.chararray.join

numpy.core.defchararray.chararray.item

chararray.item(*args)

Copy an element of an array to a standard Python scalar and return it.

Parameters:

*args : Arguments (variable number and type)

  • none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.
  • int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.
  • tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.
Returns:

z : Standard Python scalar object

A copy of the specified element of the array as a suitable Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.item(3)
2
>>> x.item(7)
5
>>> x.item((0, 1))
1
>>> x.item((2, 2))
3


numpy.core.defchararray.chararray.join

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.item

Next topic

numpy.core.defchararray.chararray.ljust

numpy.core.defchararray.chararray.join

chararray.join(seq) [source]

Return a string which is the concatenation of the strings in the sequence seq.

See also

char.join


numpy.core.defchararray.chararray.ljust

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.join

Next topic

numpy.core.defchararray.chararray.lower

numpy.core.defchararray.chararray.ljust

chararray.ljust(width, fillchar=' ') [source]

Return an array with the elements of self left-justified in a string of length width.

See also

char.ljust


numpy.core.defchararray.chararray.lower

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.ljust

Next topic

numpy.core.defchararray.chararray.lstrip

numpy.core.defchararray.chararray.lower

chararray.lower() [source]

Return an array with the elements of self converted to lowercase.

See also

char.lower


numpy.core.defchararray.chararray.lstrip

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.lower

Next topic

numpy.core.defchararray.chararray.nonzero

numpy.core.defchararray.chararray.lstrip

chararray.lstrip(chars=None) [source]

For each element in self, return a copy with the leading characters removed.

See also

char.lstrip


numpy.core.defchararray.chararray.nonzero

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.lstrip

Next topic

numpy.core.defchararray.chararray.put

numpy.core.defchararray.chararray.nonzero

chararray.nonzero()

Return the indices of the elements that are non-zero.

Refer to numpy.nonzero for full documentation.

See also

numpy.nonzero
equivalent function


numpy.core.defchararray.chararray.put

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.nonzero

Next topic

numpy.core.defchararray.chararray.ravel

numpy.core.defchararray.chararray.put

chararray.put(indices, values, mode='raise')

Set a.flat[n] = values[n] for all n in indices.

Refer to numpy.put for full documentation.

See also

numpy.put
equivalent function


numpy.core.defchararray.chararray.ravel

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.put

Next topic

numpy.core.defchararray.chararray.repeat

numpy.core.defchararray.chararray.ravel

chararray.ravel([order])

Return a flattened array.

Refer to numpy.ravel for full documentation.

See also

numpy.ravel
equivalent function
ndarray.flat
a flat iterator on the array.


numpy.core.defchararray.chararray.repeat

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.ravel

Next topic

numpy.core.defchararray.chararray.replace

numpy.core.defchararray.chararray.repeat

chararray.repeat(repeats, axis=None)

Repeat elements of an array.

Refer to numpy.repeat for full documentation.

See also

numpy.repeat
equivalent function


numpy.core.defchararray.chararray.replace

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.repeat

Next topic

numpy.core.defchararray.chararray.reshape

numpy.core.defchararray.chararray.replace

chararray.replace(old, new, count=None) [source]

For each element in self, return a copy of the string with all occurrences of substring old replaced by new.

See also

char.replace


numpy.core.defchararray.chararray.reshape

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.replace

Next topic

numpy.core.defchararray.chararray.resize

numpy.core.defchararray.chararray.reshape

chararray.reshape(shape, order='C')

Returns an array containing the same data with a new shape.

Refer to numpy.reshape for full documentation.

See also

numpy.reshape
equivalent function


numpy.core.defchararray.chararray.resize

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.reshape

Next topic

numpy.core.defchararray.chararray.rfind

numpy.core.defchararray.chararray.resize

chararray.resize(new_shape, refcheck=True)

Change shape and size of array in-place.

Parameters:

new_shape : tuple of ints, or n ints

Shape of resized array.

refcheck : bool, optional

If False, reference count will not be checked. Default is True.
Returns:

None
Raises:

ValueError

If a does not own its own data or references or views to it exist, and the data memory must be changed.

SystemError

If the order keyword argument is specified. This behaviour is a bug in NumPy.

See also

resize
Return a new array with the specified shape.

Notes

This reallocates space for the data area if necessary.

Only contiguous arrays (data elements consecutive in memory) can be resized.

The purpose of the reference count check is to make sure you do not use this array as a buffer for another Python object and then reallocate the memory. However, reference counts can increase in other ways so if you are sure that you have not shared the memory for this array with another Python object, then you may safely set refcheck to False.

Examples

Shrinking an array: array is flattened (in the order that the data are stored in memory), resized, and reshaped:

>>> a = np.array([[0, 1], [2, 3]], order='C')
>>> a.resize((2, 1))
>>> a
array([[0],
       [1]])

>>> a = np.array([[0, 1], [2, 3]], order='F')
>>> a.resize((2, 1))
>>> a
array([[0],
       [2]])

Enlarging an array: as above, but missing entries are filled with zeros:

>>> b = np.array([[0, 1], [2, 3]])
>>> b.resize(2, 3) # new_shape parameter doesn't have to be a tuple
>>> b
array([[0, 1, 2],
       [3, 0, 0]])

Referencing an array prevents resizing...

>>> c = a
>>> a.resize((1, 1))
Traceback (most recent call last):
...
ValueError: cannot resize an array that has been referenced ...

Unless refcheck is False:

>>> a.resize((1, 1), refcheck=False)
>>> a
array([[0]])
>>> c
array([[0]])


numpy.core.defchararray.chararray.rfind

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.resize

Next topic

numpy.core.defchararray.chararray.rindex

numpy.core.defchararray.chararray.rfind

chararray.rfind(sub, start=0, end=None) [source]

For each element in self, return the highest index in the string where substring sub is found, such that sub is contained within [start, end].

See also

char.rfind


numpy.core.defchararray.chararray.rindex

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.rfind

Next topic

numpy.core.defchararray.chararray.rjust

numpy.core.defchararray.chararray.rindex

chararray.rindex(sub, start=0, end=None) [source]

Like rfind, but raises ValueError when the substring sub is not found.

See also

char.rindex


numpy.core.defchararray.chararray.rjust

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.rindex

Next topic

numpy.core.defchararray.chararray.rsplit

numpy.core.defchararray.chararray.rjust

chararray.rjust(width, fillchar=' ') [source]

Return an array with the elements of self right-justified in a string of length width.

See also

char.rjust


numpy.core.defchararray.chararray.rsplit

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.rjust

Next topic

numpy.core.defchararray.chararray.rstrip

numpy.core.defchararray.chararray.rsplit

chararray.rsplit(sep=None, maxsplit=None) [source]

For each element in self, return a list of the words in the string, using sep as the delimiter string.

See also

char.rsplit


numpy.core.defchararray.chararray.rstrip

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.rsplit

Next topic

numpy.core.defchararray.chararray.searchsorted

numpy.core.defchararray.chararray.rstrip

chararray.rstrip(chars=None) [source]

For each element in self, return a copy with the trailing characters removed.

See also

char.rstrip


numpy.core.defchararray.chararray.searchsorted

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.rstrip

Next topic

numpy.core.defchararray.chararray.setfield

numpy.core.defchararray.chararray.searchsorted

chararray.searchsorted(v, side='left', sorter=None)

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See also

numpy.searchsorted
equivalent function


numpy.core.defchararray.chararray.setfield

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.searchsorted

Next topic

numpy.core.defchararray.chararray.setflags

numpy.core.defchararray.chararray.setfield

chararray.setfield(val, dtype, offset=0)

Put a value into a specified place in a field defined by a data-type.

Place val into a‘s field defined by dtype and beginning offset bytes into the field.

Parameters:

val : object

Value to be placed in field.

dtype : dtype object

Data-type of the field in which to place val.

offset : int, optional

The number of bytes into the field at which to place val.
Returns:

None

See also

getfield

Examples

>>> x = np.eye(3)
>>> x.getfield(np.float64)
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
>>> x.setfield(3, np.int32)
>>> x.getfield(np.int32)
array([[3, 3, 3],
       [3, 3, 3],
       [3, 3, 3]])
>>> x
array([[  1.00000000e+000,   1.48219694e-323,   1.48219694e-323],
       [  1.48219694e-323,   1.00000000e+000,   1.48219694e-323],
       [  1.48219694e-323,   1.48219694e-323,   1.00000000e+000]])
>>> x.setfield(np.eye(3), np.int32)
>>> x
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])


numpy.core.defchararray.chararray.setflags

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.setfield

Next topic

numpy.core.defchararray.chararray.sort

numpy.core.defchararray.chararray.setflags

chararray.setflags(write=None, align=None, uic=None)

Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively.

These Boolean-valued flags affect how numpy interprets the memory area used by a (see Notes below). The ALIGNED flag can only be set to True if the data is actually aligned according to the type. The UPDATEIFCOPY flag can never be set to True. The flag WRITEABLE can only be set to True if the array owns its own memory, or the ultimate owner of the memory exposes a writeable buffer interface, or is a string. (The exception for string is made so that unpickling can be done without copying memory.)

Parameters:

write : bool, optional

Describes whether or not a can be written to.

align : bool, optional

Describes whether or not a is aligned properly for its type.

uic : bool, optional

Describes whether or not a is a copy of another “base” array.

Notes

Array flags provide information about how the memory area used for the array is to be interpreted. There are 6 Boolean flags in use, only three of which can be changed by the user: UPDATEIFCOPY, WRITEABLE, and ALIGNED.

WRITEABLE (W) the data area can be written to;

ALIGNED (A) the data and strides are aligned appropriately for the hardware (as determined by the compiler);

UPDATEIFCOPY (U) this array is a copy of some other array (referenced by .base). When this array is deallocated, the base array will be updated with the contents of this array.

All flags can be accessed using their first (upper case) letter as well as the full name.

Examples

>>> y
array([[3, 1, 7],
       [2, 0, 0],
       [8, 5, 9]])
>>> y.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : True
  WRITEABLE : True
  ALIGNED : True
  UPDATEIFCOPY : False
>>> y.setflags(write=0, align=0)
>>> y.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : True
  WRITEABLE : False
  ALIGNED : False
  UPDATEIFCOPY : False
>>> y.setflags(uic=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: cannot set UPDATEIFCOPY flag to True


numpy.core.defchararray.chararray.sort

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.setflags

Next topic

numpy.core.defchararray.chararray.split

numpy.core.defchararray.chararray.sort

chararray.sort(axis=-1, kind='quicksort', order=None)

Sort an array, in-place.

Parameters:

axis : int, optional

Axis along which to sort. Default is -1, which means sort along the last axis.

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm. Default is ‘quicksort’.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.

See also

numpy.sort
Return a sorted copy of an array.
argsort
Indirect sort.
lexsort
Indirect stable sort on multiple keys.
searchsorted
Find elements in sorted array.
partition
Partial sort.

Notes

See sort for notes on the different sorting algorithms.

Examples

>>> a = np.array([[1,4], [3,1]])
>>> a.sort(axis=1)
>>> a
array([[1, 4],
       [1, 3]])
>>> a.sort(axis=0)
>>> a
array([[1, 3],
       [1, 4]])

Use the order keyword to specify a field to use when sorting a structured array:

>>> a = np.array([('a', 2), ('c', 1)], dtype=[('x', 'S1'), ('y', int)])
>>> a.sort(order='y')
>>> a
array([('c', 1), ('a', 2)],
      dtype=[('x', '|S1'), ('y', '<i4')])


numpy.core.defchararray.chararray.split

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.sort

Next topic

numpy.core.defchararray.chararray.splitlines

numpy.core.defchararray.chararray.split

chararray.split(sep=None, maxsplit=None) [source]

For each element in self, return a list of the words in the string, using sep as the delimiter string.

See also

char.split


numpy.core.defchararray.chararray.splitlines

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.split

Next topic

numpy.core.defchararray.chararray.squeeze

numpy.core.defchararray.chararray.splitlines

chararray.splitlines(keepends=None) [source]

For each element in self, return a list of the lines in the element, breaking at line boundaries.

See also

char.splitlines


numpy.core.defchararray.chararray.squeeze

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.splitlines

Next topic

numpy.core.defchararray.chararray.startswith

numpy.core.defchararray.chararray.squeeze

chararray.squeeze(axis=None)

Remove single-dimensional entries from the shape of a.

Refer to numpy.squeeze for full documentation.

See also

numpy.squeeze
equivalent function


numpy.core.defchararray.chararray.startswith

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.squeeze

Next topic

numpy.core.defchararray.chararray.strip

numpy.core.defchararray.chararray.startswith

chararray.startswith(prefix, start=0, end=None) [source]

Returns a boolean array which is True where the string element in self starts with prefix, otherwise False.

See also

char.startswith


numpy.core.defchararray.chararray.strip

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.startswith

Next topic

numpy.core.defchararray.chararray.swapaxes

numpy.core.defchararray.chararray.strip

chararray.strip(chars=None) [source]

For each element in self, return a copy with the leading and trailing characters removed.

See also

char.strip


numpy.core.defchararray.chararray.swapaxes

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.strip

Next topic

numpy.core.defchararray.chararray.swapcase

numpy.core.defchararray.chararray.swapaxes

chararray.swapaxes(axis1, axis2)

Return a view of the array with axis1 and axis2 interchanged.

Refer to numpy.swapaxes for full documentation.

See also

numpy.swapaxes
equivalent function


numpy.core.defchararray.chararray.swapcase

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.swapaxes

Next topic

numpy.core.defchararray.chararray.take

numpy.core.defchararray.chararray.swapcase

chararray.swapcase() [source]

For each element in self, return a copy of the string with uppercase characters converted to lowercase and vice versa.

See also

char.swapcase


numpy.core.defchararray.chararray.take

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.swapcase

Next topic

numpy.core.defchararray.chararray.title

numpy.core.defchararray.chararray.take

chararray.take(indices, axis=None, out=None, mode='raise')

Return an array formed from the elements of a at the given indices.

Refer to numpy.take for full documentation.

See also

numpy.take
equivalent function


numpy.core.defchararray.chararray.title

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.take

Next topic

numpy.core.defchararray.chararray.tofile

numpy.core.defchararray.chararray.title

chararray.title() [source]

For each element in self, return a titlecased version of the string: words start with uppercase characters, all remaining cased characters are lowercase.

See also

char.title


numpy.core.defchararray.chararray.tofile

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.title

Next topic

numpy.core.defchararray.chararray.tolist

numpy.core.defchararray.chararray.tofile

chararray.tofile(fid, sep="", format="%s")

Write array to a file as text or binary (default).

Data is always written in ‘C’ order, independent of the order of a. The data produced by this method can be recovered using the function fromfile().

Parameters:

fid : file or str

An open file object, or a string containing a filename.

sep : str

Separator between array items for text output. If “” (empty), a binary file is written, equivalent to file.write(a.tobytes()).

format : str

Format string for text file output. Each entry in the array is formatted to text by first converting it to the closest Python type, and then using “format” % item.

Notes

This is a convenience function for quick storage of array data. Information on endianness and precision is lost, so this method is not a good choice for files intended to archive data or transport data between machines with different endianness. Some of these problems can be overcome by outputting the data as text files, at the expense of speed and file size.


numpy.core.defchararray.chararray.tolist

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.tofile

Next topic

numpy.core.defchararray.chararray.tostring

numpy.core.defchararray.chararray.tolist

chararray.tolist()

Return the array as a (possibly nested) list.

Return a copy of the array data as a (nested) Python list. Data items are converted to the nearest compatible Python type.

Parameters:

none
Returns:

y : list

The possibly nested list of array elements.

Notes

The array may be recreated, a = np.array(a.tolist()).

Examples

>>> a = np.array([1, 2])
>>> a.tolist()
[1, 2]
>>> a = np.array([[1, 2], [3, 4]])
>>> list(a)
[array([1, 2]), array([3, 4])]
>>> a.tolist()
[[1, 2], [3, 4]]


numpy.core.defchararray.chararray.tostring

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.tolist

Next topic

numpy.core.defchararray.chararray.translate

numpy.core.defchararray.chararray.tostring

chararray.tostring(order='C')

Construct Python bytes containing the raw data bytes in the array.

Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.

This function is a compatibility alias for tobytes. Despite its name it returns bytes not strings.

Parameters:

order : {‘C’, ‘F’, None}, optional

Order of the data for multidimensional arrays: C, Fortran, or the same as for the original array.
Returns:

s : bytes

Python bytes exhibiting a copy of a‘s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]])
>>> x.tobytes()
b'\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x03\x00\x00\x00'


numpy.core.defchararray.chararray.translate

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.tostring

Next topic

numpy.core.defchararray.chararray.transpose

numpy.core.defchararray.chararray.translate

chararray.translate(table, deletechars=None) [source]

For each element in self, return a copy of the string where all characters occurring in the optional argument deletechars are removed, and the remaining characters have been mapped through the given translation table.

See also

char.translate


numpy.core.defchararray.chararray.transpose

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.translate

Next topic

numpy.core.defchararray.chararray.upper

numpy.core.defchararray.chararray.transpose

chararray.transpose(*axes)

Returns a view of the array with axes transposed.

For a 1-D array, this has no effect. (To change between column and row vectors, first cast the 1-D array into a matrix object.) For a 2-D array, this is the usual matrix transpose. For an n-D array, if axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided and a.shape = (i[0], i[1], ... i[n-2], i[n-1]), then a.transpose().shape = (i[n-1], i[n-2], ... i[1], i[0]).

Parameters:

axes : None, tuple of ints, or n ints

  • None or no argument: reverses the order of the axes.
  • tuple of ints: i in the j-th place in the tuple means a‘s i-th axis becomes a.transpose()‘s j-th axis.
  • n ints: same as an n-tuple of the same ints (this form is intended simply as a “convenience” alternative to the tuple form)
Returns:

out : ndarray

View of a, with axes suitably permuted.

See also

ndarray.T
Array property returning the array transposed.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> a
array([[1, 2],
       [3, 4]])
>>> a.transpose()
array([[1, 3],
       [2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
       [2, 4]])
>>> a.transpose(1, 0)
array([[1, 3],
       [2, 4]])


numpy.core.defchararray.chararray.upper

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.transpose

Next topic

numpy.core.defchararray.chararray.view

numpy.core.defchararray.chararray.upper

chararray.upper() [source]

Return an array with the elements of self converted to uppercase.

See also

char.upper


numpy.core.defchararray.chararray.view

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.upper

Next topic

numpy.core.defchararray.chararray.zfill

numpy.core.defchararray.chararray.view

chararray.view(dtype=None, type=None)

New view of array with the same data.

Parameters:

dtype : data-type or ndarray sub-class, optional

Data-type descriptor of the returned view, e.g., float32 or int16. The default, None, results in the view having the same data-type as a. This argument can also be specified as an ndarray sub-class, which then specifies the type of the returned object (this is equivalent to setting the type parameter).

type : Python type, optional

Type of the returned view, e.g., ndarray or matrix. Again, the default None results in type preservation.

Notes

a.view() is used two different ways:

a.view(some_dtype) or a.view(dtype=some_dtype) constructs a view of the array’s memory with a different data-type. This can cause a reinterpretation of the bytes of memory.

a.view(ndarray_subclass) or a.view(type=ndarray_subclass) just returns an instance of ndarray_subclass that looks at the same array (same shape, dtype, etc.) This does not cause a reinterpretation of the memory.

For a.view(some_dtype), if some_dtype has a different number of bytes per entry than the previous dtype (for example, converting a regular array to a structured array), then the behavior of the view cannot be predicted just from the superficial appearance of a (shown by print(a)). It also depends on exactly how a is stored in memory. Therefore if a is C-ordered versus fortran-ordered, versus defined as a slice or transpose, etc., the view may give different results.

Examples

>>> x = np.array([(1, 2)], dtype=[('a', np.int8), ('b', np.int8)])

Viewing array data using a different type and dtype:

>>> y = x.view(dtype=np.int16, type=np.matrix)
>>> y
matrix([[513]], dtype=int16)
>>> print type(y)
<class 'numpy.matrixlib.defmatrix.matrix'>

Creating a view on a structured array so it can be used in calculations

>>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)])
>>> xv = x.view(dtype=np.int8).reshape(-1,2)
>>> xv
array([[1, 2],
       [3, 4]], dtype=int8)
>>> xv.mean(0)
array([ 2.,  3.])

Making changes to the view changes the underlying array

>>> xv[0,1] = 20
>>> print x
[(1, 20) (3, 4)]

Using a view to convert an array to a record array:

>>> z = x.view(np.recarray)
>>> z.a
array([1], dtype=int8)

Views share data:

>>> x[0] = (9, 10)
>>> z[0]
(9, 10)

Views that change the dtype size (bytes per entry) should normally be avoided on arrays defined by slices, transposes, fortran-ordering, etc.:

>>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16)
>>> y = x[:, 0:2]
>>> y
array([[1, 2],
       [4, 5]], dtype=int16)
>>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: new type not compatible with array.
>>> z = y.copy()
>>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
array([[(1, 2)],
       [(4, 5)]], dtype=[('width', '<i2'), ('length', '<i2')])


numpy.core.defchararray.chararray.zfill

  • String operations
  • numpy.core.defchararray.chararray
  • index
  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.view

Next topic

C-Types Foreign Function Interface (numpy.ctypeslib)

numpy.core.defchararray.chararray.zfill

chararray.zfill(width) [source]

Return the numeric string left-filled with zeros in a string of length width.

See also

char.zfill


C-Types Foreign Function Interface (numpy.ctypeslib)

  • next
  • previous

Previous topic

numpy.core.defchararray.chararray.zfill

Next topic

Datetime Support Functions

C-Types Foreign Function Interface (numpy.ctypeslib)

numpy.ctypeslib.as_array(obj, shape=None) [source]

Create a numpy array from a ctypes array or a ctypes POINTER. The numpy array shares the memory with the ctypes object.

The size parameter must be given if converting from a ctypes POINTER. The size parameter is ignored if converting from a ctypes array

numpy.ctypeslib.as_ctypes(obj) [source]

Create and return a ctypes object from a numpy array. Actually anything that exposes the __array_interface__ is accepted.

numpy.ctypeslib.ctypes_load_library(*args, **kwds) [source]

ctypes_load_library is deprecated, use load_library instead!

numpy.ctypeslib.load_library(libname, loader_path) [source]
numpy.ctypeslib.ndpointer(dtype=None, ndim=None, shape=None, flags=None) [source]

Array-checking restype/argtypes.

An ndpointer instance is used to describe an ndarray in restypes and argtypes specifications. This approach is more flexible than using, for example, POINTER(c_double), since several restrictions can be specified, which are verified upon calling the ctypes function. These include data type, number of dimensions, shape and flags. If a given array does not satisfy the specified restrictions, a TypeError is raised.

Parameters:

dtype : data-type, optional

Array data-type.

ndim : int, optional

Number of array dimensions.

shape : tuple of ints, optional

Array shape.

flags : str or tuple of str

Array flags; may be one or more of:

  • C_CONTIGUOUS / C / CONTIGUOUS
  • F_CONTIGUOUS / F / FORTRAN
  • OWNDATA / O
  • WRITEABLE / W
  • ALIGNED / A
  • UPDATEIFCOPY / U
Returns:

klass : ndpointer type object

A type object, which is an _ndtpr instance containing dtype, ndim, shape and flags information.
Raises:

TypeError

If a given array does not satisfy the specified restrictions.

Examples

>>> clib.somefunc.argtypes = [np.ctypeslib.ndpointer(dtype=np.float64,
...                                                  ndim=1,
...                                                  flags='C_CONTIGUOUS')]
...
>>> clib.somefunc(np.array([1, 2, 3], dtype=np.float64))
...


Datetime Support Functions

  • next
  • previous

Table Of Contents

  • Datetime Support Functions
    • Business Day Functions

Previous topic

C-Types Foreign Function Interface (numpy.ctypeslib)

Next topic

numpy.busdaycalendar

Datetime Support Functions

Business Day Functions

busdaycalendar | A business day calendar object that efficiently stores information defining valid days for the busday family of functions.
is_busday(dates[, weekmask, holidays, ...]) | Calculates which of the given dates are valid days, and which are not.
busday_offset(dates, offsets[, roll, ...]) | First adjusts the date to fall on a valid day according to the roll rule, then applies offsets to the given dates counted in valid days.
busday_count(begindates, enddates[, ...]) | Counts the number of valid days between begindates and enddates, not including the day of enddates.


numpy.busdaycalendar

  • Datetime Support Functions
  • next
  • previous

Previous topic

numpy.busday_count

Next topic

numpy.busdaycalendar.weekmask

numpy.busdaycalendar

class numpy.busdaycalendar [source]

A business day calendar object that efficiently stores information defining valid days for the busday family of functions.

The default valid days are Monday through Friday (“business days”). A busdaycalendar object can be specified with any set of weekly valid days, plus an optional “holiday” dates that always will be invalid.

Once a busdaycalendar object is created, the weekmask and holidays cannot be modified.

New in version 1.7.0.

Parameters:

weekmask : str or array_like of bool, optional

A seven-element array indicating which of Monday through Sunday are valid days. May be specified as a length-seven list or array, like [1,1,1,1,1,0,0]; a length-seven string, like ‘1111100’; or a string like “Mon Tue Wed Thu Fri”, made up of 3-character abbreviations for weekdays, optionally separated by white space. Valid abbreviations are: Mon Tue Wed Thu Fri Sat Sun

holidays : array_like of datetime64[D], optional

An array of dates to consider as invalid dates, no matter which weekday they fall upon. Holiday dates may be specified in any order, and NaT (not-a-time) dates are ignored. This list is saved in a normalized form that is suited for fast calculations of valid days.
Returns:

out : busdaycalendar

A business day calendar object containing the specified weekmask and holidays values.

See also

is_busday
Returns a boolean array indicating valid days.
busday_offset
Applies an offset counted in valid days.
busday_count
Counts how many valid days are in a half-open date range.

Examples

>>> # Some important days in July
... bdd = np.busdaycalendar(
...             holidays=['2011-07-01', '2011-07-04', '2011-07-17'])
>>> # Default is Monday to Friday weekdays
... bdd.weekmask
array([ True,  True,  True,  True,  True, False, False], dtype='bool')
>>> # Any holidays already on the weekend are removed
... bdd.holidays
array(['2011-07-01', '2011-07-04'], dtype='datetime64[D]')

Attributes

weekmask | A copy of the seven-element boolean mask indicating valid days.
holidays | A copy of the holiday array indicating additional invalid days.
Note: once a busdaycalendar object is created, you cannot modify the
weekmask or holidays. The attributes return copies of internal data.


numpy.busdaycalendar.weekmask

  • Datetime Support Functions
  • numpy.busdaycalendar
  • index
  • next
  • previous

Previous topic

numpy.busdaycalendar

Next topic

numpy.busdaycalendar.holidays

numpy.busdaycalendar.weekmask

busdaycalendar.weekmask

A copy of the seven-element boolean mask indicating valid days.


numpy.busdaycalendar.holidays

  • Datetime Support Functions
  • numpy.busdaycalendar
  • index
  • next
  • previous

Previous topic

numpy.busdaycalendar.weekmask

Next topic

numpy.is_busday

numpy.busdaycalendar.holidays

busdaycalendar.holidays

A copy of the holiday array indicating additional invalid days.


numpy.is_busday

  • Datetime Support Functions
  • next
  • previous

Previous topic

numpy.busdaycalendar.holidays

Next topic

numpy.busday_offset

numpy.is_busday

numpy.is_busday(dates, weekmask='1111100', holidays=None, busdaycal=None, out=None)

Calculates which of the given dates are valid days, and which are not.

New in version 1.7.0.

Parameters:

dates : array_like of datetime64[D]

The array of dates to process.

weekmask : str or array_like of bool, optional

A seven-element array indicating which of Monday through Sunday are valid days. May be specified as a length-seven list or array, like [1,1,1,1,1,0,0]; a length-seven string, like ‘1111100’; or a string like “Mon Tue Wed Thu Fri”, made up of 3-character abbreviations for weekdays, optionally separated by white space. Valid abbreviations are: Mon Tue Wed Thu Fri Sat Sun

holidays : array_like of datetime64[D], optional

An array of dates to consider as invalid dates. They may be specified in any order, and NaT (not-a-time) dates are ignored. This list is saved in a normalized form that is suited for fast calculations of valid days.

busdaycal : busdaycalendar, optional

A busdaycalendar object which specifies the valid days. If this parameter is provided, neither weekmask nor holidays may be provided.

out : array of bool, optional

If provided, this array is filled with the result.
Returns:

out : array of bool

An array with the same shape as dates, containing True for each valid day, and False for each invalid day.

See also

busdaycalendar
An object that specifies a custom set of valid days.
busday_offset
Applies an offset counted in valid days.
busday_count
Counts how many valid days are in a half-open date range.

Examples

>>> # The weekdays are Friday, Saturday, and Monday
... np.is_busday(['2011-07-01', '2011-07-02', '2011-07-18'],
...                 holidays=['2011-07-01', '2011-07-04', '2011-07-17'])
array([False, False,  True], dtype='bool')


numpy.busday_offset

  • Datetime Support Functions
  • next
  • previous

Previous topic

numpy.is_busday

Next topic

numpy.busday_count

numpy.busday_offset

numpy.busday_offset(dates, offsets, roll='raise', weekmask='1111100', holidays=None, busdaycal=None, out=None)

First adjusts the date to fall on a valid day according to the roll rule, then applies offsets to the given dates counted in valid days.

New in version 1.7.0.

Parameters:

dates : array_like of datetime64[D]

The array of dates to process.

offsets : array_like of int

The array of offsets, which is broadcast with dates.

roll : {‘raise’, ‘nat’, ‘forward’, ‘following’, ‘backward’, ‘preceding’, ‘modifiedfollowing’, ‘modifiedpreceding’}, optional

How to treat dates that do not fall on a valid day. The default is ‘raise’.

  • ‘raise’ means to raise an exception for an invalid day.
  • ‘nat’ means to return a NaT (not-a-time) for an invalid day.
  • ‘forward’ and ‘following’ mean to take the first valid day later in time.
  • ‘backward’ and ‘preceding’ mean to take the first valid day earlier in time.
  • ‘modifiedfollowing’ means to take the first valid day later in time unless it is across a Month boundary, in which case to take the first valid day earlier in time.
  • ‘modifiedpreceding’ means to take the first valid day earlier in time unless it is across a Month boundary, in which case to take the first valid day later in time.

weekmask : str or array_like of bool, optional

A seven-element array indicating which of Monday through Sunday are valid days. May be specified as a length-seven list or array, like [1,1,1,1,1,0,0]; a length-seven string, like ‘1111100’; or a string like “Mon Tue Wed Thu Fri”, made up of 3-character abbreviations for weekdays, optionally separated by white space. Valid abbreviations are: Mon Tue Wed Thu Fri Sat Sun

holidays : array_like of datetime64[D], optional

An array of dates to consider as invalid dates. They may be specified in any order, and NaT (not-a-time) dates are ignored. This list is saved in a normalized form that is suited for fast calculations of valid days.

busdaycal : busdaycalendar, optional

A busdaycalendar object which specifies the valid days. If this parameter is provided, neither weekmask nor holidays may be provided.

out : array of datetime64[D], optional

If provided, this array is filled with the result.
Returns:

out : array of datetime64[D]

An array with a shape from broadcasting dates and offsets together, containing the dates with offsets applied.

See also

busdaycalendar
An object that specifies a custom set of valid days.
is_busday
Returns a boolean array indicating valid days.
busday_count
Counts how many valid days are in a half-open date range.

Examples

>>> # First business day in October 2011 (not accounting for holidays)
... np.busday_offset('2011-10', 0, roll='forward')
numpy.datetime64('2011-10-03','D')
>>> # Last business day in February 2012 (not accounting for holidays)
... np.busday_offset('2012-03', -1, roll='forward')
numpy.datetime64('2012-02-29','D')
>>> # Third Wednesday in January 2011
... np.busday_offset('2011-01', 2, roll='forward', weekmask='Wed')
numpy.datetime64('2011-01-19','D')
>>> # 2012 Mother's Day in Canada and the U.S.
... np.busday_offset('2012-05', 1, roll='forward', weekmask='Sun')
numpy.datetime64('2012-05-13','D')

>>> # First business day on or after a date
... np.busday_offset('2011-03-20', 0, roll='forward')
numpy.datetime64('2011-03-21','D')
>>> np.busday_offset('2011-03-22', 0, roll='forward')
numpy.datetime64('2011-03-22','D')
>>> # First business day after a date
... np.busday_offset('2011-03-20', 1, roll='backward')
numpy.datetime64('2011-03-21','D')
>>> np.busday_offset('2011-03-22', 1, roll='backward')
numpy.datetime64('2011-03-23','D')


numpy.busday_count

  • Datetime Support Functions
  • next
  • previous

Previous topic

numpy.busday_offset

Next topic

Data type routines

numpy.busday_count

numpy.busday_count(begindates, enddates, weekmask='1111100', holidays=[], busdaycal=None, out=None)

Counts the number of valid days between begindates and enddates, not including the day of enddates.

If enddates specifies a date value that is earlier than the corresponding begindates date value, the count will be negative.

New in version 1.7.0.

Parameters:

begindates : array_like of datetime64[D]

The array of the first dates for counting.

enddates : array_like of datetime64[D]

The array of the end dates for counting, which are excluded from the count themselves.

weekmask : str or array_like of bool, optional

A seven-element array indicating which of Monday through Sunday are valid days. May be specified as a length-seven list or array, like [1,1,1,1,1,0,0]; a length-seven string, like ‘1111100’; or a string like “Mon Tue Wed Thu Fri”, made up of 3-character abbreviations for weekdays, optionally separated by white space. Valid abbreviations are: Mon Tue Wed Thu Fri Sat Sun

holidays : array_like of datetime64[D], optional

An array of dates to consider as invalid dates. They may be specified in any order, and NaT (not-a-time) dates are ignored. This list is saved in a normalized form that is suited for fast calculations of valid days.

busdaycal : busdaycalendar, optional

A busdaycalendar object which specifies the valid days. If this parameter is provided, neither weekmask nor holidays may be provided.

out : array of int, optional

If provided, this array is filled with the result.
Returns:

out : array of int

An array with a shape from broadcasting begindates and enddates together, containing the number of valid days between the begin and end dates.

See also

busdaycalendar
An object that specifies a custom set of valid days.
is_busday
Returns a boolean array indicating valid days.
busday_offset
Applies an offset counted in valid days.

Examples

>>> # Number of weekdays in January 2011
... np.busday_count('2011-01', '2011-02')
21
>>> # Number of weekdays in 2011
...  np.busday_count('2011', '2012')
260
>>> # Number of Saturdays in 2011
... np.busday_count('2011', '2012', weekmask='Sat')
53


Data type routines

  • next
  • previous

Table Of Contents

  • Data type routines
    • Creating data types
    • Data type information
    • Data type testing
    • Miscellaneous

Previous topic

numpy.busday_count

Next topic

numpy.can_cast

Data type routines

can_cast(from, totype, casting = ) | Returns True if cast between data types can occur according to the casting rule.
promote_types(type1, type2) | Returns the data type with the smallest size and smallest scalar kind to which both type1 and type2 may be safely cast.
min_scalar_type(a) | For scalar a, returns the data type with the smallest size and smallest scalar kind which can hold its value.
result_type(*arrays_and_dtypes) | Returns the type that results from applying the NumPy type promotion rules to the arguments.
common_type(*arrays) | Return a scalar type which is common to the input arrays.
obj2sctype(rep[, default]) | Return the scalar dtype or NumPy equivalent of Python type of an object.

Creating data types

dtype | Create a data type object.
format_parser(formats, names, titles[, ...]) | Class to convert formats, names, titles description to a dtype.

Data type information

finfo | Machine limits for floating point types.
iinfo(type) | Machine limits for integer types.
MachAr([float_conv, int_conv, ...]) | Diagnosing machine parameters.

Data type testing

issctype(rep) | Determines whether the given object represents a scalar data-type.
issubdtype(arg1, arg2) | Returns True if first argument is a typecode lower/equal in type hierarchy.
issubsctype(arg1, arg2) | Determine if the first argument is a subclass of the second argument.
issubclass_(arg1, arg2) | Determine if a class is a subclass of a second class.
find_common_type(array_types, scalar_types) | Determine common type following standard coercion rules.

Miscellaneous

typename(char) | Return a description for the given data type code.
sctype2char(sctype) | Return the string representation of a scalar dtype.
mintypecode(typechars[, typeset, default]) | Return the character for the minimum-size type to which given types can be safely cast.


numpy.can_cast

  • Data type routines
  • next
  • previous

Previous topic

numpy.mintypecode

Next topic

numpy.promote_types

numpy.can_cast

numpy.can_cast(from, totype, casting = 'safe')

Returns True if cast between data types can occur according to the casting rule. If from is a scalar or array scalar, also returns True if the scalar value can be cast without overflow or truncation to an integer.

Parameters:

from : dtype, dtype specifier, scalar, or array

Data type, scalar, or array to cast from.

totype : dtype or dtype specifier

Data type to cast to.

casting : {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

Controls what kind of data casting may occur.

  • ‘no’ means the data types should not be cast at all.
  • ‘equiv’ means only byte-order changes are allowed.
  • ‘safe’ means only casts which can preserve values are allowed.
  • ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.
  • ‘unsafe’ means any data conversions may be done.
Returns:

out : bool

True if cast can occur according to the casting rule.

See also

dtype, result_type

Notes

Starting in NumPy 1.9, can_cast function now returns False in ‘safe’ casting mode for integer/float dtype and string dtype if the string dtype length is not long enough to store the max integer/float value converted to a string. Previously can_cast in ‘safe’ mode returned True for integer/float dtype and a string dtype of any length.

Examples

Basic examples

>>> np.can_cast(np.int32, np.int64)
True
>>> np.can_cast(np.float64, np.complex)
True
>>> np.can_cast(np.complex, np.float)
False

>>> np.can_cast('i8', 'f8')
True
>>> np.can_cast('i8', 'f4')
False
>>> np.can_cast('i4', 'S4')
False

Casting scalars

>>> np.can_cast(100, 'i1')
True
>>> np.can_cast(150, 'i1')
False
>>> np.can_cast(150, 'u1')
True

>>> np.can_cast(3.5e100, np.float32)
False
>>> np.can_cast(1000.0, np.float32)
True

Array scalar checks the value, array does not

>>> np.can_cast(np.array(1000.0), np.float32)
True
>>> np.can_cast(np.array([1000.0]), np.float32)
False

Using the casting rules

>>> np.can_cast('i8', 'i8', 'no')
True
>>> np.can_cast('<i8', '>i8', 'no')
False

>>> np.can_cast('<i8', '>i8', 'equiv')
True
>>> np.can_cast('<i4', '>i8', 'equiv')
False

>>> np.can_cast('<i4', '>i8', 'safe')
True
>>> np.can_cast('<i8', '>i4', 'safe')
False

>>> np.can_cast('<i8', '>i4', 'same_kind')
True
>>> np.can_cast('<i8', '>u4', 'same_kind')
False

>>> np.can_cast('<i8', '>u4', 'unsafe')
True


numpy.promote_types

  • Data type routines
  • next
  • previous

Previous topic

numpy.can_cast

Next topic

numpy.min_scalar_type

numpy.promote_types

numpy.promote_types(type1, type2)

Returns the data type with the smallest size and smallest scalar kind to which both type1 and type2 may be safely cast. The returned data type is always in native byte order.

This function is symmetric and associative.

Parameters:

type1 : dtype or dtype specifier

First data type.

type2 : dtype or dtype specifier

Second data type.
Returns:

out : dtype

The promoted data type.

See also

result_type, dtype, can_cast

Notes

New in version 1.6.0.

Starting in NumPy 1.9, promote_types function now returns a valid string length when given an integer or float dtype as one argument and a string dtype as another argument. Previously it always returned the input string dtype, even if it wasn’t long enough to store the max integer/float value converted to a string.

Examples

>>> np.promote_types('f4', 'f8')
dtype('float64')

>>> np.promote_types('i8', 'f4')
dtype('float64')

>>> np.promote_types('>i8', '<c8')
dtype('complex128')

>>> np.promote_types('i4', 'S8')
dtype('S11')


numpy.min_scalar_type

  • Data type routines
  • next
  • previous

Previous topic

numpy.promote_types

Next topic

numpy.result_type

numpy.min_scalar_type

numpy.min_scalar_type(a)

For scalar a, returns the data type with the smallest size and smallest scalar kind which can hold its value. For non-scalar array a, returns the vector’s dtype unmodified.

Floating point values are not demoted to integers, and complex values are not demoted to floats.

Parameters:

a : scalar or array_like

The value whose minimal data type is to be found.
Returns:

out : dtype

The minimal data type.

See also

result_type, promote_types, dtype, can_cast

Notes

New in version 1.6.0.

Examples

>>> np.min_scalar_type(10)
dtype('uint8')

>>> np.min_scalar_type(-260)
dtype('int16')

>>> np.min_scalar_type(3.1)
dtype('float16')

>>> np.min_scalar_type(1e50)
dtype('float64')

>>> np.min_scalar_type(np.arange(4,dtype='f8'))
dtype('float64')


numpy.result_type

  • Data type routines
  • next
  • previous

Previous topic

numpy.min_scalar_type

Next topic

numpy.common_type

numpy.result_type

numpy.result_type(*arrays_and_dtypes)

Returns the type that results from applying the NumPy type promotion rules to the arguments.

Type promotion in NumPy works similarly to the rules in languages like C++, with some slight differences. When both scalars and arrays are used, the array’s type takes precedence and the actual value of the scalar is taken into account.

For example, calculating 3*a, where a is an array of 32-bit floats, intuitively should result in a 32-bit float output. If the 3 is a 32-bit integer, the NumPy rules indicate it can’t convert losslessly into a 32-bit float, so a 64-bit float should be the result type. By examining the value of the constant, ‘3’, we see that it fits in an 8-bit integer, which can be cast losslessly into the 32-bit float.

Parameters:

arrays_and_dtypes : list of arrays and dtypes

The operands of some operation whose result type is needed.
Returns:

out : dtype

The result type.

See also

dtype, promote_types, min_scalar_type, can_cast

Notes

New in version 1.6.0.

The specific algorithm used is as follows.

Categories are determined by first checking which of boolean, integer (int/uint), or floating point (float/complex) the maximum kind of all the arrays and the scalars are.

If there are only scalars or the maximum category of the scalars is higher than the maximum category of the arrays, the data types are combined with promote_types to produce the return value.

Otherwise, min_scalar_type is called on each array, and the resulting data types are all combined with promote_types to produce the return value.

The set of int values is not a subset of the uint values for types with the same number of bits, something not reflected in min_scalar_type, but handled as a special case in result_type.

Examples

>>> np.result_type(3, np.arange(7, dtype='i1'))
dtype('int8')

>>> np.result_type('i4', 'c8')
dtype('complex128')

>>> np.result_type(3.0, -2)
dtype('float64')


numpy.common_type

  • Data type routines
  • next
  • previous

Previous topic

numpy.result_type

Next topic

numpy.obj2sctype

numpy.common_type

numpy.common_type(*arrays) [source]

Return a scalar type which is common to the input arrays.

The return type will always be an inexact (i.e. floating point) scalar type, even if all the arrays are integer arrays. If one of the inputs is an integer array, the minimum precision type that is returned is a 64-bit floating point dtype.

All input arrays can be safely cast to the returned dtype without loss of information.

Parameters:

array1, array2, ... : ndarrays

Input arrays.
Returns:

out : data type code

Data type code.

See also

dtype, mintypecode

Examples

>>> np.common_type(np.arange(2, dtype=np.float32))
<type 'numpy.float32'>
>>> np.common_type(np.arange(2, dtype=np.float32), np.arange(2))
<type 'numpy.float64'>
>>> np.common_type(np.arange(4), np.array([45, 6.j]), np.array([45.0]))
<type 'numpy.complex128'>


numpy.obj2sctype

  • Data type routines
  • next
  • previous

Previous topic

numpy.common_type

Next topic

numpy.dtype

numpy.obj2sctype

numpy.obj2sctype(rep, default=None) [source]

Return the scalar dtype or NumPy equivalent of Python type of an object.

Parameters:

rep : any

The object of which the type is returned.

default : any, optional

If given, this is returned for objects whose types can not be determined. If not given, None is returned for those objects.
Returns:

dtype : dtype or Python type

The data type of rep.

See also

sctype2char, issctype, issubsctype, issubdtype, maximum_sctype

Examples

>>> np.obj2sctype(np.int32)
<type 'numpy.int32'>
>>> np.obj2sctype(np.array([1., 2.]))
<type 'numpy.float64'>
>>> np.obj2sctype(np.array([1.j]))
<type 'numpy.complex128'>

>>> np.obj2sctype(dict)
<type 'numpy.object_'>
>>> np.obj2sctype('string')
<type 'numpy.string_'>

>>> np.obj2sctype(1, default=list)
<type 'list'>


numpy.format_parser

  • Data type routines
  • next
  • previous

Previous topic

numpy.dtype.newbyteorder

Next topic

numpy.finfo

numpy.format_parser

class numpy.format_parser(formats, names, titles, aligned=False, byteorder=None) [source]

Class to convert formats, names, titles description to a dtype.

After constructing the format_parser object, the dtype attribute is the converted data-type: dtype = format_parser(formats, names, titles).dtype

Parameters:

formats : str or list of str

The format description, either specified as a string with comma-separated format descriptions in the form 'f8, i4, a5', or a list of format description strings in the form ['f8', 'i4', 'a5'].

names : str or list/tuple of str

The field names, either specified as a comma-separated string in the form 'col1, col2, col3', or as a list or tuple of strings in the form ['col1', 'col2', 'col3']. An empty list can be used, in that case default field names (‘f0’, ‘f1’, ...) are used.

titles : sequence

Sequence of title strings. An empty list can be used to leave titles out.

aligned : bool, optional

If True, align the fields by padding as the C-compiler would. Default is False.

byteorder : str, optional

If specified, all the fields will be changed to the provided byte-order. Otherwise, the default byte-order is used. For all available string specifiers, see dtype.newbyteorder.

See also

dtype, typename, sctype2char

Examples

>>> np.format_parser(['f8', 'i4', 'a5'], ['col1', 'col2', 'col3'],
...                  ['T1', 'T2', 'T3']).dtype
dtype([(('T1', 'col1'), '<f8'), (('T2', 'col2'), '<i4'),
       (('T3', 'col3'), '|S5')])

names and/or titles can be empty lists. If titles is an empty list, titles will simply not appear. If names is empty, default field names will be used.

>>> np.format_parser(['f8', 'i4', 'a5'], ['col1', 'col2', 'col3'],
...                  []).dtype
dtype([('col1', '<f8'), ('col2', '<i4'), ('col3', '|S5')])
>>> np.format_parser(['f8', 'i4', 'a5'], [], []).dtype
dtype([('f0', '<f8'), ('f1', '<i4'), ('f2', '|S5')])

Attributes

dtype (dtype) The converted data-type.


numpy.finfo

  • Data type routines
  • next
  • previous

Previous topic

numpy.format_parser

Next topic

numpy.iinfo

numpy.finfo

class numpy.finfo [source]

Machine limits for floating point types.

Parameters:

dtype : float, dtype, or instance

Kind of floating point data-type about which to get information.

See also

MachAr
The implementation of the tests that produce this information.
iinfo
The equivalent for integer data types.

Notes

For developers of NumPy: do not instantiate this at the module level. The initial calculation of these parameters is expensive and negatively impacts import times. These objects are cached, so calling finfo() repeatedly inside your functions is not a problem.

Attributes

eps | (float) The smallest representable positive number such that 1.0 + eps != 1.0. Type of eps is an appropriate floating point type.
epsneg | (floating point number of the appropriate type) The smallest representable positive number such that 1.0 - epsneg != 1.0.
iexp | (int) The number of bits in the exponent portion of the floating point representation.
machar | (MachAr) The object which calculated these parameters and holds more detailed information.
machep | (int) The exponent that yields eps.
max | (floating point number of the appropriate type) The largest representable number.
maxexp | (int) The smallest positive power of the base (2) that causes overflow.
min | (floating point number of the appropriate type) The smallest representable number, typically -max.
minexp | (int) The most negative power of the base (2) consistent with there being no leading 0’s in the mantissa.
negep | (int) The exponent that yields epsneg.
nexp | (int) The number of bits in the exponent including its sign and bias.
nmant | (int) The number of bits in the mantissa.
precision | (int) The approximate number of decimal digits to which this kind of float is precise.
resolution | (floating point number of the appropriate type) The approximate decimal resolution of this type, i.e., 10**-precision.
tiny | (float) The smallest positive usable number. Type of tiny is an appropriate floating point type.


numpy.iinfo

  • Data type routines
  • next
  • previous

Previous topic

numpy.finfo

Next topic

numpy.iinfo.min

numpy.iinfo

class numpy.iinfo(type) [source]

Machine limits for integer types.

Parameters:

type : integer type, dtype, or instance

The kind of integer data type to get information about.

See also

finfo
The equivalent for floating point data types.

Examples

With types:

>>> ii16 = np.iinfo(np.int16)
>>> ii16.min
-32768
>>> ii16.max
32767
>>> ii32 = np.iinfo(np.int32)
>>> ii32.min
-2147483648
>>> ii32.max
2147483647

With instances:

>>> ii32 = np.iinfo(np.int32(10))
>>> ii32.min
-2147483648
>>> ii32.max
2147483647

Attributes

min | Minimum value of given dtype.
max | Maximum value of given dtype.


numpy.iinfo.min

  • Data type routines
  • numpy.iinfo
  • index
  • next
  • previous

Previous topic

numpy.iinfo

Next topic

numpy.iinfo.max

numpy.iinfo.min

iinfo.min

Minimum value of given dtype.


numpy.iinfo.max

  • Data type routines
  • numpy.iinfo
  • index
  • next
  • previous

Previous topic

numpy.iinfo.min

Next topic

numpy.MachAr

numpy.iinfo.max

iinfo.max

Maximum value of given dtype.


numpy.MachAr

  • Data type routines
  • next
  • previous

Previous topic

numpy.iinfo.max

Next topic

numpy.issctype

numpy.MachAr

class numpy.MachAr(float_conv=<type 'float'>, int_conv=<type 'int'>, float_to_float=<type 'float'>, float_to_str=<function <lambda> at 0x00000000045742E8>, title='Python floating point number') [source]

Diagnosing machine parameters.

Parameters:

float_conv : function, optional

Function that converts an integer or integer array to a float or float array. Default is float.

int_conv : function, optional

Function that converts a float or float array to an integer or integer array. Default is int.

float_to_float : function, optional

Function that converts a float array to float. Default is float. Note that this does not seem to do anything useful in the current implementation.

float_to_str : function, optional

Function that converts a single float to a string. Default is lambda v:'%24.16e' %v.

title : str, optional

Title that is printed in the string representation of MachAr.

See also

finfo
Machine limits for floating point types.
iinfo
Machine limits for integer types.

References

[R1] Press, Teukolsky, Vetterling and Flannery, “Numerical Recipes in C++,” 2nd ed, Cambridge University Press, 2002, p. 31.

Attributes

ibeta | (int) Radix in which numbers are represented.
it | (int) Number of base-ibeta digits in the floating point mantissa M.
machep | (int) Exponent of the smallest (most negative) power of ibeta that, added to 1.0, gives something different from 1.0
eps | (float) Floating-point number beta**machep (floating point precision)
negep | (int) Exponent of the smallest power of ibeta that, substracted from 1.0, gives something different from 1.0.
epsneg | (float) Floating-point number beta**negep.
iexp | (int) Number of bits in the exponent (including its sign and bias).
minexp | (int) Smallest (most negative) power of ibeta consistent with there being no leading zeros in the mantissa.
xmin | (float) Floating point number beta**minexp (the smallest [in magnitude] usable floating value).
maxexp | (int) Smallest (positive) power of ibeta that causes overflow.
xmax | (float) (1-epsneg) * beta**maxexp (the largest [in magnitude] usable floating value).
irnd | (int) In range(6), information on what kind of rounding is done in addition, and on how underflow is handled.
ngrd | (int) Number of ‘guard digits’ used when truncating the product of two mantissas to fit the representation.
epsilon | (float) Same as eps.
tiny | (float) Same as xmin.
huge | (float) Same as xmax.
precision | (float) - int(-log10(eps))
resolution | (float) - 10**(-precision)


numpy.issctype

  • Data type routines
  • next
  • previous

Previous topic

numpy.MachAr

Next topic

numpy.issubdtype

numpy.issctype

numpy.issctype(rep) [source]

Determines whether the given object represents a scalar data-type.

Parameters:

rep : any

If rep is an instance of a scalar dtype, True is returned. If not, False is returned.
Returns:

out : bool

Boolean result of check whether rep is a scalar dtype.

See also

issubsctype, issubdtype, obj2sctype, sctype2char

Examples

>>> np.issctype(np.int32)
True
>>> np.issctype(list)
False
>>> np.issctype(1.1)
False

Strings are also a scalar type:

>>> np.issctype(np.dtype('str'))
True


numpy.issubdtype

  • Data type routines
  • next
  • previous

Previous topic

numpy.issctype

Next topic

numpy.issubsctype

numpy.issubdtype

numpy.issubdtype(arg1, arg2) [source]

Returns True if first argument is a typecode lower/equal in type hierarchy.

Parameters:

arg1, arg2 : dtype_like

dtype or string representing a typecode.
Returns:

out : bool

See also

issubsctype, issubclass_

numpy.core.numerictypes
Overview of numpy type hierarchy.

Examples

>>> np.issubdtype('S1', str)
True
>>> np.issubdtype(np.float64, np.float32)
False


numpy.issubsctype

  • Data type routines
  • next
  • previous

Previous topic

numpy.issubdtype

Next topic

numpy.issubclass

numpy.issubsctype

numpy.issubsctype(arg1, arg2) [source]

Determine if the first argument is a subclass of the second argument.

Parameters:

arg1, arg2 : dtype or dtype specifier

Data-types.
Returns:

out : bool

The result.

See also

issctype, issubdtype, obj2sctype

Examples

>>> np.issubsctype('S8', str)
True
>>> np.issubsctype(np.array([1]), np.int)
True
>>> np.issubsctype(np.array([1]), np.float)
False


numpy.issubclass

  • Data type routines
  • next
  • previous

Previous topic

numpy.issubsctype

Next topic

numpy.find_common_type

numpy.issubclass

numpy.issubclass_(arg1, arg2) [source]

Determine if a class is a subclass of a second class.

issubclass_ is equivalent to the Python built-in issubclass, except that it returns False instead of raising a TypeError is one of the arguments is not a class.

Parameters:

arg1 : class

Input class. True is returned if arg1 is a subclass of arg2.

arg2 : class or tuple of classes.

Input class. If a tuple of classes, True is returned if arg1 is a subclass of any of the tuple elements.
Returns:

out : bool

Whether arg1 is a subclass of arg2 or not.

See also

issubsctype, issubdtype, issctype

Examples

>>> np.issubclass_(np.int32, np.int)
True
>>> np.issubclass_(np.int32, np.float)
False


numpy.find_common_type

  • Data type routines
  • next
  • previous

Previous topic

numpy.issubclass

Next topic

numpy.typename

numpy.find_common_type

numpy.find_common_type(array_types, scalar_types) [source]

Determine common type following standard coercion rules.

Parameters:

array_types : sequence

A list of dtypes or dtype convertible objects representing arrays.

scalar_types : sequence

A list of dtypes or dtype convertible objects representing scalars.
Returns:

datatype : dtype

The common data type, which is the maximum of array_types ignoring scalar_types, unless the maximum of scalar_types is of a different kind (dtype.kind). If the kind is not understood, then None is returned.

See also

dtype, common_type, can_cast, mintypecode

Examples

>>> np.find_common_type([], [np.int64, np.float32, np.complex])
dtype('complex128')
>>> np.find_common_type([np.int64, np.float32], [])
dtype('float64')

The standard casting rules ensure that a scalar cannot up-cast an array unless the scalar is of a fundamentally different kind of data (i.e. under a different hierarchy in the data type hierarchy) then the array:

>>> np.find_common_type([np.float32], [np.int64, np.float64])
dtype('float32')

Complex is of a different type, so it up-casts the float in the array_types argument:

>>> np.find_common_type([np.float32], [np.complex])
dtype('complex128')

Type specifier strings are convertible to dtypes and can therefore be used instead of dtypes:

>>> np.find_common_type(['f4', 'f4', 'i4'], ['c8'])
dtype('complex128')


numpy.typename

  • Data type routines
  • next
  • previous

Previous topic

numpy.find_common_type

Next topic

numpy.sctype2char

numpy.typename

numpy.typename(char) [source]

Return a description for the given data type code.

Parameters:

char : str

Data type code.
Returns:

out : str

Description of the input data type code.

See also

dtype, typecodes

Examples

>>> typechars = ['S1', '?', 'B', 'D', 'G', 'F', 'I', 'H', 'L', 'O', 'Q',
...              'S', 'U', 'V', 'b', 'd', 'g', 'f', 'i', 'h', 'l', 'q']
>>> for typechar in typechars:
...     print typechar, ' : ', np.typename(typechar)
...
S1  :  character
?  :  bool
B  :  unsigned char
D  :  complex double precision
G  :  complex long double precision
F  :  complex single precision
I  :  unsigned integer
H  :  unsigned short
L  :  unsigned long integer
O  :  object
Q  :  unsigned long long integer
S  :  string
U  :  unicode
V  :  void
b  :  signed char
d  :  double precision
g  :  long precision
f  :  single precision
i  :  integer
h  :  short
l  :  long integer
q  :  long long integer


numpy.sctype2char

  • Data type routines
  • next
  • previous

Previous topic

numpy.typename

Next topic

numpy.mintypecode

numpy.sctype2char

numpy.sctype2char(sctype) [source]

Return the string representation of a scalar dtype.

Parameters:

sctype : scalar dtype or object

If a scalar dtype, the corresponding string character is returned. If an object, sctype2char tries to infer its scalar type and then return the corresponding string character.
Returns:

typechar : str

The string character corresponding to the scalar type.
Raises:

ValueError

If sctype is an object for which the type can not be inferred.

See also

obj2sctype, issctype, issubsctype, mintypecode

Examples

>>> for sctype in [np.int32, np.float, np.complex, np.string_, np.ndarray]:
...     print np.sctype2char(sctype)
l
d
D
S
O

>>> x = np.array([1., 2-1.j])
>>> np.sctype2char(x)
'D'
>>> np.sctype2char(list)
'O'


numpy.mintypecode

  • Data type routines
  • next
  • previous

Previous topic

numpy.sctype2char

Next topic

Optionally Scipy-accelerated routines (numpy.dual)

numpy.mintypecode

numpy.mintypecode(typechars, typeset='GDFgdf', default='d') [source]

Return the character for the minimum-size type to which given types can be safely cast.

The returned type character must represent the smallest size dtype such that an array of the returned type can handle the data from an array of all types in typechars (or if typechars is an array, then its dtype.char).

Parameters:

typechars : list of str or array_like

If a list of strings, each string should represent a dtype. If array_like, the character representation of the array dtype is used.

typeset : str or list of str, optional

The set of characters that the returned character is chosen from. The default set is ‘GDFgdf’.

default : str, optional

The default character, this is returned if none of the characters in typechars matches a character in typeset.
Returns:

typechar : str

The character representing the minimum-size type that was found.

See also

dtype, sctype2char, maximum_sctype

Examples

>>> np.mintypecode(['d', 'f', 'S'])
'd'
>>> x = np.array([1.1, 2-3.j])
>>> np.mintypecode(x)
'D'

>>> np.mintypecode('abceh', default='G')
'G'


Optionally Scipy-accelerated routines (numpy.dual)

  • next
  • previous

Table Of Contents

  • Optionally Scipy-accelerated routines (numpy.dual)
    • Linear algebra
    • FFT
    • Other

Previous topic

numpy.mintypecode

Next topic

Mathematical functions with automatic domain (numpy.emath)

Optionally Scipy-accelerated routines (numpy.dual)

Aliases for functions which may be accelerated by Scipy.

Scipy can be built to use accelerated or otherwise improved libraries for FFTs, linear algebra, and special functions. This module allows developers to transparently support these accelerated functions when scipy is available but still support users who have only installed Numpy.

Linear algebra

cholesky(a) | Cholesky decomposition.
det(a) | Compute the determinant of an array.
eig(a) | Compute the eigenvalues and right eigenvectors of a square array.
eigh(a[, UPLO]) | Return the eigenvalues and eigenvectors of a Hermitian or symmetric matrix.
eigvals(a) | Compute the eigenvalues of a general matrix.
eigvalsh(a[, UPLO]) | Compute the eigenvalues of a Hermitian or real symmetric matrix.
inv(a) | Compute the (multiplicative) inverse of a matrix.
lstsq(a, b[, rcond]) | Return the least-squares solution to a linear matrix equation.
norm(x[, ord, axis]) | Matrix or vector norm.
pinv(a[, rcond]) | Compute the (Moore-Penrose) pseudo-inverse of a matrix.
solve(a, b) | Solve a linear matrix equation, or system of linear scalar equations.
svd(a[, full_matrices, compute_uv]) | Singular Value Decomposition.

FFT

fft(a[, n, axis]) | Compute the one-dimensional discrete Fourier Transform.
fft2(a[, s, axes]) | Compute the 2-dimensional discrete Fourier Transform
fftn(a[, s, axes]) | Compute the N-dimensional discrete Fourier Transform.
ifft(a[, n, axis]) | Compute the one-dimensional inverse discrete Fourier Transform.
ifft2(a[, s, axes]) | Compute the 2-dimensional inverse discrete Fourier Transform.
ifftn(a[, s, axes]) | Compute the N-dimensional inverse discrete Fourier Transform.

Other

i0(x) Modified Bessel function of the first kind, order 0.


Mathematical functions with automatic domain (numpy.emath)

  • next
  • previous

Previous topic

Optionally Scipy-accelerated routines (numpy.dual)

Next topic

Floating point error handling

Mathematical functions with automatic domain (numpy.emath)

Note

numpy.emath is a preferred alias for numpy.lib.scimath, available after numpy is imported.

Wrapper functions to more user-friendly calling of certain math functions whose output data-type is different than the input data-type in certain domains of the input.

For example, for functions like log with branch cuts, the versions in this module provide the mathematically valid answers in the complex plane:

>>> import math
>>> from numpy.lib import scimath
>>> scimath.log(-math.exp(1)) == (1+1j*math.pi)
True

Similarly, sqrt, other base logarithms, power and trig functions are correctly handled. See their respective docstrings for specific examples.


Floating point error handling

  • next
  • previous

Table Of Contents

  • Floating point error handling
    • Setting and getting error handling
    • Internal functions

Previous topic

Mathematical functions with automatic domain (numpy.emath)

Next topic

numpy.seterr

Floating point error handling

Setting and getting error handling

seterr([all, divide, over, under, invalid]) | Set how floating-point errors are handled.
geterr() | Get the current way of handling floating-point errors.
seterrcall(func) | Set the floating-point error callback function or log object.
geterrcall() | Return the current callback function used on floating-point errors.
errstate(**kwargs) | Context manager for floating-point error handling.

Internal functions

seterrobj(errobj) | Set the object that defines floating-point error handling.
geterrobj() | Return the current object that defines floating-point error handling.


numpy.geterr

  • Floating point error handling
  • next
  • previous

Previous topic

numpy.seterr

Next topic

numpy.seterrcall

numpy.geterr

numpy.geterr() [source]

Get the current way of handling floating-point errors.

Returns:

res : dict

A dictionary with keys “divide”, “over”, “under”, and “invalid”, whose values are from the strings “ignore”, “print”, “log”, “warn”, “raise”, and “call”. The keys represent possible floating-point exceptions, and the values define how these exceptions are handled.

See also

geterrcall, seterr, seterrcall

Notes

For complete documentation of the types of floating-point exceptions and treatment options, see seterr.

Examples

>>> np.geterr()
{'over': 'warn', 'divide': 'warn', 'invalid': 'warn',
'under': 'ignore'}
>>> np.arange(3.) / np.arange(3.)
array([ NaN,   1.,   1.])

>>> oldsettings = np.seterr(all='warn', over='raise')
>>> np.geterr()
{'over': 'raise', 'divide': 'warn', 'invalid': 'warn', 'under': 'warn'}
>>> np.arange(3.) / np.arange(3.)
__main__:1: RuntimeWarning: invalid value encountered in divide
array([ NaN,   1.,   1.])


numpy.geterrcall

  • Floating point error handling
  • next
  • previous

Previous topic

numpy.seterrcall

Next topic

numpy.errstate

numpy.geterrcall

numpy.geterrcall() [source]

Return the current callback function used on floating-point errors.

When the error handling for a floating-point error (one of “divide”, “over”, “under”, or “invalid”) is set to ‘call’ or ‘log’, the function that is called or the log instance that is written to is returned by geterrcall. This function or log instance has been set with seterrcall.

Returns:

errobj : callable, log instance or None

The current error handler. If no handler was set through seterrcall, None is returned.

See also

seterrcall, seterr, geterr

Notes

For complete documentation of the types of floating-point exceptions and treatment options, see seterr.

Examples

>>> np.geterrcall()  # we did not yet set a handler, returns None

>>> oldsettings = np.seterr(all='call')
>>> def err_handler(type, flag):
...     print "Floating point error (%s), with flag %s" % (type, flag)
>>> oldhandler = np.seterrcall(err_handler)
>>> np.array([1, 2, 3]) / 0.0
Floating point error (divide by zero), with flag 1
array([ Inf,  Inf,  Inf])

>>> cur_handler = np.geterrcall()
>>> cur_handler is err_handler
True


numpy.errstate

  • Floating point error handling
  • next
  • previous

Previous topic

numpy.geterrcall

Next topic

numpy.seterrobj

numpy.errstate

class numpy.errstate(**kwargs) [source]

Context manager for floating-point error handling.

Using an instance of errstate as a context manager allows statements in that context to execute with a known error handling behavior. Upon entering the context the error handling is set with seterr and seterrcall, and upon exiting it is reset to what it was before.

Parameters:

kwargs : {divide, over, under, invalid}

Keyword arguments. The valid keywords are the possible floating-point exceptions. Each keyword should have a string value that defines the treatment for the particular error. Possible values are {‘ignore’, ‘warn’, ‘raise’, ‘call’, ‘print’, ‘log’}.

See also

seterr, geterr, seterrcall, geterrcall

Notes

The with statement was introduced in Python 2.5, and can only be used there by importing it: from __future__ import with_statement. In earlier Python versions the with statement is not available.

For complete documentation of the types of floating-point exceptions and treatment options, see seterr.

Examples

>>> from __future__ import with_statement  # use 'with' in Python 2.5
>>> olderr = np.seterr(all='ignore')  # Set error handling to known state.

>>> np.arange(3) / 0.
array([ NaN,  Inf,  Inf])
>>> with np.errstate(divide='warn'):
...     np.arange(3) / 0.
...
__main__:2: RuntimeWarning: divide by zero encountered in divide
array([ NaN,  Inf,  Inf])

>>> np.sqrt(-1)
nan
>>> with np.errstate(invalid='raise'):
...     np.sqrt(-1)
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
FloatingPointError: invalid value encountered in sqrt

Outside the context the error handling behavior has not changed:

>>> np.geterr()
{'over': 'warn', 'divide': 'warn', 'invalid': 'warn',
'under': 'ignore'}


numpy.seterrobj

  • Floating point error handling
  • next
  • previous

Previous topic

numpy.errstate

Next topic

numpy.geterrobj

numpy.seterrobj

numpy.seterrobj(errobj)

Set the object that defines floating-point error handling.

The error object contains all information that defines the error handling behavior in Numpy. seterrobj is used internally by the other functions that set error handling behavior (seterr, seterrcall).

Parameters:

errobj : list

The error object, a list containing three elements: [internal numpy buffer size, error mask, error callback function].

The error mask is a single integer that holds the treatment information on all four floating point errors. The information for each error type is contained in three bits of the integer. If we print it in base 8, we can see what treatment is set for “invalid”, “under”, “over”, and “divide” (in that order). The printed string can be interpreted with

  • 0 : ‘ignore’
  • 1 : ‘warn’
  • 2 : ‘raise’
  • 3 : ‘call’
  • 4 : ‘print’
  • 5 : ‘log’

See also

geterrobj, seterr, geterr, seterrcall, geterrcall, getbufsize, setbufsize

Notes

For complete documentation of the types of floating-point exceptions and treatment options, see seterr.

Examples

>>> old_errobj = np.geterrobj()  # first get the defaults
>>> old_errobj
[10000, 0, None]

>>> def err_handler(type, flag):
...     print "Floating point error (%s), with flag %s" % (type, flag)
...
>>> new_errobj = [20000, 12, err_handler]
>>> np.seterrobj(new_errobj)
>>> np.base_repr(12, 8)  # int for divide=4 ('print') and over=1 ('warn')
'14'
>>> np.geterr()
{'over': 'warn', 'divide': 'print', 'invalid': 'ignore', 'under': 'ignore'}
>>> np.geterrcall() is err_handler
True


numpy.geterrobj

  • Floating point error handling
  • next
  • previous

Previous topic

numpy.seterrobj

Next topic

Discrete Fourier Transform (numpy.fft)

numpy.geterrobj

numpy.geterrobj()

Return the current object that defines floating-point error handling.

The error object contains all information that defines the error handling behavior in Numpy. geterrobj is used internally by the other functions that get and set error handling behavior (geterr, seterr, geterrcall, seterrcall).

Returns:

errobj : list

The error object, a list containing three elements: [internal numpy buffer size, error mask, error callback function].

The error mask is a single integer that holds the treatment information on all four floating point errors. The information for each error type is contained in three bits of the integer. If we print it in base 8, we can see what treatment is set for “invalid”, “under”, “over”, and “divide” (in that order). The printed string can be interpreted with

  • 0 : ‘ignore’
  • 1 : ‘warn’
  • 2 : ‘raise’
  • 3 : ‘call’
  • 4 : ‘print’
  • 5 : ‘log’

See also

seterrobj, seterr, geterr, seterrcall, geterrcall, getbufsize, setbufsize

Notes

For complete documentation of the types of floating-point exceptions and treatment options, see seterr.

Examples

>>> np.geterrobj()  # first get the defaults
[10000, 0, None]

>>> def err_handler(type, flag):
...     print "Floating point error (%s), with flag %s" % (type, flag)
...
>>> old_bufsize = np.setbufsize(20000)
>>> old_err = np.seterr(divide='raise')
>>> old_handler = np.seterrcall(err_handler)
>>> np.geterrobj()
[20000, 2, <function err_handler at 0x91dcaac>]

>>> old_err = np.seterr(all='ignore')
>>> np.base_repr(np.geterrobj()[1], 8)
'0'
>>> old_err = np.seterr(divide='warn', over='log', under='call',
                        invalid='print')
>>> np.base_repr(np.geterrobj()[1], 8)
'4351'


Discrete Fourier Transform (numpy.fft)

  • next
  • previous

Table Of Contents

  • Discrete Fourier Transform (numpy.fft)
    • Standard FFTs
    • Real FFTs
    • Hermitian FFTs
    • Helper routines
    • Background information
    • Implementation details
    • Real and Hermitian transforms
    • Higher dimensions
    • References
    • Examples

Previous topic

numpy.geterrobj

Next topic

numpy.fft.fft

Discrete Fourier Transform (numpy.fft)

Standard FFTs

fft(a[, n, axis]) | Compute the one-dimensional discrete Fourier Transform.
ifft(a[, n, axis]) | Compute the one-dimensional inverse discrete Fourier Transform.
fft2(a[, s, axes]) | Compute the 2-dimensional discrete Fourier Transform
ifft2(a[, s, axes]) | Compute the 2-dimensional inverse discrete Fourier Transform.
fftn(a[, s, axes]) | Compute the N-dimensional discrete Fourier Transform.
ifftn(a[, s, axes]) | Compute the N-dimensional inverse discrete Fourier Transform.

Real FFTs

rfft(a[, n, axis]) | Compute the one-dimensional discrete Fourier Transform for real input.
irfft(a[, n, axis]) | Compute the inverse of the n-point DFT for real input.
rfft2(a[, s, axes]) | Compute the 2-dimensional FFT of a real array.
irfft2(a[, s, axes]) | Compute the 2-dimensional inverse FFT of a real array.
rfftn(a[, s, axes]) | Compute the N-dimensional discrete Fourier Transform for real input.
irfftn(a[, s, axes]) | Compute the inverse of the N-dimensional FFT of real input.

Hermitian FFTs

hfft(a[, n, axis]) | Compute the FFT of a signal which has Hermitian symmetry (real spectrum).
ihfft(a[, n, axis]) | Compute the inverse FFT of a signal which has Hermitian symmetry.

Helper routines

fftfreq(n[, d]) | Return the Discrete Fourier Transform sample frequencies.
rfftfreq(n[, d]) | Return the Discrete Fourier Transform sample frequencies (for usage with rfft, irfft).
fftshift(x[, axes]) | Shift the zero-frequency component to the center of the spectrum.
ifftshift(x[, axes]) | The inverse of fftshift.

Background information

Fourier analysis is fundamentally a method for expressing a function as a sum of periodic components, and for recovering the function from those components. When both the function and its Fourier transform are replaced with discretized counterparts, it is called the discrete Fourier transform (DFT). The DFT has become a mainstay of numerical computing in part because of a very fast algorithm for computing it, called the Fast Fourier Transform (FFT), which was known to Gauss (1805) and was brought to light in its current form by Cooley and Tukey [CT]. Press et al. [NR] provide an accessible introduction to Fourier analysis and its applications.

Because the discrete Fourier transform separates its input into components that contribute at discrete frequencies, it has a great number of applications in digital signal processing, e.g., for filtering, and in this context the discretized input to the transform is customarily referred to as a signal, which exists in the time domain. The output is called a spectrum or transform and exists in the frequency domain.

Implementation details

There are many ways to define the DFT, varying in the sign of the exponent, normalization, etc. In this implementation, the DFT is defined as

The DFT is in general defined for complex inputs and outputs, and a single-frequency component at linear frequency f is represented by a complex exponential [image], where [image] is the sampling interval.

The values in the result follow so-called “standard” order: If A = fft(a, n), then A[0] contains the zero-frequency term (the mean of the signal), which is always purely real for real inputs. Then A[1:n/2] contains the positive-frequency terms, and A[n/2+1:] contains the negative-frequency terms, in order of decreasingly negative frequency. For an even number of input points, A[n/2] represents both positive and negative Nyquist frequency, and is also purely real for real input. For an odd number of input points, A[(n-1)/2] contains the largest positive frequency, while A[(n+1)/2] contains the largest negative frequency. The routine np.fft.fftfreq(n) returns an array giving the frequencies of corresponding elements in the output. The routine np.fft.fftshift(A) shifts transforms and their frequencies to put the zero-frequency components in the middle, and np.fft.ifftshift(A) undoes that shift.

When the input a is a time-domain signal and A = fft(a), np.abs(A) is its amplitude spectrum and np.abs(A)**2 is its power spectrum. The phase spectrum is obtained by np.angle(A).

The inverse DFT is defined as

It differs from the forward transform by the sign of the exponential argument and the normalization by 1/n.

Real and Hermitian transforms

When the input is purely real, its transform is Hermitian, i.e., the component at frequency [image] is the complex conjugate of the component at frequency [image], which means that for real inputs there is no information in the negative frequency components that is not already available from the positive frequency components. The family of rfft functions is designed to operate on real inputs, and exploits this symmetry by computing only the positive frequency components, up to and including the Nyquist frequency. Thus, n input points produce n/2+1 complex output points. The inverses of this family assumes the same symmetry of its input, and for an output of n points uses n/2+1 input points.

Correspondingly, when the spectrum is purely real, the signal is Hermitian. The hfft family of functions exploits this symmetry by using n/2+1 complex points in the input (time) domain for n real points in the frequency domain.

In higher dimensions, FFTs are used, e.g., for image analysis and filtering. The computational efficiency of the FFT means that it can also be a faster way to compute large convolutions, using the property that a convolution in the time domain is equivalent to a point-by-point multiplication in the frequency domain.

Higher dimensions

In two dimensions, the DFT is defined as

which extends in the obvious way to higher dimensions, and the inverses in higher dimensions also extend in the same way.

References

[CT] Cooley, James W., and John W. Tukey, 1965, “An algorithm for the machine calculation of complex Fourier series,” Math. Comput. 19: 297-301.
[NR] Press, W., Teukolsky, S., Vetterline, W.T., and Flannery, B.P., 2007, Numerical Recipes: The Art of Scientific Computing, ch. 12-13. Cambridge Univ. Press, Cambridge, UK.

Examples

For examples, see the various functions.


numpy.fft.fft

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.ifftshift

Next topic

numpy.fft.ifft

numpy.fft.fft

numpy.fft.fft(a, n=None, axis=-1) [source]

Compute the one-dimensional discrete Fourier Transform.

This function computes the one-dimensional n-point discrete Fourier Transform (DFT) with the efficient Fast Fourier Transform (FFT) algorithm [CT].

Parameters:

a : array_like

Input array, can be complex.

n : int, optional

Length of the transformed axis of the output. If n is smaller than the length of the input, the input is cropped. If it is larger, the input is padded with zeros. If n is not given, the length of the input along the axis specified by axis is used.

axis : int, optional

Axis over which to compute the FFT. If not given, the last axis is used.
Returns:

out : complex ndarray

The truncated or zero-padded input, transformed along the axis indicated by axis, or the last one if axis is not specified.
Raises:

IndexError

if axes is larger than the last axis of a.

See also

numpy.fft
for definition of the DFT and conventions used.
ifft
The inverse of fft.
fft2
The two-dimensional FFT.
fftn
The n-dimensional FFT.
rfftn
The n-dimensional FFT of real input.
fftfreq
Frequency bins for given FFT parameters.

Notes

FFT (Fast Fourier Transform) refers to a way the discrete Fourier Transform (DFT) can be calculated efficiently, by using symmetries in the calculated terms. The symmetry is highest when n is a power of 2, and the transform is therefore most efficient for these sizes.

The DFT is defined, with the conventions used in this implementation, in the documentation for the numpy.fft module.

References

[CT] Cooley, James W., and John W. Tukey, 1965, “An algorithm for the machine calculation of complex Fourier series,” Math. Comput. 19: 297-301.

Examples

>>> np.fft.fft(np.exp(2j * np.pi * np.arange(8) / 8))
array([ -3.44505240e-16 +1.14383329e-17j,
         8.00000000e+00 -5.71092652e-15j,
         2.33482938e-16 +1.22460635e-16j,
         1.64863782e-15 +1.77635684e-15j,
         9.95839695e-17 +2.33482938e-16j,
         0.00000000e+00 +1.66837030e-15j,
         1.14383329e-17 +1.22460635e-16j,
         -1.64863782e-15 +1.77635684e-15j])

>>> import matplotlib.pyplot as plt
>>> t = np.arange(256)
>>> sp = np.fft.fft(np.sin(t))
>>> freq = np.fft.fftfreq(t.shape[-1])
>>> plt.plot(freq, sp.real, freq, sp.imag)
[<matplotlib.lines.Line2D object at 0x...>, <matplotlib.lines.Line2D object at 0x...>]
>>> plt.show()

In this example, real input has an FFT which is Hermitian, i.e., symmetric in the real part and anti-symmetric in the imaginary part, as described in the numpy.fft documentation.

(Source code)


numpy.fft.ifft

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.fft

Next topic

numpy.fft.fft2

numpy.fft.ifft

numpy.fft.ifft(a, n=None, axis=-1) [source]

Compute the one-dimensional inverse discrete Fourier Transform.

This function computes the inverse of the one-dimensional n-point discrete Fourier transform computed by fft. In other words, ifft(fft(a)) == a to within numerical accuracy. For a general description of the algorithm and definitions, see numpy.fft.

The input should be ordered in the same way as is returned by fft, i.e., a[0] should contain the zero frequency term, a[1:n/2+1] should contain the positive-frequency terms, and a[n/2+1:] should contain the negative-frequency terms, in order of decreasingly negative frequency. See numpy.fft for details.

Parameters:

a : array_like

Input array, can be complex.

n : int, optional

Length of the transformed axis of the output. If n is smaller than the length of the input, the input is cropped. If it is larger, the input is padded with zeros. If n is not given, the length of the input along the axis specified by axis is used. See notes about padding issues.

axis : int, optional

Axis over which to compute the inverse DFT. If not given, the last axis is used.
Returns:

out : complex ndarray

The truncated or zero-padded input, transformed along the axis indicated by axis, or the last one if axis is not specified.
Raises:

IndexError

If axes is larger than the last axis of a.

See also

numpy.fft
An introduction, with definitions and general explanations.
fft
The one-dimensional (forward) FFT, of which ifft is the inverse
ifft2
The two-dimensional inverse FFT.
ifftn
The n-dimensional inverse FFT.

Notes

If the input parameter n is larger than the size of the input, the input is padded by appending zeros at the end. Even though this is the common approach, it might lead to surprising results. If a different padding is desired, it must be performed before calling ifft.

Examples

>>> np.fft.ifft([0, 4, 0, 0])
array([ 1.+0.j,  0.+1.j, -1.+0.j,  0.-1.j])

Create and plot a band-limited signal with random phases:

>>> import matplotlib.pyplot as plt
>>> t = np.arange(400)
>>> n = np.zeros((400,), dtype=complex)
>>> n[40:60] = np.exp(1j*np.random.uniform(0, 2*np.pi, (20,)))
>>> s = np.fft.ifft(n)
>>> plt.plot(t, s.real, 'b-', t, s.imag, 'r--')
[<matplotlib.lines.Line2D object at 0x...>, <matplotlib.lines.Line2D object at 0x...>]
>>> plt.legend(('real', 'imaginary'))
<matplotlib.legend.Legend object at 0x...>
>>> plt.show()

(Source code, png, pdf)


numpy.fft.fft2

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.ifft

Next topic

numpy.fft.ifft2

numpy.fft.fft2

numpy.fft.fft2(a, s=None, axes=(-2, -1)) [source]

Compute the 2-dimensional discrete Fourier Transform

This function computes the n-dimensional discrete Fourier Transform over any axes in an M-dimensional array by means of the Fast Fourier Transform (FFT). By default, the transform is computed over the last two axes of the input array, i.e., a 2-dimensional FFT.

Parameters:

a : array_like

Input array, can be complex

s : sequence of ints, optional

Shape (length of each transformed axis) of the output (s[0] refers to axis 0, s[1] to axis 1, etc.). This corresponds to n for fft(x, n). Along each axis, if the given shape is smaller than that of the input, the input is cropped. If it is larger, the input is padded with zeros. if s is not given, the shape of the input along the axes specified by axes is used.

axes : sequence of ints, optional

Axes over which to compute the FFT. If not given, the last two axes are used. A repeated index in axes means the transform over that axis is performed multiple times. A one-element sequence means that a one-dimensional FFT is performed.
Returns:

out : complex ndarray

The truncated or zero-padded input, transformed along the axes indicated by axes, or the last two axes if axes is not given.
Raises:

ValueError

If s and axes have different length, or axes not given and len(s) != 2.

IndexError

If an element of axes is larger than than the number of axes of a.

See also

numpy.fft
Overall view of discrete Fourier transforms, with definitions and conventions used.
ifft2
The inverse two-dimensional FFT.
fft
The one-dimensional FFT.
fftn
The n-dimensional FFT.
fftshift
Shifts zero-frequency terms to the center of the array. For two-dimensional input, swaps first and third quadrants, and second and fourth quadrants.

Notes

fft2 is just fftn with a different default for axes.

The output, analogously to fft, contains the term for zero frequency in the low-order corner of the transformed axes, the positive frequency terms in the first half of these axes, the term for the Nyquist frequency in the middle of the axes and the negative frequency terms in the second half of the axes, in order of decreasingly negative frequency.

See fftn for details and a plotting example, and numpy.fft for definitions and conventions used.

Examples

>>> a = np.mgrid[:5, :5][0]
>>> np.fft.fft2(a)
array([[ 50.0 +0.j        ,   0.0 +0.j        ,   0.0 +0.j        ,
          0.0 +0.j        ,   0.0 +0.j        ],
       [-12.5+17.20477401j,   0.0 +0.j        ,   0.0 +0.j        ,
          0.0 +0.j        ,   0.0 +0.j        ],
       [-12.5 +4.0614962j ,   0.0 +0.j        ,   0.0 +0.j        ,
          0.0 +0.j        ,   0.0 +0.j        ],
       [-12.5 -4.0614962j ,   0.0 +0.j        ,   0.0 +0.j        ,
            0.0 +0.j        ,   0.0 +0.j        ],
       [-12.5-17.20477401j,   0.0 +0.j        ,   0.0 +0.j        ,
          0.0 +0.j        ,   0.0 +0.j        ]])


numpy.fft.ifft2

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.fft2

Next topic

numpy.fft.fftn

numpy.fft.ifft2

numpy.fft.ifft2(a, s=None, axes=(-2, -1)) [source]

Compute the 2-dimensional inverse discrete Fourier Transform.

This function computes the inverse of the 2-dimensional discrete Fourier Transform over any number of axes in an M-dimensional array by means of the Fast Fourier Transform (FFT). In other words, ifft2(fft2(a)) == a to within numerical accuracy. By default, the inverse transform is computed over the last two axes of the input array.

The input, analogously to ifft, should be ordered in the same way as is returned by fft2, i.e. it should have the term for zero frequency in the low-order corner of the two axes, the positive frequency terms in the first half of these axes, the term for the Nyquist frequency in the middle of the axes and the negative frequency terms in the second half of both axes, in order of decreasingly negative frequency.

Parameters:

a : array_like

Input array, can be complex.

s : sequence of ints, optional

Shape (length of each axis) of the output (s[0] refers to axis 0, s[1] to axis 1, etc.). This corresponds to n for ifft(x, n). Along each axis, if the given shape is smaller than that of the input, the input is cropped. If it is larger, the input is padded with zeros. if s is not given, the shape of the input along the axes specified by axes is used. See notes for issue on ifft zero padding.

axes : sequence of ints, optional

Axes over which to compute the FFT. If not given, the last two axes are used. A repeated index in axes means the transform over that axis is performed multiple times. A one-element sequence means that a one-dimensional FFT is performed.
Returns:

out : complex ndarray

The truncated or zero-padded input, transformed along the axes indicated by axes, or the last two axes if axes is not given.
Raises:

ValueError

If s and axes have different length, or axes not given and len(s) != 2.

IndexError

If an element of axes is larger than than the number of axes of a.

See also

numpy.fft
Overall view of discrete Fourier transforms, with definitions and conventions used.
fft2
The forward 2-dimensional FFT, of which ifft2 is the inverse.
ifftn
The inverse of the n-dimensional FFT.
fft
The one-dimensional FFT.
ifft
The one-dimensional inverse FFT.

Notes

ifft2 is just ifftn with a different default for axes.

See ifftn for details and a plotting example, and numpy.fft for definition and conventions used.

Zero-padding, analogously with ifft, is performed by appending zeros to the input along the specified dimension. Although this is the common approach, it might lead to surprising results. If another form of zero padding is desired, it must be performed before ifft2 is called.

Examples

>>> a = 4 * np.eye(4)
>>> np.fft.ifft2(a)
array([[ 1.+0.j,  0.+0.j,  0.+0.j,  0.+0.j],
       [ 0.+0.j,  0.+0.j,  0.+0.j,  1.+0.j],
       [ 0.+0.j,  0.+0.j,  1.+0.j,  0.+0.j],
       [ 0.+0.j,  1.+0.j,  0.+0.j,  0.+0.j]])


numpy.fft.fftn

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.ifft2

Next topic

numpy.fft.ifftn

numpy.fft.fftn

numpy.fft.fftn(a, s=None, axes=None) [source]

Compute the N-dimensional discrete Fourier Transform.

This function computes the N-dimensional discrete Fourier Transform over any number of axes in an M-dimensional array by means of the Fast Fourier Transform (FFT).

Parameters:

a : array_like

Input array, can be complex.

s : sequence of ints, optional

Shape (length of each transformed axis) of the output (s[0] refers to axis 0, s[1] to axis 1, etc.). This corresponds to n for fft(x, n). Along any axis, if the given shape is smaller than that of the input, the input is cropped. If it is larger, the input is padded with zeros. if s is not given, the shape of the input along the axes specified by axes is used.

axes : sequence of ints, optional

Axes over which to compute the FFT. If not given, the last len(s) axes are used, or all axes if s is also not specified. Repeated indices in axes means that the transform over that axis is performed multiple times.
Returns:

out : complex ndarray

The truncated or zero-padded input, transformed along the axes indicated by axes, or by a combination of s and a, as explained in the parameters section above.
Raises:

ValueError

If s and axes have different length.

IndexError

If an element of axes is larger than than the number of axes of a.

See also

numpy.fft
Overall view of discrete Fourier transforms, with definitions and conventions used.
ifftn
The inverse of fftn, the inverse n-dimensional FFT.
fft
The one-dimensional FFT, with definitions and conventions used.
rfftn
The n-dimensional FFT of real input.
fft2
The two-dimensional FFT.
fftshift
Shifts zero-frequency terms to centre of array

Notes

The output, analogously to fft, contains the term for zero frequency in the low-order corner of all axes, the positive frequency terms in the first half of all axes, the term for the Nyquist frequency in the middle of all axes and the negative frequency terms in the second half of all axes, in order of decreasingly negative frequency.

See numpy.fft for details, definitions and conventions used.

Examples

>>> a = np.mgrid[:3, :3, :3][0]
>>> np.fft.fftn(a, axes=(1, 2))
array([[[  0.+0.j,   0.+0.j,   0.+0.j],
        [  0.+0.j,   0.+0.j,   0.+0.j],
        [  0.+0.j,   0.+0.j,   0.+0.j]],
       [[  9.+0.j,   0.+0.j,   0.+0.j],
        [  0.+0.j,   0.+0.j,   0.+0.j],
        [  0.+0.j,   0.+0.j,   0.+0.j]],
       [[ 18.+0.j,   0.+0.j,   0.+0.j],
        [  0.+0.j,   0.+0.j,   0.+0.j],
        [  0.+0.j,   0.+0.j,   0.+0.j]]])
>>> np.fft.fftn(a, (2, 2), axes=(0, 1))
array([[[ 2.+0.j,  2.+0.j,  2.+0.j],
        [ 0.+0.j,  0.+0.j,  0.+0.j]],
       [[-2.+0.j, -2.+0.j, -2.+0.j],
        [ 0.+0.j,  0.+0.j,  0.+0.j]]])

>>> import matplotlib.pyplot as plt
>>> [X, Y] = np.meshgrid(2 * np.pi * np.arange(200) / 12,
...                      2 * np.pi * np.arange(200) / 34)
>>> S = np.sin(X) + np.cos(Y) + np.random.uniform(0, 1, X.shape)
>>> FS = np.fft.fftn(S)
>>> plt.imshow(np.log(np.abs(np.fft.fftshift(FS))**2))
<matplotlib.image.AxesImage object at 0x...>
>>> plt.show()

(Source code, png, pdf)


numpy.fft.ifftn

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.fftn

Next topic

numpy.fft.rfft

numpy.fft.ifftn

numpy.fft.ifftn(a, s=None, axes=None) [source]

Compute the N-dimensional inverse discrete Fourier Transform.

This function computes the inverse of the N-dimensional discrete Fourier Transform over any number of axes in an M-dimensional array by means of the Fast Fourier Transform (FFT). In other words, ifftn(fftn(a)) == a to within numerical accuracy. For a description of the definitions and conventions used, see numpy.fft.

The input, analogously to ifft, should be ordered in the same way as is returned by fftn, i.e. it should have the term for zero frequency in all axes in the low-order corner, the positive frequency terms in the first half of all axes, the term for the Nyquist frequency in the middle of all axes and the negative frequency terms in the second half of all axes, in order of decreasingly negative frequency.

Parameters:

a : array_like

Input array, can be complex.

s : sequence of ints, optional

Shape (length of each transformed axis) of the output (s[0] refers to axis 0, s[1] to axis 1, etc.). This corresponds to n for ifft(x, n). Along any axis, if the given shape is smaller than that of the input, the input is cropped. If it is larger, the input is padded with zeros. if s is not given, the shape of the input along the axes specified by axes is used. See notes for issue on ifft zero padding.

axes : sequence of ints, optional

Axes over which to compute the IFFT. If not given, the last len(s) axes are used, or all axes if s is also not specified. Repeated indices in axes means that the inverse transform over that axis is performed multiple times.
Returns:

out : complex ndarray

The truncated or zero-padded input, transformed along the axes indicated by axes, or by a combination of s or a, as explained in the parameters section above.
Raises:

ValueError

If s and axes have different length.

IndexError

If an element of axes is larger than than the number of axes of a.

See also

numpy.fft
Overall view of discrete Fourier transforms, with definitions and conventions used.
fftn
The forward n-dimensional FFT, of which ifftn is the inverse.
ifft
The one-dimensional inverse FFT.
ifft2
The two-dimensional inverse FFT.
ifftshift
Undoes fftshift, shifts zero-frequency terms to beginning of array.

Notes

See numpy.fft for definitions and conventions used.

Zero-padding, analogously with ifft, is performed by appending zeros to the input along the specified dimension. Although this is the common approach, it might lead to surprising results. If another form of zero padding is desired, it must be performed before ifftn is called.

Examples

>>> a = np.eye(4)
>>> np.fft.ifftn(np.fft.fftn(a, axes=(0,)), axes=(1,))
array([[ 1.+0.j,  0.+0.j,  0.+0.j,  0.+0.j],
       [ 0.+0.j,  1.+0.j,  0.+0.j,  0.+0.j],
       [ 0.+0.j,  0.+0.j,  1.+0.j,  0.+0.j],
       [ 0.+0.j,  0.+0.j,  0.+0.j,  1.+0.j]])

Create and plot an image with band-limited frequency content:

>>> import matplotlib.pyplot as plt
>>> n = np.zeros((200,200), dtype=complex)
>>> n[60:80, 20:40] = np.exp(1j*np.random.uniform(0, 2*np.pi, (20, 20)))
>>> im = np.fft.ifftn(n).real
>>> plt.imshow(im)
<matplotlib.image.AxesImage object at 0x...>
>>> plt.show()

(Source code, png, pdf)


numpy.fft.rfft

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.ifftn

Next topic

numpy.fft.irfft

numpy.fft.rfft

numpy.fft.rfft(a, n=None, axis=-1) [source]

Compute the one-dimensional discrete Fourier Transform for real input.

This function computes the one-dimensional n-point discrete Fourier Transform (DFT) of a real-valued array by means of an efficient algorithm called the Fast Fourier Transform (FFT).

Parameters:

a : array_like

Input array

n : int, optional

Number of points along transformation axis in the input to use. If n is smaller than the length of the input, the input is cropped. If it is larger, the input is padded with zeros. If n is not given, the length of the input along the axis specified by axis is used.

axis : int, optional

Axis over which to compute the FFT. If not given, the last axis is used.
Returns:

out : complex ndarray

The truncated or zero-padded input, transformed along the axis indicated by axis, or the last one if axis is not specified. If n is even, the length of the transformed axis is (n/2)+1. If n is odd, the length is (n+1)/2.
Raises:

IndexError

If axis is larger than the last axis of a.

See also

numpy.fft
For definition of the DFT and conventions used.
irfft
The inverse of rfft.
fft
The one-dimensional FFT of general (complex) input.
fftn
The n-dimensional FFT.
rfftn
The n-dimensional FFT of real input.

Notes

When the DFT is computed for purely real input, the output is Hermitian-symmetric, i.e. the negative frequency terms are just the complex conjugates of the corresponding positive-frequency terms, and the negative-frequency terms are therefore redundant. This function does not compute the negative frequency terms, and the length of the transformed axis of the output is therefore n//2 + 1.

When A = rfft(a) and fs is the sampling frequency, A[0] contains the zero-frequency term 0*fs, which is real due to Hermitian symmetry.

If n is even, A[-1] contains the term representing both positive and negative Nyquist frequency (+fs/2 and -fs/2), and must also be purely real. If n is odd, there is no term at fs/2; A[-1] contains the largest positive frequency (fs/2*(n-1)/n), and is complex in the general case.

If the input a contains an imaginary part, it is silently discarded.

Examples

>>> np.fft.fft([0, 1, 0, 0])
array([ 1.+0.j,  0.-1.j, -1.+0.j,  0.+1.j])
>>> np.fft.rfft([0, 1, 0, 0])
array([ 1.+0.j,  0.-1.j, -1.+0.j])

Notice how the final element of the fft output is the complex conjugate of the second element, for real input. For rfft, this symmetry is exploited to compute only the non-negative frequency terms.


numpy.fft.irfft

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.rfft

Next topic

numpy.fft.rfft2

numpy.fft.irfft

numpy.fft.irfft(a, n=None, axis=-1) [source]

Compute the inverse of the n-point DFT for real input.

This function computes the inverse of the one-dimensional n-point discrete Fourier Transform of real input computed by rfft. In other words, irfft(rfft(a), len(a)) == a to within numerical accuracy. (See Notes below for why len(a) is necessary here.)

The input is expected to be in the form returned by rfft, i.e. the real zero-frequency term followed by the complex positive frequency terms in order of increasing frequency. Since the discrete Fourier Transform of real input is Hermitian-symmetric, the negative frequency terms are taken to be the complex conjugates of the corresponding positive frequency terms.

Parameters:

a : array_like

The input array.

n : int, optional

Length of the transformed axis of the output. For n output points, n//2+1 input points are necessary. If the input is longer than this, it is cropped. If it is shorter than this, it is padded with zeros. If n is not given, it is determined from the length of the input along the axis specified by axis.

axis : int, optional

Axis over which to compute the inverse FFT. If not given, the last axis is used.
Returns:

out : ndarray

The truncated or zero-padded input, transformed along the axis indicated by axis, or the last one if axis is not specified. The length of the transformed axis is n, or, if n is not given, 2*(m-1) where m is the length of the transformed axis of the input. To get an odd number of output points, n must be specified.
Raises:

IndexError

If axis is larger than the last axis of a.

See also

numpy.fft
For definition of the DFT and conventions used.
rfft
The one-dimensional FFT of real input, of which irfft is inverse.
fft
The one-dimensional FFT.
irfft2
The inverse of the two-dimensional FFT of real input.
irfftn
The inverse of the n-dimensional FFT of real input.

Notes

Returns the real valued n-point inverse discrete Fourier transform of a, where a contains the non-negative frequency terms of a Hermitian-symmetric sequence. n is the length of the result, not the input.

If you specify an n such that a must be zero-padded or truncated, the extra/removed values will be added/removed at high frequencies. One can thus resample a series to m points via Fourier interpolation by: a_resamp = irfft(rfft(a), m).

Examples

>>> np.fft.ifft([1, -1j, -1, 1j])
array([ 0.+0.j,  1.+0.j,  0.+0.j,  0.+0.j])
>>> np.fft.irfft([1, -1j, -1])
array([ 0.,  1.,  0.,  0.])

Notice how the last term in the input to the ordinary ifft is the complex conjugate of the second term, and the output has zero imaginary part everywhere. When calling irfft, the negative frequencies are not specified, and the output array is purely real.


numpy.fft.rfft2

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.irfft

Next topic

numpy.fft.irfft2

numpy.fft.rfft2

numpy.fft.rfft2(a, s=None, axes=(-2, -1)) [source]

Compute the 2-dimensional FFT of a real array.

Parameters:

a : array

Input array, taken to be real.

s : sequence of ints, optional

Shape of the FFT.

axes : sequence of ints, optional

Axes over which to compute the FFT.
Returns:

out : ndarray

The result of the real 2-D FFT.

See also

rfftn
Compute the N-dimensional discrete Fourier Transform for real input.

Notes

This is really just rfftn with different default behavior. For more details see rfftn.


numpy.fft.irfft2

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.rfft2

Next topic

numpy.fft.rfftn

numpy.fft.irfft2

numpy.fft.irfft2(a, s=None, axes=(-2, -1)) [source]

Compute the 2-dimensional inverse FFT of a real array.

Parameters:

a : array_like

The input array

s : sequence of ints, optional

Shape of the inverse FFT.

axes : sequence of ints, optional

The axes over which to compute the inverse fft. Default is the last two axes.
Returns:

out : ndarray

The result of the inverse real 2-D FFT.

See also

irfftn
Compute the inverse of the N-dimensional FFT of real input.

Notes

This is really irfftn with different defaults. For more details see irfftn.


numpy.fft.rfftn

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.irfft2

Next topic

numpy.fft.irfftn

numpy.fft.rfftn

numpy.fft.rfftn(a, s=None, axes=None) [source]

Compute the N-dimensional discrete Fourier Transform for real input.

This function computes the N-dimensional discrete Fourier Transform over any number of axes in an M-dimensional real array by means of the Fast Fourier Transform (FFT). By default, all axes are transformed, with the real transform performed over the last axis, while the remaining transforms are complex.

Parameters:

a : array_like

Input array, taken to be real.

s : sequence of ints, optional

Shape (length along each transformed axis) to use from the input. (s[0] refers to axis 0, s[1] to axis 1, etc.). The final element of s corresponds to n for rfft(x, n), while for the remaining axes, it corresponds to n for fft(x, n). Along any axis, if the given shape is smaller than that of the input, the input is cropped. If it is larger, the input is padded with zeros. if s is not given, the shape of the input along the axes specified by axes is used.

axes : sequence of ints, optional

Axes over which to compute the FFT. If not given, the last len(s) axes are used, or all axes if s is also not specified.
Returns:

out : complex ndarray

The truncated or zero-padded input, transformed along the axes indicated by axes, or by a combination of s and a, as explained in the parameters section above. The length of the last axis transformed will be s[-1]//2+1, while the remaining transformed axes will have lengths according to s, or unchanged from the input.
Raises:

ValueError

If s and axes have different length.

IndexError

If an element of axes is larger than than the number of axes of a.

See also

irfftn
The inverse of rfftn, i.e. the inverse of the n-dimensional FFT of real input.
fft
The one-dimensional FFT, with definitions and conventions used.
rfft
The one-dimensional FFT of real input.
fftn
The n-dimensional FFT.
rfft2
The two-dimensional FFT of real input.

Notes

The transform for real input is performed over the last transformation axis, as by rfft, then the transform over the remaining axes is performed as by fftn. The order of the output is as for rfft for the final transformation axis, and as for fftn for the remaining transformation axes.

See fft for details, definitions and conventions used.

Examples

>>> a = np.ones((2, 2, 2))
>>> np.fft.rfftn(a)
array([[[ 8.+0.j,  0.+0.j],
        [ 0.+0.j,  0.+0.j]],
       [[ 0.+0.j,  0.+0.j],
        [ 0.+0.j,  0.+0.j]]])

>>> np.fft.rfftn(a, axes=(2, 0))
array([[[ 4.+0.j,  0.+0.j],
        [ 4.+0.j,  0.+0.j]],
       [[ 0.+0.j,  0.+0.j],
        [ 0.+0.j,  0.+0.j]]])


numpy.fft.irfftn

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.rfftn

Next topic

numpy.fft.hfft

numpy.fft.irfftn

numpy.fft.irfftn(a, s=None, axes=None) [source]

Compute the inverse of the N-dimensional FFT of real input.

This function computes the inverse of the N-dimensional discrete Fourier Transform for real input over any number of axes in an M-dimensional array by means of the Fast Fourier Transform (FFT). In other words, irfftn(rfftn(a), a.shape) == a to within numerical accuracy. (The a.shape is necessary like len(a) is for irfft, and for the same reason.)

The input should be ordered in the same way as is returned by rfftn, i.e. as for irfft for the final transformation axis, and as for ifftn along all the other axes.

Parameters:

a : array_like

Input array.

s : sequence of ints, optional

Shape (length of each transformed axis) of the output (s[0] refers to axis 0, s[1] to axis 1, etc.). s is also the number of input points used along this axis, except for the last axis, where s[-1]//2+1 points of the input are used. Along any axis, if the shape indicated by s is smaller than that of the input, the input is cropped. If it is larger, the input is padded with zeros. If s is not given, the shape of the input along the axes specified by axes is used.

axes : sequence of ints, optional

Axes over which to compute the inverse FFT. If not given, the last len(s) axes are used, or all axes if s is also not specified. Repeated indices in axes means that the inverse transform over that axis is performed multiple times.
Returns:

out : ndarray

The truncated or zero-padded input, transformed along the axes indicated by axes, or by a combination of s or a, as explained in the parameters section above. The length of each transformed axis is as given by the corresponding element of s, or the length of the input in every axis except for the last one if s is not given. In the final transformed axis the length of the output when s is not given is 2*(m-1) where m is the length of the final transformed axis of the input. To get an odd number of output points in the final axis, s must be specified.
Raises:

ValueError

If s and axes have different length.

IndexError

If an element of axes is larger than than the number of axes of a.

See also

rfftn
The forward n-dimensional FFT of real input, of which ifftn is the inverse.
fft
The one-dimensional FFT, with definitions and conventions used.
irfft
The inverse of the one-dimensional FFT of real input.
irfft2
The inverse of the two-dimensional FFT of real input.

Notes

See fft for definitions and conventions used.

See rfft for definitions and conventions used for real input.

Examples

>>> a = np.zeros((3, 2, 2))
>>> a[0, 0, 0] = 3 * 2 * 2
>>> np.fft.irfftn(a)
array([[[ 1.,  1.],
        [ 1.,  1.]],
       [[ 1.,  1.],
        [ 1.,  1.]],
       [[ 1.,  1.],
        [ 1.,  1.]]])


numpy.fft.hfft

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.irfftn

Next topic

numpy.fft.ihfft

numpy.fft.hfft

numpy.fft.hfft(a, n=None, axis=-1) [source]

Compute the FFT of a signal which has Hermitian symmetry (real spectrum).

Parameters:

a : array_like

The input array.

n : int, optional

Length of the transformed axis of the output. For n output points, n//2+1 input points are necessary. If the input is longer than this, it is cropped. If it is shorter than this, it is padded with zeros. If n is not given, it is determined from the length of the input along the axis specified by axis.

axis : int, optional

Axis over which to compute the FFT. If not given, the last axis is used.
Returns:

out : ndarray

The truncated or zero-padded input, transformed along the axis indicated by axis, or the last one if axis is not specified. The length of the transformed axis is n, or, if n is not given, 2*(m-1) where m is the length of the transformed axis of the input. To get an odd number of output points, n must be specified.
Raises:

IndexError

If axis is larger than the last axis of a.

See also

rfft
Compute the one-dimensional FFT for real input.
ihfft
The inverse of hfft.

Notes

hfft/ihfft are a pair analogous to rfft/irfft, but for the opposite case: here the signal has Hermitian symmetry in the time domain and is real in the frequency domain. So here it’s hfft for which you must supply the length of the result if it is to be odd: ihfft(hfft(a), len(a)) == a, within numerical accuracy.

Examples

>>> signal = np.array([1, 2, 3, 4, 3, 2])
>>> np.fft.fft(signal)
array([ 15.+0.j,  -4.+0.j,   0.+0.j,  -1.-0.j,   0.+0.j,  -4.+0.j])
>>> np.fft.hfft(signal[:4]) # Input first half of signal
array([ 15.,  -4.,   0.,  -1.,   0.,  -4.])
>>> np.fft.hfft(signal, 6)  # Input entire signal and truncate
array([ 15.,  -4.,   0.,  -1.,   0.,  -4.])

>>> signal = np.array([[1, 1.j], [-1.j, 2]])
>>> np.conj(signal.T) - signal   # check Hermitian symmetry
array([[ 0.-0.j,  0.+0.j],
       [ 0.+0.j,  0.-0.j]])
>>> freq_spectrum = np.fft.hfft(signal)
>>> freq_spectrum
array([[ 1.,  1.],
       [ 2., -2.]])


numpy.fft.ihfft

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.hfft

Next topic

numpy.fft.fftfreq

numpy.fft.ihfft

numpy.fft.ihfft(a, n=None, axis=-1) [source]

Compute the inverse FFT of a signal which has Hermitian symmetry.

Parameters:

a : array_like

Input array.

n : int, optional

Length of the inverse FFT. Number of points along transformation axis in the input to use. If n is smaller than the length of the input, the input is cropped. If it is larger, the input is padded with zeros. If n is not given, the length of the input along the axis specified by axis is used.

axis : int, optional

Axis over which to compute the inverse FFT. If not given, the last axis is used.
Returns:

out : complex ndarray

The truncated or zero-padded input, transformed along the axis indicated by axis, or the last one if axis is not specified. If n is even, the length of the transformed axis is (n/2)+1. If n is odd, the length is (n+1)/2.

See also

hfft, irfft

Notes

hfft/ihfft are a pair analogous to rfft/irfft, but for the opposite case: here the signal has Hermitian symmetry in the time domain and is real in the frequency domain. So here it’s hfft for which you must supply the length of the result if it is to be odd: ihfft(hfft(a), len(a)) == a, within numerical accuracy.

Examples

>>> spectrum = np.array([ 15, -4, 0, -1, 0, -4])
>>> np.fft.ifft(spectrum)
array([ 1.+0.j,  2.-0.j,  3.+0.j,  4.+0.j,  3.+0.j,  2.-0.j])
>>> np.fft.ihfft(spectrum)
array([ 1.-0.j,  2.-0.j,  3.-0.j,  4.-0.j])


numpy.fft.fftfreq

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.ihfft

Next topic

numpy.fft.rfftfreq

numpy.fft.fftfreq

numpy.fft.fftfreq(n, d=1.0) [source]

Return the Discrete Fourier Transform sample frequencies.

The returned float array f contains the frequency bin centers in cycles per unit of the sample spacing (with zero at the start). For instance, if the sample spacing is in seconds, then the frequency unit is cycles/second.

Given a window length n and a sample spacing d:

f = [0, 1, ...,   n/2-1,     -n/2, ..., -1] / (d*n)   if n is even
f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n)   if n is odd
Parameters:

n : int

Window length.

d : scalar, optional

Sample spacing (inverse of the sampling rate). Defaults to 1.
Returns:

f : ndarray

Array of length n containing the sample frequencies.

Examples

>>> signal = np.array([-2, 8, 6, 4, 1, 0, 3, 5], dtype=float)
>>> fourier = np.fft.fft(signal)
>>> n = signal.size
>>> timestep = 0.1
>>> freq = np.fft.fftfreq(n, d=timestep)
>>> freq
array([ 0.  ,  1.25,  2.5 ,  3.75, -5.  , -3.75, -2.5 , -1.25])


numpy.fft.rfftfreq

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.fftfreq

Next topic

numpy.fft.fftshift

numpy.fft.rfftfreq

numpy.fft.rfftfreq(n, d=1.0) [source]

Return the Discrete Fourier Transform sample frequencies (for usage with rfft, irfft).

The returned float array f contains the frequency bin centers in cycles per unit of the sample spacing (with zero at the start). For instance, if the sample spacing is in seconds, then the frequency unit is cycles/second.

Given a window length n and a sample spacing d:

f = [0, 1, ...,     n/2-1,     n/2] / (d*n)   if n is even
f = [0, 1, ..., (n-1)/2-1, (n-1)/2] / (d*n)   if n is odd

Unlike fftfreq (but like scipy.fftpack.rfftfreq) the Nyquist frequency component is considered to be positive.

Parameters:

n : int

Window length.

d : scalar, optional

Sample spacing (inverse of the sampling rate). Defaults to 1.
Returns:

f : ndarray

Array of length n//2 + 1 containing the sample frequencies.

Examples

>>> signal = np.array([-2, 8, 6, 4, 1, 0, 3, 5, -3, 4], dtype=float)
>>> fourier = np.fft.rfft(signal)
>>> n = signal.size
>>> sample_rate = 100
>>> freq = np.fft.fftfreq(n, d=1./sample_rate)
>>> freq
array([  0.,  10.,  20.,  30.,  40., -50., -40., -30., -20., -10.])
>>> freq = np.fft.rfftfreq(n, d=1./sample_rate)
>>> freq
array([  0.,  10.,  20.,  30.,  40.,  50.])


numpy.fft.fftshift

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.rfftfreq

Next topic

numpy.fft.ifftshift

numpy.fft.fftshift

numpy.fft.fftshift(x, axes=None) [source]

Shift the zero-frequency component to the center of the spectrum.

This function swaps half-spaces for all axes listed (defaults to all). Note that y[0] is the Nyquist component only if len(x) is even.

Parameters:

x : array_like

Input array.

axes : int or shape tuple, optional

Axes over which to shift. Default is None, which shifts all axes.
Returns:

y : ndarray

The shifted array.

See also

ifftshift
The inverse of fftshift.

Examples

>>> freqs = np.fft.fftfreq(10, 0.1)
>>> freqs
array([ 0.,  1.,  2.,  3.,  4., -5., -4., -3., -2., -1.])
>>> np.fft.fftshift(freqs)
array([-5., -4., -3., -2., -1.,  0.,  1.,  2.,  3.,  4.])

Shift the zero-frequency component only along the second axis:

>>> freqs = np.fft.fftfreq(9, d=1./9).reshape(3, 3)
>>> freqs
array([[ 0.,  1.,  2.],
       [ 3.,  4., -4.],
       [-3., -2., -1.]])
>>> np.fft.fftshift(freqs, axes=(1,))
array([[ 2.,  0.,  1.],
       [-4.,  3.,  4.],
       [-1., -3., -2.]])


numpy.fft.ifftshift

  • Discrete Fourier Transform (numpy.fft)
  • index
  • next
  • previous

Previous topic

numpy.fft.fftshift

Next topic

Financial functions

numpy.fft.ifftshift

numpy.fft.ifftshift(x, axes=None) [source]

The inverse of fftshift. Although identical for even-length x, the functions differ by one sample for odd-length x.

Parameters:

x : array_like

Input array.

axes : int or shape tuple, optional

Axes over which to calculate. Defaults to None, which shifts all axes.
Returns:

y : ndarray

The shifted array.

See also

fftshift
Shift zero-frequency component to the center of the spectrum.

Examples

>>> freqs = np.fft.fftfreq(9, d=1./9).reshape(3, 3)
>>> freqs
array([[ 0.,  1.,  2.],
       [ 3.,  4., -4.],
       [-3., -2., -1.]])
>>> np.fft.ifftshift(np.fft.fftshift(freqs))
array([[ 0.,  1.,  2.],
       [ 3.,  4., -4.],
       [-3., -2., -1.]])


Financial functions

  • next
  • previous

Table Of Contents

  • Financial functions
    • Simple financial functions

Previous topic

numpy.fft.ifftshift

Next topic

numpy.fv

Financial functions

Simple financial functions

fv(rate, nper, pmt, pv[, when]) | Compute the future value.
pv(rate, nper, pmt[, fv, when]) | Compute the present value.
npv(rate, values) | Returns the NPV (Net Present Value) of a cash flow series.
pmt(rate, nper, pv[, fv, when]) | Compute the payment against loan principal plus interest.
ppmt(rate, per, nper, pv[, fv, when]) | Compute the payment against loan principal.
ipmt(rate, per, nper, pv[, fv, when]) | Compute the interest portion of a payment.
irr(values) | Return the Internal Rate of Return (IRR).
mirr(values, finance_rate, reinvest_rate) | Modified internal rate of return.
nper(rate, pmt, pv[, fv, when]) | Compute the number of periodic payments.
rate(nper, pmt, pv, fv[, when, guess, tol, ...]) | Compute the rate of interest per period.


numpy.fv

  • Financial functions
  • next
  • previous

Previous topic

numpy.rate

Next topic

numpy.pv

numpy.fv

numpy.fv(rate, nper, pmt, pv, when='end') [source]

Compute the future value.

Given:
  • a present value, pv
  • an interest rate compounded once per period, of which there are
  • nper total
  • a (fixed) payment, pmt, paid either
  • at the beginning (when = {‘begin’, 1}) or the end (when = {‘end’, 0}) of each period
Return:
the value at the end of the nper periods
Parameters:

rate : scalar or array_like of shape(M, )

Rate of interest as decimal (not per cent) per period

nper : scalar or array_like of shape(M, )

Number of compounding periods

pmt : scalar or array_like of shape(M, )

Payment

pv : scalar or array_like of shape(M, )

Present value

when : {{‘begin’, 1}, {‘end’, 0}}, {string, int}, optional

When payments are due (‘begin’ (1) or ‘end’ (0)). Defaults to {‘end’, 0}.
Returns:

out : ndarray

Future values. If all input is scalar, returns a scalar float. If any input is array_like, returns future values for each input element. If multiple inputs are array_like, they all must have the same shape.

Notes

The future value is computed by solving the equation:

fv +
pv*(1+rate)**nper +
pmt*(1 + rate*when)/rate*((1 + rate)**nper - 1) == 0

or, when rate == 0:

fv + pv + pmt * nper == 0

References

[WRW] Wheeler, D. A., E. Rathke, and R. Weir (Eds.) (2009, May). Open Document Format for Office Applications (OpenDocument)v1.2, Part 2: Recalculated Formula (OpenFormula) Format - Annotated Version, Pre-Draft 12. Organization for the Advancement of Structured Information Standards (OASIS). Billerica, MA, USA. [ODT Document]. Available: http://www.oasis-open.org/committees/documents.php?wg_abbrev=office-formula OpenDocument-formula-20090508.odt

Examples

What is the future value after 10 years of saving $100 now, with an additional monthly savings of $100. Assume the interest rate is 5% (annually) compounded monthly?

>>> np.fv(0.05/12, 10*12, -100, -100)
15692.928894335748

By convention, the negative sign represents cash flow out (i.e. money not available today). Thus, saving $100 a month at 5% annual interest leads to $15,692.93 available to spend in 10 years.

If any input is array_like, returns an array of equal shape. Let’s compare different interest rates from the example above.

>>> a = np.array((0.05, 0.06, 0.07))/12
>>> np.fv(a, 10*12, -100, -100)
array([ 15692.92889434,  16569.87435405,  17509.44688102])


numpy.pv

  • Financial functions
  • next
  • previous

Previous topic

numpy.fv

Next topic

numpy.npv

numpy.pv

numpy.pv(rate, nper, pmt, fv=0.0, when='end') [source]

Compute the present value.

Given:
  • a future value, fv
  • an interest rate compounded once per period, of which there are
  • nper total
  • a (fixed) payment, pmt, paid either
  • at the beginning (when = {‘begin’, 1}) or the end (when = {‘end’, 0}) of each period
Return:
the value now
Parameters:

rate : array_like

Rate of interest (per period)

nper : array_like

Number of compounding periods

pmt : array_like

Payment

fv : array_like, optional

Future value

when : {{‘begin’, 1}, {‘end’, 0}}, {string, int}, optional

When payments are due (‘begin’ (1) or ‘end’ (0))
Returns:

out : ndarray, float

Present value of a series of payments or investments.

Notes

The present value is computed by solving the equation:

fv +
pv*(1 + rate)**nper +
pmt*(1 + rate*when)/rate*((1 + rate)**nper - 1) = 0

or, when rate = 0:

fv + pv + pmt * nper = 0

for pv, which is then returned.

References

[WRW] Wheeler, D. A., E. Rathke, and R. Weir (Eds.) (2009, May). Open Document Format for Office Applications (OpenDocument)v1.2, Part 2: Recalculated Formula (OpenFormula) Format - Annotated Version, Pre-Draft 12. Organization for the Advancement of Structured Information Standards (OASIS). Billerica, MA, USA. [ODT Document]. Available: http://www.oasis-open.org/committees/documents.php?wg_abbrev=office-formula OpenDocument-formula-20090508.odt

Examples

What is the present value (e.g., the initial investment) of an investment that needs to total $15692.93 after 10 years of saving $100 every month? Assume the interest rate is 5% (annually) compounded monthly.

>>> np.pv(0.05/12, 10*12, -100, 15692.93)
-100.00067131625819

By convention, the negative sign represents cash flow out (i.e., money not available today). Thus, to end up with $15,692.93 in 10 years saving $100 a month at 5% annual interest, one’s initial deposit should also be $100.

If any input is array_like, pv returns an array of equal shape. Let’s compare different interest rates in the example above:

>>> a = np.array((0.05, 0.04, 0.03))/12
>>> np.pv(a, 10*12, -100, 15692.93)
array([ -100.00067132,  -649.26771385, -1273.78633713])

So, to end up with the same $15692.93 under the same $100 per month “savings plan,” for annual interest rates of 4% and 3%, one would need initial investments of $649.27 and $1273.79, respectively.


numpy.npv

  • Financial functions
  • next
  • previous

Previous topic

numpy.pv

Next topic

numpy.pmt

numpy.npv

numpy.npv(rate, values) [source]

Returns the NPV (Net Present Value) of a cash flow series.

Parameters:

rate : scalar

The discount rate.

values : array_like, shape(M, )

The values of the time series of cash flows. The (fixed) time interval between cash flow “events” must be the same as that for which rate is given (i.e., if rate is per year, then precisely a year is understood to elapse between each cash flow event). By convention, investments or “deposits” are negative, income or “withdrawals” are positive; values must begin with the initial investment, thus values[0] will typically be negative.
Returns:

out : float

The NPV of the input cash flow series values at the discount rate.

Notes

Returns the result of: [G53]

References

[G53] (1, 2) L. J. Gitman, “Principles of Managerial Finance, Brief,” 3rd ed., Addison-Wesley, 2003, pg. 346.

Examples

>>> np.npv(0.281,[-100, 39, 59, 55, 20])
-0.0084785916384548798

(Compare with the Example given for numpy.lib.financial.irr)


numpy.pmt

  • Financial functions
  • next
  • previous

Previous topic

numpy.npv

Next topic

numpy.ppmt

numpy.pmt

numpy.pmt(rate, nper, pv, fv=0, when='end') [source]

Compute the payment against loan principal plus interest.

Given:
  • a present value, pv (e.g., an amount borrowed)
  • a future value, fv (e.g., 0)
  • an interest rate compounded once per period, of which there are
  • nper total
  • and (optional) specification of whether payment is made at the beginning (when = {‘begin’, 1}) or the end (when = {‘end’, 0}) of each period
Return:
the (fixed) periodic payment.
Parameters:

rate : array_like

Rate of interest (per period)

nper : array_like

Number of compounding periods

pv : array_like

Present value

fv : array_like (optional)

Future value (default = 0)

when : {{‘begin’, 1}, {‘end’, 0}}, {string, int}

When payments are due (‘begin’ (1) or ‘end’ (0))
Returns:

out : ndarray

Payment against loan plus interest. If all input is scalar, returns a scalar float. If any input is array_like, returns payment for each input element. If multiple inputs are array_like, they all must have the same shape.

Notes

The payment is computed by solving the equation:

fv +
pv*(1 + rate)**nper +
pmt*(1 + rate*when)/rate*((1 + rate)**nper - 1) == 0

or, when rate == 0:

fv + pv + pmt * nper == 0

for pmt.

Note that computing a monthly mortgage payment is only one use for this function. For example, pmt returns the periodic deposit one must make to achieve a specified future balance given an initial deposit, a fixed, periodically compounded interest rate, and the total number of periods.

References

[WRW] Wheeler, D. A., E. Rathke, and R. Weir (Eds.) (2009, May). Open Document Format for Office Applications (OpenDocument)v1.2, Part 2: Recalculated Formula (OpenFormula) Format - Annotated Version, Pre-Draft 12. Organization for the Advancement of Structured Information Standards (OASIS). Billerica, MA, USA. [ODT Document]. Available: http://www.oasis-open.org/committees/documents.php ?wg_abbrev=office-formulaOpenDocument-formula-20090508.odt

Examples

What is the monthly payment needed to pay off a $200,000 loan in 15 years at an annual interest rate of 7.5%?

>>> np.pmt(0.075/12, 12*15, 200000)
-1854.0247200054619

In order to pay-off (i.e., have a future-value of 0) the $200,000 obtained today, a monthly payment of $1,854.02 would be required. Note that this example illustrates usage of fv having a default value of 0.


numpy.ppmt

  • Financial functions
  • next
  • previous

Previous topic

numpy.pmt

Next topic

numpy.ipmt

numpy.ppmt

numpy.ppmt(rate, per, nper, pv, fv=0.0, when='end') [source]

Compute the payment against loan principal.

Parameters:

rate : array_like

Rate of interest (per period)

per : array_like, int

Amount paid against the loan changes. The per is the period of interest.

nper : array_like

Number of compounding periods

pv : array_like

Present value

fv : array_like, optional

Future value

when : {{‘begin’, 1}, {‘end’, 0}}, {string, int}

When payments are due (‘begin’ (1) or ‘end’ (0))

See also

pmt, pv, ipmt


numpy.ipmt

  • Financial functions
  • next
  • previous

Previous topic

numpy.ppmt

Next topic

numpy.irr

numpy.ipmt

numpy.ipmt(rate, per, nper, pv, fv=0.0, when='end') [source]

Compute the interest portion of a payment.

Parameters:

rate : scalar or array_like of shape(M, )

Rate of interest as decimal (not per cent) per period

per : scalar or array_like of shape(M, )

Interest paid against the loan changes during the life or the loan. The per is the payment period to calculate the interest amount.

nper : scalar or array_like of shape(M, )

Number of compounding periods

pv : scalar or array_like of shape(M, )

Present value

fv : scalar or array_like of shape(M, ), optional

Future value

when : {{‘begin’, 1}, {‘end’, 0}}, {string, int}, optional

When payments are due (‘begin’ (1) or ‘end’ (0)). Defaults to {‘end’, 0}.
Returns:

out : ndarray

Interest portion of payment. If all input is scalar, returns a scalar float. If any input is array_like, returns interest payment for each input element. If multiple inputs are array_like, they all must have the same shape.

See also

ppmt, pmt, pv

Notes

The total payment is made up of payment against principal plus interest.

pmt = ppmt + ipmt

Examples

What is the amortization schedule for a 1 year loan of $2500 at 8.24% interest per year compounded monthly?

>>> principal = 2500.00

The ‘per’ variable represents the periods of the loan. Remember that financial equations start the period count at 1!

>>> per = np.arange(1*12) + 1
>>> ipmt = np.ipmt(0.0824/12, per, 1*12, principal)
>>> ppmt = np.ppmt(0.0824/12, per, 1*12, principal)

Each element of the sum of the ‘ipmt’ and ‘ppmt’ arrays should equal ‘pmt’.

>>> pmt = np.pmt(0.0824/12, 1*12, principal)
>>> np.allclose(ipmt + ppmt, pmt)
True

>>> fmt = '{0:2d} {1:8.2f} {2:8.2f} {3:8.2f}'
>>> for payment in per:
...     index = payment - 1
...     principal = principal + ppmt[index]
...     print fmt.format(payment, ppmt[index], ipmt[index], principal)
 1  -200.58   -17.17  2299.42
 2  -201.96   -15.79  2097.46
 3  -203.35   -14.40  1894.11
 4  -204.74   -13.01  1689.37
 5  -206.15   -11.60  1483.22
 6  -207.56   -10.18  1275.66
 7  -208.99    -8.76  1066.67
 8  -210.42    -7.32   856.25
 9  -211.87    -5.88   644.38
10  -213.32    -4.42   431.05
11  -214.79    -2.96   216.26
12  -216.26    -1.49    -0.00

>>> interestpd = np.sum(ipmt)
>>> np.round(interestpd, 2)
-112.98


numpy.irr

  • Financial functions
  • next
  • previous

Previous topic

numpy.ipmt

Next topic

numpy.mirr

numpy.irr

numpy.irr(values) [source]

Return the Internal Rate of Return (IRR).

This is the “average” periodically compounded rate of return that gives a net present value of 0.0; for a more complete explanation, see Notes below.

Parameters:

values : array_like, shape(N,)

Input cash flows per time period. By convention, net “deposits” are negative and net “withdrawals” are positive. Thus, for example, at least the first element of values, which represents the initial investment, will typically be negative.
Returns:

out : float

Internal Rate of Return for periodic input values.

Notes

The IRR is perhaps best understood through an example (illustrated using np.irr in the Examples section below). Suppose one invests 100 units and then makes the following withdrawals at regular (fixed) intervals: 39, 59, 55, 20. Assuming the ending value is 0, one’s 100 unit investment yields 173 units; however, due to the combination of compounding and the periodic withdrawals, the “average” rate of return is neither simply 0.73/4 nor (1.73)^0.25-1. Rather, it is the solution (for r) of the equation:

In general, for values = [v_0, v_1, ... v_M], irr is the solution of the equation: [G32]

References

[G32] (1, 2) L. J. Gitman, “Principles of Managerial Finance, Brief,” 3rd ed., Addison-Wesley, 2003, pg. 348.

Examples

>>> round(irr([-100, 39, 59, 55, 20]), 5)
0.28095
>>> round(irr([-100, 0, 0, 74]), 5)
-0.0955
>>> round(irr([-100, 100, 0, -7]), 5)
-0.0833
>>> round(irr([-100, 100, 0, 7]), 5)
0.06206
>>> round(irr([-5, 10.5, 1, -8, 1]), 5)
0.0886

(Compare with the Example given for numpy.lib.financial.npv)


numpy.mirr

  • Financial functions
  • next
  • previous

Previous topic

numpy.irr

Next topic

numpy.nper

numpy.mirr

numpy.mirr(values, finance_rate, reinvest_rate) [source]

Modified internal rate of return.

Parameters:

values : array_like

Cash flows (must contain at least one positive and one negative value) or nan is returned. The first value is considered a sunk cost at time zero.

finance_rate : scalar

Interest rate paid on the cash flows

reinvest_rate : scalar

Interest rate received on the cash flows upon reinvestment
Returns:

out : float

Modified internal rate of return


numpy.nper

  • Financial functions
  • next
  • previous

Previous topic

numpy.mirr

Next topic

numpy.rate

numpy.nper

numpy.nper(rate, pmt, pv, fv=0, when='end') [source]

Compute the number of periodic payments.

Parameters:

rate : array_like

Rate of interest (per period)

pmt : array_like

Payment

pv : array_like

Present value

fv : array_like, optional

Future value

when : {{‘begin’, 1}, {‘end’, 0}}, {string, int}, optional

When payments are due (‘begin’ (1) or ‘end’ (0))

Notes

The number of periods nper is computed by solving the equation:

fv + pv*(1+rate)**nper + pmt*(1+rate*when)/rate*((1+rate)**nper-1) = 0

but if rate = 0 then:

fv + pv + pmt*nper = 0

Examples

If you only had $150/month to pay towards the loan, how long would it take to pay-off a loan of $8,000 at 7% annual interest?

>>> print round(np.nper(0.07/12, -150, 8000), 5)
64.07335

So, over 64 months would be required to pay off the loan.

The same analysis could be done with several different interest rates and/or payments and/or total amounts to produce an entire table.

>>> np.nper(*(np.ogrid[0.07/12: 0.08/12: 0.01/12,
...                    -150   : -99     : 50    ,
...                    8000   : 9001    : 1000]))
array([[[  64.07334877,   74.06368256],
        [ 108.07548412,  127.99022654]],
       [[  66.12443902,   76.87897353],
        [ 114.70165583,  137.90124779]]])


numpy.rate

  • Financial functions
  • next
  • previous

Previous topic

numpy.nper

Next topic

Functional programming

numpy.rate

numpy.rate(nper, pmt, pv, fv, when='end', guess=0.1, tol=1e-06, maxiter=100) [source]

Compute the rate of interest per period.

Parameters:

nper : array_like

Number of compounding periods

pmt : array_like

Payment

pv : array_like

Present value

fv : array_like

Future value

when : {{‘begin’, 1}, {‘end’, 0}}, {string, int}, optional

When payments are due (‘begin’ (1) or ‘end’ (0))

guess : float, optional

Starting guess for solving the rate of interest

tol : float, optional

Required tolerance for the solution

maxiter : int, optional

Maximum iterations in finding the solution

Notes

The rate of interest is computed by iteratively solving the (non-linear) equation:

fv + pv*(1+rate)**nper + pmt*(1+rate*when)/rate * ((1+rate)**nper - 1) = 0

for rate.

References

Wheeler, D. A., E. Rathke, and R. Weir (Eds.) (2009, May). Open Document Format for Office Applications (OpenDocument)v1.2, Part 2: Recalculated Formula (OpenFormula) Format - Annotated Version, Pre-Draft 12. Organization for the Advancement of Structured Information Standards (OASIS). Billerica, MA, USA. [ODT Document]. Available: http://www.oasis-open.org/committees/documents.php?wg_abbrev=office-formula OpenDocument-formula-20090508.odt


Functional programming

  • next
  • previous

Previous topic

numpy.rate

Next topic

numpy.apply_along_axis

Functional programming

apply_along_axis(func1d, axis, arr, *args, ...) | Apply a function to 1-D slices along the given axis.
apply_over_axes(func, a, axes) | Apply a function repeatedly over multiple axes.
vectorize(pyfunc[, otypes, doc, excluded, cache]) | Generalized function class.
frompyfunc(func, nin, nout) | Takes an arbitrary Python function and returns a Numpy ufunc.
piecewise(x, condlist, funclist, *args, **kw) | Evaluate a piecewise-defined function.


numpy.apply_along_axis

  • Functional programming
  • next
  • previous

Previous topic

numpy.piecewise

Next topic

numpy.apply_over_axes

numpy.apply_along_axis

numpy.apply_along_axis(func1d, axis, arr, *args, **kwargs) [source]

Apply a function to 1-D slices along the given axis.

Execute func1d(a, *args) where func1d operates on 1-D arrays and a is a 1-D slice of arr along axis.

Parameters:

func1d : function

This function should accept 1-D arrays. It is applied to 1-D slices of arr along the specified axis.

axis : integer

Axis along which arr is sliced.

arr : ndarray

Input array.

args : any

Additional arguments to func1d.

kwargs: any

Additional named arguments to func1d.

New in version 1.9.0.
Returns:

apply_along_axis : ndarray

The output array. The shape of outarr is identical to the shape of arr, except along the axis dimension, where the length of outarr is equal to the size of the return value of func1d. If func1d returns a scalar outarr will have one fewer dimensions than arr.

See also

apply_over_axes
Apply a function repeatedly over multiple axes.

Examples

>>> def my_func(a):
...     """Average first and last element of a 1-D array"""
...     return (a[0] + a[-1]) * 0.5
>>> b = np.array([[1,2,3], [4,5,6], [7,8,9]])
>>> np.apply_along_axis(my_func, 0, b)
array([ 4.,  5.,  6.])
>>> np.apply_along_axis(my_func, 1, b)
array([ 2.,  5.,  8.])

For a function that doesn’t return a scalar, the number of dimensions in outarr is the same as arr.

>>> b = np.array([[8,1,7], [4,3,9], [5,2,6]])
>>> np.apply_along_axis(sorted, 1, b)
array([[1, 7, 8],
       [3, 4, 9],
       [2, 5, 6]])


numpy.apply_over_axes

  • Functional programming
  • next
  • previous

Previous topic

numpy.apply_along_axis

Next topic

numpy.vectorize

numpy.apply_over_axes

numpy.apply_over_axes(func, a, axes) [source]

Apply a function repeatedly over multiple axes.

func is called as res = func(a, axis), where axis is the first element of axes. The result res of the function call must have either the same dimensions as a or one less dimension. If res has one less dimension than a, a dimension is inserted before axis. The call to func is then repeated for each axis in axes, with res as the first argument.

Parameters:

func : function

This function must take two arguments, func(a, axis).

a : array_like

Input array.

axes : array_like

Axes over which func is applied; the elements must be integers.
Returns:

apply_over_axis : ndarray

The output array. The number of dimensions is the same as a, but the shape can be different. This depends on whether func changes the shape of its output with respect to its input.

See also

apply_along_axis
Apply a function to 1-D slices of an array along the given axis.

Notes

This function is equivalent to tuple axis arguments to reorderable ufuncs with keepdims=True. Tuple axis arguments to ufuncs have been availabe since version 1.7.0.

Examples

>>> a = np.arange(24).reshape(2,3,4)
>>> a
array([[[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]],
       [[12, 13, 14, 15],
        [16, 17, 18, 19],
        [20, 21, 22, 23]]])

Sum over axes 0 and 2. The result has same number of dimensions as the original array:

>>> np.apply_over_axes(np.sum, a, [0,2])
array([[[ 60],
        [ 92],
        [124]]])

Tuple axis arguments to ufuncs are equivalent:

>>> np.sum(a, axis=(0,2), keepdims=True)
array([[[ 60],
        [ 92],
        [124]]])


numpy.vectorize

  • Functional programming
  • next
  • previous

Previous topic

numpy.apply_over_axes

Next topic

numpy.vectorize.__call__

numpy.vectorize

class numpy.vectorize(pyfunc, otypes='', doc=None, excluded=None, cache=False) [source]

Generalized function class.

Define a vectorized function which takes a nested sequence of objects or numpy arrays as inputs and returns a numpy array as output. The vectorized function evaluates pyfunc over successive tuples of the input arrays like the python map function, except it uses the broadcasting rules of numpy.

The data type of the output of vectorized is determined by calling the function with the first element of the input. This can be avoided by specifying the otypes argument.

Parameters:

pyfunc : callable

A python function or method.

otypes : str or list of dtypes, optional

The output data type. It must be specified as either a string of typecode characters or a list of data type specifiers. There should be one data type specifier for each output.

doc : str, optional

The docstring for the function. If None, the docstring will be the pyfunc.__doc__.

excluded : set, optional

Set of strings or integers representing the positional or keyword arguments for which the function will not be vectorized. These will be passed directly to pyfunc unmodified.

New in version 1.7.0.

cache : bool, optional

If True, then cache the first function call that determines the number of outputs if otypes is not provided.

New in version 1.7.0.
Returns:

vectorized : callable

Vectorized function.

Notes

The vectorize function is provided primarily for convenience, not for performance. The implementation is essentially a for loop.

If otypes is not specified, then a call to the function with the first argument will be used to determine the number of outputs. The results of this call will be cached if cache is True to prevent calling the function twice. However, to implement the cache, the original function must be wrapped which will slow down subsequent calls, so only do this if your function is expensive.

The new keyword argument interface and excluded argument support further degrades performance.

Examples

>>> def myfunc(a, b):
...     "Return a-b if a>b, otherwise return a+b"
...     if a > b:
...         return a - b
...     else:
...         return a + b

>>> vfunc = np.vectorize(myfunc)
>>> vfunc([1, 2, 3, 4], 2)
array([3, 4, 1, 2])

The docstring is taken from the input function to vectorize unless it is specified

>>> vfunc.__doc__
'Return a-b if a>b, otherwise return a+b'
>>> vfunc = np.vectorize(myfunc, doc='Vectorized `myfunc`')
>>> vfunc.__doc__
'Vectorized `myfunc`'

The output type is determined by evaluating the first element of the input, unless it is specified

>>> out = vfunc([1, 2, 3, 4], 2)
>>> type(out[0])
<type 'numpy.int32'>
>>> vfunc = np.vectorize(myfunc, otypes=[np.float])
>>> out = vfunc([1, 2, 3, 4], 2)
>>> type(out[0])
<type 'numpy.float64'>

The excluded argument can be used to prevent vectorizing over certain arguments. This can be useful for array-like arguments of a fixed length such as the coefficients for a polynomial as in polyval:

>>> def mypolyval(p, x):
...     _p = list(p)
...     res = _p.pop(0)
...     while _p:
...         res = res*x + _p.pop(0)
...     return res
>>> vpolyval = np.vectorize(mypolyval, excluded=['p'])
>>> vpolyval(p=[1, 2, 3], x=[0, 1])
array([3, 6])

Positional arguments may also be excluded by specifying their position:

>>> vpolyval.excluded.add(0)
>>> vpolyval([1, 2, 3], x=[0, 1])
array([3, 6])

Methods

__call__(*args, **kwargs) Return arrays with the results of pyfunc broadcast (vectorized) over args and kwargs not in excluded.


numpy.vectorize.__call__

  • Functional programming
  • numpy.vectorize
  • index
  • next
  • previous

Previous topic

numpy.vectorize

Next topic

numpy.frompyfunc

numpy.vectorize.__call__

vectorize.__call__(*args, **kwargs) [source]

Return arrays with the results of pyfunc broadcast (vectorized) over args and kwargs not in excluded.


numpy.frompyfunc

  • Functional programming
  • next
  • previous

Previous topic

numpy.vectorize.__call__

Next topic

numpy.piecewise

numpy.frompyfunc

numpy.frompyfunc(func, nin, nout)

Takes an arbitrary Python function and returns a Numpy ufunc.

Can be used, for example, to add broadcasting to a built-in Python function (see Examples section).

Parameters:

func : Python function object

An arbitrary Python function.

nin : int

The number of input arguments.

nout : int

The number of objects returned by func.
Returns:

out : ufunc

Returns a Numpy universal function (ufunc) object.

Notes

The returned ufunc always returns PyObject arrays.

Examples

Use frompyfunc to add broadcasting to the Python function oct:

>>> oct_array = np.frompyfunc(oct, 1, 1)
>>> oct_array(np.array((10, 30, 100)))
array([012, 036, 0144], dtype=object)
>>> np.array((oct(10), oct(30), oct(100))) # for comparison
array(['012', '036', '0144'],
      dtype='|S4')


numpy.piecewise

  • Functional programming
  • next
  • previous

Previous topic

numpy.frompyfunc

Next topic

Numpy-specific help functions

numpy.piecewise

numpy.piecewise(x, condlist, funclist, *args, **kw) [source]

Evaluate a piecewise-defined function.

Given a set of conditions and corresponding functions, evaluate each function on the input data wherever its condition is true.

Parameters:

x : ndarray

The input domain.

condlist : list of bool arrays

Each boolean array corresponds to a function in funclist. Wherever condlist[i] is True, funclist[i](x) is used as the output value.

Each boolean array in condlist selects a piece of x, and should therefore be of the same shape as x.

The length of condlist must correspond to that of funclist. If one extra function is given, i.e. if len(funclist) - len(condlist) == 1, then that extra function is the default value, used wherever all conditions are false.

funclist : list of callables, f(x,*args,**kw), or scalars

Each function is evaluated over x wherever its corresponding condition is True. It should take an array as input and give an array or a scalar value as output. If, instead of a callable, a scalar is provided then a constant function (lambda x: scalar) is assumed.

args : tuple, optional

Any further arguments given to piecewise are passed to the functions upon execution, i.e., if called piecewise(..., ..., 1, 'a'), then each function is called as f(x, 1, 'a').

kw : dict, optional

Keyword arguments used in calling piecewise are passed to the functions upon execution, i.e., if called piecewise(..., ..., lambda=1), then each function is called as f(x, lambda=1).
Returns:

out : ndarray

The output is the same shape and type as x and is found by calling the functions in funclist on the appropriate portions of x, as defined by the boolean arrays in condlist. Portions not covered by any condition have a default value of 0.

See also

choose, select, where

Notes

This is similar to choose or select, except that functions are evaluated on elements of x that satisfy the corresponding condition from condlist.

The result is:

      |--
      |funclist[0](x[condlist[0]])
out = |funclist[1](x[condlist[1]])
      |...
      |funclist[n2](x[condlist[n2]])
      |--

Examples

Define the sigma function, which is -1 for x < 0 and +1 for x >= 0.

>>> x = np.linspace(-2.5, 2.5, 6)
>>> np.piecewise(x, [x < 0, x >= 0], [-1, 1])
array([-1., -1., -1.,  1.,  1.,  1.])

Define the absolute value, which is -x for x <0 and x for x >= 0.

>>> np.piecewise(x, [x < 0, x >= 0], [lambda x: -x, lambda x: x])
array([ 2.5,  1.5,  0.5,  0.5,  1.5,  2.5])


Numpy-specific help functions

  • next
  • previous

Table Of Contents

  • Numpy-specific help functions
    • Finding help
    • Reading help

Previous topic

numpy.piecewise

Next topic

numpy.lookfor

Numpy-specific help functions

Finding help

lookfor(what[, module, import_modules, ...]) Do a keyword search on docstrings.

Reading help

info([object, maxwidth, output, toplevel]) | Get help information for a function, class, or module.
source(object[, output]) | Print or write to a file the source code for a Numpy object.


numpy.lookfor

  • Numpy-specific help functions
  • next
  • previous

Previous topic

numpy.source

Next topic

numpy.info

numpy.lookfor

numpy.lookfor(what, module=None, import_modules=True, regenerate=False, output=None) [source]

Do a keyword search on docstrings.

A list of of objects that matched the search is displayed, sorted by relevance. All given keywords need to be found in the docstring for it to be returned as a result, but the order does not matter.

Parameters:

what : str

String containing words to look for.

module : str or list, optional

Name of module(s) whose docstrings to go through.

import_modules : bool, optional

Whether to import sub-modules in packages. Default is True.

regenerate : bool, optional

Whether to re-generate the docstring cache. Default is False.

output : file-like, optional

File-like object to write the output to. If omitted, use a pager.

See also

source, info

Notes

Relevance is determined only roughly, by checking if the keywords occur in the function name, at the start of a docstring, etc.

Examples

>>> np.lookfor('binary representation')
Search results for 'binary representation'
------------------------------------------
numpy.binary_repr
    Return the binary representation of the input number as a string.
numpy.core.setup_common.long_double_representation
    Given a binary dump as given by GNU od -b, look for long double
numpy.base_repr
    Return a string representation of a number in the given base system.
...


numpy.info

  • Numpy-specific help functions
  • next
  • previous

Previous topic

numpy.lookfor

Next topic

numpy.source

numpy.info

numpy.info(object=None, maxwidth=76, output=<open file '<stdout>', mode 'w' at 0x0000000001E720C0>, toplevel='numpy') [source]

Get help information for a function, class, or module.

Parameters:

object : object or str, optional

Input object or name to get information about. If object is a numpy object, its docstring is given. If it is a string, available modules are searched for matching objects. If None, information about info itself is returned.

maxwidth : int, optional

Printing width.

output : file like object, optional

File like object that the output is written to, default is stdout. The object has to be opened in ‘w’ or ‘a’ mode.

toplevel : str, optional

Start search at this level.

See also

source, lookfor

Notes

When used interactively with an object, np.info(obj) is equivalent to help(obj) on the Python prompt or obj? on the IPython prompt.

Examples

>>> np.info(np.polyval)
   polyval(p, x)
     Evaluate the polynomial p at x.
     ...

When using a string for object it is possible to get multiple results.

>>> np.info('fft')
     *** Found in numpy ***
Core FFT routines
...
     *** Found in numpy.fft ***
 fft(a, n=None, axis=-1)
...
     *** Repeat reference found in numpy.fft.fftpack ***
     *** Total of 3 references found. ***


numpy.source

  • Numpy-specific help functions
  • next
  • previous

Previous topic

numpy.info

Next topic

Indexing routines

numpy.source

numpy.source(object, output=<open file '<stdout>', mode 'w' at 0x0000000001E720C0>) [source]

Print or write to a file the source code for a Numpy object.

The source code is only returned for objects written in Python. Many functions and classes are defined in C and will therefore not return useful information.

Parameters:

object : numpy object

Input object. This can be any object (function, class, module, ...).

output : file object, optional

If output not supplied then source code is printed to screen (sys.stdout). File object must be created with either write ‘w’ or append ‘a’ modes.

See also

lookfor, info

Examples

>>> np.source(np.interp)
In file: /usr/lib/python2.6/dist-packages/numpy/lib/function_base.py
def interp(x, xp, fp, left=None, right=None):
    """.... (full docstring printed)"""
    if isinstance(x, (float, int, number)):
        return compiled_interp([x], xp, fp, left, right).item()
    else:
        return compiled_interp(x, xp, fp, left, right)

The source code is only returned for objects written in Python.

>>> np.source(np.array)
Not available for this object.


Indexing routines

  • next
  • previous

Table Of Contents

  • Indexing routines
    • Generating index arrays
    • Indexing-like operations
    • Inserting data into arrays
    • Iterating over arrays

Previous topic

numpy.source

Next topic

numpy.c

Indexing routines

See also

Indexing

Generating index arrays

c_ | Translates slice objects to concatenation along the second axis.
r_ | Translates slice objects to concatenation along the first axis.
s_ | A nicer way to build up index tuples for arrays.
nonzero(a) | Return the indices of the elements that are non-zero.
where(condition, [x, y]) | Return elements, either from x or y, depending on condition.
indices(dimensions[, dtype]) | Return an array representing the indices of a grid.
ix_(*args) | Construct an open mesh from multiple sequences.
ogrid | nd_grid instance which returns an open multi-dimensional “meshgrid”.
ravel_multi_index(multi_index, dims[, mode, ...]) | Converts a tuple of index arrays into an array of flat indices, applying boundary modes to the multi-index.
unravel_index(indices, dims[, order]) | Converts a flat index or array of flat indices into a tuple of coordinate arrays.
diag_indices(n[, ndim]) | Return the indices to access the main diagonal of an array.
diag_indices_from(arr) | Return the indices to access the main diagonal of an n-dimensional array.
mask_indices(n, mask_func[, k]) | Return the indices to access (n, n) arrays, given a masking function.
tril_indices(n[, k, m]) | Return the indices for the lower-triangle of an (n, m) array.
tril_indices_from(arr[, k]) | Return the indices for the lower-triangle of arr.
triu_indices(n[, k, m]) | Return the indices for the upper-triangle of an (n, m) array.
triu_indices_from(arr[, k]) | Return the indices for the upper-triangle of arr.

Indexing-like operations

take(a, indices[, axis, out, mode]) | Take elements from an array along an axis.
choose(a, choices[, out, mode]) | Construct an array from an index array and a set of arrays to choose from.
compress(condition, a[, axis, out]) | Return selected slices of an array along given axis.
diag(v[, k]) | Extract a diagonal or construct a diagonal array.
diagonal(a[, offset, axis1, axis2]) | Return specified diagonals.
select(condlist, choicelist[, default]) | Return an array drawn from elements in choicelist, depending on conditions.

Inserting data into arrays

place(arr, mask, vals) | Change elements of an array based on conditional and input values.
put(a, ind, v[, mode]) | Replaces specified elements of an array with given values.
putmask(a, mask, values) | Changes elements of an array based on conditional and input values.
fill_diagonal(a, val[, wrap]) | Fill the main diagonal of the given array of any dimensionality.

Iterating over arrays

nditer | Efficient multi-dimensional iterator object to iterate over arrays.
ndenumerate(arr) | Multidimensional index iterator.
ndindex(*shape) | An N-dimensional iterator object to index arrays.
flatiter | Flat iterator object to iterate over arrays.


numpy.c

  • Indexing routines
  • next
  • previous

Previous topic

numpy.flatiter.next

Next topic

numpy.r

numpy.c

numpy.c_ = <numpy.lib.index_tricks.CClass object at 0x0000000004640EF0>

Translates slice objects to concatenation along the second axis.

This is short-hand for np.r_['-1,2,0', index expression], which is useful because of its common occurrence. In particular, arrays will be stacked along their last axis after being upgraded to at least 2-D with 1’s post-pended to the shape (column vectors made out of 1-D arrays).

For detailed documentation, see r_.

Examples

>>> np.c_[np.array([[1,2,3]]), 0, 0, np.array([[4,5,6]])]
array([[1, 2, 3, 0, 0, 4, 5, 6]])


numpy.r

  • Indexing routines
  • next
  • previous

Previous topic

numpy.c

Next topic

numpy.s

numpy.r

numpy.r_ = <numpy.lib.index_tricks.RClass object at 0x0000000004640E48>

Translates slice objects to concatenation along the first axis.

This is a simple way to build up arrays quickly. There are two use cases.

  1. If the index expression contains comma separated arrays, then stack them along their first axis.
  2. If the index expression contains slice notation or scalars then create a 1-D array with a range indicated by the slice notation.

If slice notation is used, the syntax start:stop:step is equivalent to np.arange(start, stop, step) inside of the brackets. However, if step is an imaginary number (i.e. 100j) then its integer portion is interpreted as a number-of-points desired and the start and stop are inclusive. In other words start:stop:stepj is interpreted as np.linspace(start, stop, step, endpoint=1) inside of the brackets. After expansion of slice notation, all comma separated sequences are concatenated together.

Optional character strings placed as the first element of the index expression can be used to change the output. The strings ‘r’ or ‘c’ result in matrix output. If the result is 1-D and ‘r’ is specified a 1 x N (row) matrix is produced. If the result is 1-D and ‘c’ is specified, then a N x 1 (column) matrix is produced. If the result is 2-D then both provide the same matrix result.

A string integer specifies which axis to stack multiple comma separated arrays along. A string of two comma-separated integers allows indication of the minimum number of dimensions to force each entry into as the second integer (the axis to concatenate along is still the first integer).

A string with three comma-separated integers allows specification of the axis to concatenate along, the minimum number of dimensions to force the entries to, and which axis should contain the start of the arrays which are less than the specified number of dimensions. In other words the third integer allows you to specify where the 1’s should be placed in the shape of the arrays that have their shapes upgraded. By default, they are placed in the front of the shape tuple. The third argument allows you to specify where the start of the array should be instead. Thus, a third argument of ‘0’ would place the 1’s at the end of the array shape. Negative integers specify where in the new shape tuple the last dimension of upgraded arrays should be placed, so the default is ‘-1’.

Parameters: Not a function, so takes no parameters
Returns: A concatenated ndarray or matrix.

See also

concatenate
Join a sequence of arrays together.
c_
Translates slice objects to concatenation along the second axis.

Examples

>>> np.r_[np.array([1,2,3]), 0, 0, np.array([4,5,6])]
array([1, 2, 3, 0, 0, 4, 5, 6])
>>> np.r_[-1:1:6j, [0]*3, 5, 6]
array([-1. , -0.6, -0.2,  0.2,  0.6,  1. ,  0. ,  0. ,  0. ,  5. ,  6. ])

String integers specify the axis to concatenate along or the minimum number of dimensions to force entries into.

>>> a = np.array([[0, 1, 2], [3, 4, 5]])
>>> np.r_['-1', a, a] # concatenate along last axis
array([[0, 1, 2, 0, 1, 2],
       [3, 4, 5, 3, 4, 5]])
>>> np.r_['0,2', [1,2,3], [4,5,6]] # concatenate along first axis, dim>=2
array([[1, 2, 3],
       [4, 5, 6]])

>>> np.r_['0,2,0', [1,2,3], [4,5,6]]
array([[1],
       [2],
       [3],
       [4],
       [5],
       [6]])
>>> np.r_['1,2,0', [1,2,3], [4,5,6]]
array([[1, 4],
       [2, 5],
       [3, 6]])

Using ‘r’ or ‘c’ as a first string argument creates a matrix.

>>> np.r_['r',[1,2,3], [4,5,6]]
matrix([[1, 2, 3, 4, 5, 6]])


numpy.s

  • Indexing routines
  • next
  • previous

Previous topic

numpy.r

Next topic

numpy.nonzero

numpy.s

numpy.s_ = <numpy.lib.index_tricks.IndexExpression object at 0x0000000004652048>

A nicer way to build up index tuples for arrays.

Note

Use one of the two predefined instances index_exp or s_ rather than directly using IndexExpression.

For any index combination, including slicing and axis insertion, a[indices] is the same as a[np.index_exp[indices]] for any array a. However, np.index_exp[indices] can be used anywhere in Python code and returns a tuple of slice objects that can be used in the construction of complex index expressions.

Parameters:

maketuple : bool

If True, always returns a tuple.

See also

index_exp
Predefined instance that always returns a tuple: index_exp = IndexExpression(maketuple=True).
s_
Predefined instance without tuple conversion: s_ = IndexExpression(maketuple=False).

Notes

You can do all this with slice() plus a few special objects, but there’s a lot to remember and this version is simpler because it uses the standard array indexing syntax.

Examples

>>> np.s_[2::2]
slice(2, None, 2)
>>> np.index_exp[2::2]
(slice(2, None, 2),)

>>> np.array([0, 1, 2, 3, 4])[np.s_[2::2]]
array([2, 4])


numpy.nonzero

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.argwhere

Next topic

numpy.flatnonzero

numpy.nonzero

numpy.nonzero(a) [source]

Return the indices of the elements that are non-zero.

Returns a tuple of arrays, one for each dimension of a, containing the indices of the non-zero elements in that dimension. The corresponding non-zero values can be obtained with:

a[nonzero(a)]

To group the indices by element, rather than dimension, use:

transpose(nonzero(a))

The result of this is always a 2-D array, with a row for each non-zero element.

Parameters:

a : array_like

Input array.
Returns:

tuple_of_arrays : tuple

Indices of elements that are non-zero.

See also

flatnonzero
Return indices that are non-zero in the flattened version of the input array.
ndarray.nonzero
Equivalent ndarray method.
count_nonzero
Counts the number of non-zero elements in the input array.

Examples

>>> x = np.eye(3)
>>> x
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
>>> np.nonzero(x)
(array([0, 1, 2]), array([0, 1, 2]))

>>> x[np.nonzero(x)]
array([ 1.,  1.,  1.])
>>> np.transpose(np.nonzero(x))
array([[0, 0],
       [1, 1],
       [2, 2]])

A common use for nonzero is to find the indices of an array, where a condition is True. Given an array a, the condition a > 3 is a boolean array and since False is interpreted as 0, np.nonzero(a > 3) yields the indices of the a where the condition is true.

>>> a = np.array([[1,2,3],[4,5,6],[7,8,9]])
>>> a > 3
array([[False, False, False],
       [ True,  True,  True],
       [ True,  True,  True]], dtype=bool)
>>> np.nonzero(a > 3)
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))

The nonzero method of the boolean array can also be called.

>>> (a > 3).nonzero()
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))


numpy.where

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.flatnonzero

Next topic

numpy.searchsorted

numpy.where

numpy.where(condition[, x, y])

Return elements, either from x or y, depending on condition.

If only condition is given, return condition.nonzero().

Parameters:

condition : array_like, bool

When True, yield x, otherwise yield y.

x, y : array_like, optional

Values from which to choose. x and y need to have the same shape as condition.
Returns:

out : ndarray or tuple of ndarrays

If both x and y are specified, the output array contains elements of x where condition is True, and elements from y elsewhere.

If only condition is given, return the tuple condition.nonzero(), the indices where condition is True.

See also

nonzero, choose

Notes

If x and y are given and input arrays are 1-D, where is equivalent to:

[xv if c else yv for (c,xv,yv) in zip(condition,x,y)]

Examples

>>> np.where([[True, False], [True, True]],
...          [[1, 2], [3, 4]],
...          [[9, 8], [7, 6]])
array([[1, 8],
       [3, 4]])

>>> np.where([[0, 1], [1, 0]])
(array([0, 1]), array([1, 0]))

>>> x = np.arange(9.).reshape(3, 3)
>>> np.where( x > 5 )
(array([2, 2, 2]), array([0, 1, 2]))
>>> x[np.where( x > 3.0 )]               # Note: result is 1D.
array([ 4.,  5.,  6.,  7.,  8.])
>>> np.where(x < 5, x, -1)               # Note: broadcasting.
array([[ 0.,  1.,  2.],
       [ 3.,  4., -1.],
       [-1., -1., -1.]])

Find the indices of elements of x that are in goodvalues.

>>> goodvalues = [3, 4, 7]
>>> ix = np.in1d(x.ravel(), goodvalues).reshape(x.shape)
>>> ix
array([[False, False, False],
       [ True,  True, False],
       [False,  True, False]], dtype=bool)
>>> np.where(ix)
(array([1, 1, 2]), array([0, 1, 1]))


numpy.indices

  • Indexing routines
  • next
  • previous

Previous topic

numpy.where

Next topic

numpy.ix

numpy.indices

numpy.indices(dimensions, dtype=<type 'int'>) [source]

Return an array representing the indices of a grid.

Compute an array where the subarrays contain index values 0,1,... varying only along the corresponding axis.

Parameters:

dimensions : sequence of ints

The shape of the grid.

dtype : dtype, optional

Data type of the result.
Returns:

grid : ndarray

The array of grid indices, grid.shape = (len(dimensions),) + tuple(dimensions).

See also

mgrid, meshgrid

Notes

The output shape is obtained by prepending the number of dimensions in front of the tuple of dimensions, i.e. if dimensions is a tuple (r0, ..., rN-1) of length N, the output shape is (N,r0,...,rN-1).

The subarrays grid[k] contains the N-D array of indices along the k-th axis. Explicitly:

grid[k,i0,i1,...,iN-1] = ik

Examples

>>> grid = np.indices((2, 3))
>>> grid.shape
(2, 2, 3)
>>> grid[0]        # row indices
array([[0, 0, 0],
       [1, 1, 1]])
>>> grid[1]        # column indices
array([[0, 1, 2],
       [0, 1, 2]])

The indices can be used as an index into an array.

>>> x = np.arange(20).reshape(5, 4)
>>> row, col = np.indices((2, 3))
>>> x[row, col]
array([[0, 1, 2],
       [4, 5, 6]])

Note that it would be more straightforward in the above example to extract the required elements directly with x[:2, :3].


numpy.ix

  • Indexing routines
  • next
  • previous

Previous topic

numpy.indices

Next topic

numpy.ogrid

numpy.ix

numpy.ix_(*args) [source]

Construct an open mesh from multiple sequences.

This function takes N 1-D sequences and returns N outputs with N dimensions each, such that the shape is 1 in all but one dimension and the dimension with the non-unit shape value cycles through all N dimensions.

Using ix_ one can quickly construct index arrays that will index the cross product. a[np.ix_([1,3],[2,5])] returns the array [[a[1,2] a[1,5]], [a[3,2] a[3,5]]].

Parameters:

args : 1-D sequences
Returns:

out : tuple of ndarrays

N arrays with N dimensions each, with N the number of input sequences. Together these arrays form an open mesh.

See also

ogrid, mgrid, meshgrid

Examples

>>> a = np.arange(10).reshape(2, 5)
>>> a
array([[0, 1, 2, 3, 4],
       [5, 6, 7, 8, 9]])
>>> ixgrid = np.ix_([0,1], [2,4])
>>> ixgrid
(array([[0],
       [1]]), array([[2, 4]]))
>>> ixgrid[0].shape, ixgrid[1].shape
((2, 1), (1, 2))
>>> a[ixgrid]
array([[2, 4],
       [7, 9]])


numpy.ravel_multi_index

  • Indexing routines
  • next
  • previous

Previous topic

numpy.ogrid

Next topic

numpy.unravel_index

numpy.ravel_multi_index

numpy.ravel_multi_index(multi_index, dims, mode='raise', order='C')

Converts a tuple of index arrays into an array of flat indices, applying boundary modes to the multi-index.

Parameters:

multi_index : tuple of array_like

A tuple of integer arrays, one array for each dimension.

dims : tuple of ints

The shape of array into which the indices from multi_index apply.

mode : {‘raise’, ‘wrap’, ‘clip’}, optional

Specifies how out-of-bounds indices are handled. Can specify either one mode or a tuple of modes, one mode per index.

  • ‘raise’ – raise an error (default)
  • ‘wrap’ – wrap around
  • ‘clip’ – clip to the range

In ‘clip’ mode, a negative index which would normally wrap will clip to 0 instead.

order : {‘C’, ‘F’}, optional

Determines whether the multi-index should be viewed as indexing in C (row-major) order or FORTRAN (column-major) order.
Returns:

raveled_indices : ndarray

An array of indices into the flattened version of an array of dimensions dims.

See also

unravel_index

Notes

New in version 1.6.0.

Examples

>>> arr = np.array([[3,6,6],[4,5,1]])
>>> np.ravel_multi_index(arr, (7,6))
array([22, 41, 37])
>>> np.ravel_multi_index(arr, (7,6), order='F')
array([31, 41, 13])
>>> np.ravel_multi_index(arr, (4,6), mode='clip')
array([22, 23, 19])
>>> np.ravel_multi_index(arr, (4,4), mode=('clip','wrap'))
array([12, 13, 13])

>>> np.ravel_multi_index((3,1,4,1), (6,7,8,9))
1621


numpy.unravel_index

  • Indexing routines
  • next
  • previous

Previous topic

numpy.ravel_multi_index

Next topic

numpy.diag_indices

numpy.unravel_index

numpy.unravel_index(indices, dims, order='C')

Converts a flat index or array of flat indices into a tuple of coordinate arrays.

Parameters:

indices : array_like

An integer array whose elements are indices into the flattened version of an array of dimensions dims. Before version 1.6.0, this function accepted just one index value.

dims : tuple of ints

The shape of the array to use for unraveling indices.

order : {‘C’, ‘F’}, optional

New in version 1.6.0.

Determines whether the indices should be viewed as indexing in C (row-major) order or FORTRAN (column-major) order.
Returns:

unraveled_coords : tuple of ndarray

Each array in the tuple has the same shape as the indices array.

See also

ravel_multi_index

Examples

>>> np.unravel_index([22, 41, 37], (7,6))
(array([3, 6, 6]), array([4, 5, 1]))
>>> np.unravel_index([31, 41, 13], (7,6), order='F')
(array([3, 6, 6]), array([4, 5, 1]))

>>> np.unravel_index(1621, (6,7,8,9))
(3, 1, 4, 1)


numpy.diag_indices

  • Indexing routines
  • next
  • previous

Previous topic

numpy.unravel_index

Next topic

numpy.diag_indices_from

numpy.diag_indices

numpy.diag_indices(n, ndim=2) [source]

Return the indices to access the main diagonal of an array.

This returns a tuple of indices that can be used to access the main diagonal of an array a with a.ndim >= 2 dimensions and shape (n, n, ..., n). For a.ndim = 2 this is the usual diagonal, for a.ndim > 2 this is the set of indices to access a[i, i, ..., i] for i = [0..n-1].

Parameters:

n : int

The size, along each dimension, of the arrays for which the returned indices can be used.

ndim : int, optional

The number of dimensions.

See also

diag_indices_from

Notes

New in version 1.4.0.

Examples

Create a set of indices to access the diagonal of a (4, 4) array:

>>> di = np.diag_indices(4)
>>> di
(array([0, 1, 2, 3]), array([0, 1, 2, 3]))
>>> a = np.arange(16).reshape(4, 4)
>>> a
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11],
       [12, 13, 14, 15]])
>>> a[di] = 100
>>> a
array([[100,   1,   2,   3],
       [  4, 100,   6,   7],
       [  8,   9, 100,  11],
       [ 12,  13,  14, 100]])

Now, we create indices to manipulate a 3-D array:

>>> d3 = np.diag_indices(2, 3)
>>> d3
(array([0, 1]), array([0, 1]), array([0, 1]))

And use it to set the diagonal of an array of zeros to 1:

>>> a = np.zeros((2, 2, 2), dtype=np.int)
>>> a[d3] = 1
>>> a
array([[[1, 0],
        [0, 0]],
       [[0, 0],
        [0, 1]]])


numpy.diag_indices_from

  • Indexing routines
  • next
  • previous

Previous topic

numpy.diag_indices

Next topic

numpy.mask_indices

numpy.diag_indices_from

numpy.diag_indices_from(arr) [source]

Return the indices to access the main diagonal of an n-dimensional array.

See diag_indices for full details.

Parameters: arr : array, at least 2-D

See also

diag_indices

Notes

New in version 1.4.0.


numpy.mask_indices

  • Indexing routines
  • next
  • previous

Previous topic

numpy.diag_indices_from

Next topic

numpy.tril_indices

numpy.mask_indices

numpy.mask_indices(n, mask_func, k=0) [source]

Return the indices to access (n, n) arrays, given a masking function.

Assume mask_func is a function that, for a square array a of size (n, n) with a possible offset argument k, when called as mask_func(a, k) returns a new array with zeros in certain locations (functions like triu or tril do precisely this). Then this function returns the indices where the non-zero values would be located.

Parameters:

n : int

The returned indices will be valid to access arrays of shape (n, n).

mask_func : callable

A function whose call signature is similar to that of triu, tril. That is, mask_func(x, k) returns a boolean array, shaped like x. k is an optional argument to the function.

k : scalar

An optional argument which is passed through to mask_func. Functions like triu, tril take a second argument that is interpreted as an offset.
Returns:

indices : tuple of arrays.

The n arrays of indices corresponding to the locations where mask_func(np.ones((n, n)), k) is True.

See also

triu, tril, triu_indices, tril_indices

Notes

New in version 1.4.0.

Examples

These are the indices that would allow you to access the upper triangular part of any 3x3 array:

>>> iu = np.mask_indices(3, np.triu)

For example, if a is a 3x3 array:

>>> a = np.arange(9).reshape(3, 3)
>>> a
array([[0, 1, 2],
       [3, 4, 5],
       [6, 7, 8]])
>>> a[iu]
array([0, 1, 2, 4, 5, 8])

An offset can be passed also to the masking function. This gets us the indices starting on the first diagonal right of the main one:

>>> iu1 = np.mask_indices(3, np.triu, 1)

with which we now extract only three elements:

>>> a[iu1]
array([1, 2, 5])


numpy.tril_indices

  • Indexing routines
  • next
  • previous

Previous topic

numpy.mask_indices

Next topic

numpy.tril_indices_from

numpy.tril_indices

numpy.tril_indices(n, k=0, m=None) [source]

Return the indices for the lower-triangle of an (n, m) array.

Parameters:

n : int

The row dimension of the arrays for which the returned indices will be valid.

k : int, optional

Diagonal offset (see tril for details).

m : int, optional

New in version 1.9.0.

The column dimension of the arrays for which the returned arrays will be valid. By default m is taken equal to n.
Returns:

inds : tuple of arrays

The indices for the triangle. The returned tuple contains two arrays, each with the indices along one dimension of the array.

See also

triu_indices
similar function, for upper-triangular.
mask_indices
generic function accepting an arbitrary mask function.

tril, triu

Notes

New in version 1.4.0.

Examples

Compute two different sets of indices to access 4x4 arrays, one for the lower triangular part starting at the main diagonal, and one starting two diagonals further right:

>>> il1 = np.tril_indices(4)
>>> il2 = np.tril_indices(4, 2)

Here is how they can be used with a sample array:

>>> a = np.arange(16).reshape(4, 4)
>>> a
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11],
       [12, 13, 14, 15]])

Both for indexing:

>>> a[il1]
array([ 0,  4,  5,  8,  9, 10, 12, 13, 14, 15])

And for assigning values:

>>> a[il1] = -1
>>> a
array([[-1,  1,  2,  3],
       [-1, -1,  6,  7],
       [-1, -1, -1, 11],
       [-1, -1, -1, -1]])

These cover almost the whole array (two diagonals right of the main one):

>>> a[il2] = -10
>>> a
array([[-10, -10, -10,   3],
       [-10, -10, -10, -10],
       [-10, -10, -10, -10],
       [-10, -10, -10, -10]])


numpy.tril_indices_from

  • Indexing routines
  • next
  • previous

Previous topic

numpy.tril_indices

Next topic

numpy.triu_indices

numpy.tril_indices_from

numpy.tril_indices_from(arr, k=0) [source]

Return the indices for the lower-triangle of arr.

See tril_indices for full details.

Parameters:

arr : array_like

The indices will be valid for square arrays whose dimensions are the same as arr.

k : int, optional

Diagonal offset (see tril for details).

See also

tril_indices, tril

Notes

New in version 1.4.0.


numpy.triu_indices

  • Indexing routines
  • next
  • previous

Previous topic

numpy.tril_indices_from

Next topic

numpy.triu_indices_from

numpy.triu_indices

numpy.triu_indices(n, k=0, m=None) [source]

Return the indices for the upper-triangle of an (n, m) array.

Parameters:

n : int

The size of the arrays for which the returned indices will be valid.

k : int, optional

Diagonal offset (see triu for details).

m : int, optional

New in version 1.9.0.

The column dimension of the arrays for which the returned arrays will be valid. By default m is taken equal to n.
Returns:

inds : tuple, shape(2) of ndarrays, shape(n)

The indices for the triangle. The returned tuple contains two arrays, each with the indices along one dimension of the array. Can be used to slice a ndarray of shape(n, n).

See also

tril_indices
similar function, for lower-triangular.
mask_indices
generic function accepting an arbitrary mask function.

triu, tril

Notes

New in version 1.4.0.

Examples

Compute two different sets of indices to access 4x4 arrays, one for the upper triangular part starting at the main diagonal, and one starting two diagonals further right:

>>> iu1 = np.triu_indices(4)
>>> iu2 = np.triu_indices(4, 2)

Here is how they can be used with a sample array:

>>> a = np.arange(16).reshape(4, 4)
>>> a
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11],
       [12, 13, 14, 15]])

Both for indexing:

>>> a[iu1]
array([ 0,  1,  2,  3,  5,  6,  7, 10, 11, 15])

And for assigning values:

>>> a[iu1] = -1
>>> a
array([[-1, -1, -1, -1],
       [ 4, -1, -1, -1],
       [ 8,  9, -1, -1],
       [12, 13, 14, -1]])

These cover only a small part of the whole array (two diagonals right of the main one):

>>> a[iu2] = -10
>>> a
array([[ -1,  -1, -10, -10],
       [  4,  -1,  -1, -10],
       [  8,   9,  -1,  -1],
       [ 12,  13,  14,  -1]])


numpy.triu_indices_from

  • Indexing routines
  • next
  • previous

Previous topic

numpy.triu_indices

Next topic

numpy.take

numpy.triu_indices_from

numpy.triu_indices_from(arr, k=0) [source]

Return the indices for the upper-triangle of arr.

See triu_indices for full details.

Parameters:

arr : ndarray, shape(N, N)

The indices will be valid for square arrays.

k : int, optional

Diagonal offset (see triu for details).
Returns:

triu_indices_from : tuple, shape(2) of ndarray, shape(N)

Indices for the upper-triangle of arr.

See also

triu_indices, triu

Notes

New in version 1.4.0.


numpy.take

  • Indexing routines
  • next
  • previous

Previous topic

numpy.triu_indices_from

Next topic

numpy.choose

numpy.take

numpy.take(a, indices, axis=None, out=None, mode='raise') [source]

Take elements from an array along an axis.

This function does the same thing as “fancy” indexing (indexing arrays using arrays); however, it can be easier to use if you need elements along a given axis.

Parameters:

a : array_like

The source array.

indices : array_like

The indices of the values to extract.

New in version 1.8.0.

Also allow scalars for indices.

axis : int, optional

The axis over which to select values. By default, the flattened input array is used.

out : ndarray, optional

If provided, the result will be placed in this array. It should be of the appropriate shape and dtype.

mode : {‘raise’, ‘wrap’, ‘clip’}, optional

Specifies how out-of-bounds indices will behave.

  • ‘raise’ – raise an error (default)
  • ‘wrap’ – wrap around
  • ‘clip’ – clip to the range

‘clip’ mode means that all indices that are too large are replaced by the index that addresses the last element along that axis. Note that this disables indexing with negative numbers.
Returns:

subarray : ndarray

The returned array has the same type as a.

See also

compress
Take elements using a boolean mask
ndarray.take
equivalent method

Examples

>>> a = [4, 3, 5, 7, 6, 8]
>>> indices = [0, 1, 4]
>>> np.take(a, indices)
array([4, 3, 6])

In this example if a is an ndarray, “fancy” indexing can be used.

>>> a = np.array(a)
>>> a[indices]
array([4, 3, 6])

If indices is not one dimensional, the output also has these dimensions.

>>> np.take(a, [[0, 1], [2, 3]])
array([[4, 3],
       [5, 7]])


numpy.choose

  • Indexing routines
  • next
  • previous

Previous topic

numpy.take

Next topic

numpy.compress

numpy.choose

numpy.choose(a, choices, out=None, mode='raise') [source]

Construct an array from an index array and a set of arrays to choose from.

First of all, if confused or uncertain, definitely look at the Examples - in its full generality, this function is less simple than it might seem from the following code description (below ndi = numpy.lib.index_tricks):

np.choose(a,c) == np.array([c[a[I]][I] for I in ndi.ndindex(a.shape)]).

But this omits some subtleties. Here is a fully general summary:

Given an “index” array (a) of integers and a sequence of n arrays (choices), a and each choice array are first broadcast, as necessary, to arrays of a common shape; calling these Ba and Bchoices[i], i = 0,...,n-1 we have that, necessarily, Ba.shape == Bchoices[i].shape for each i. Then, a new array with shape Ba.shape is created as follows:

  • if mode=raise (the default), then, first of all, each element of a (and thus Ba) must be in the range [0, n-1]; now, suppose that i (in that range) is the value at the (j0, j1, ..., jm) position in Ba - then the value at the same position in the new array is the value in Bchoices[i] at that same position;
  • if mode=wrap, values in a (and thus Ba) may be any (signed) integer; modular arithmetic is used to map integers outside the range [0, n-1] back into that range; and then the new array is constructed as above;
  • if mode=clip, values in a (and thus Ba) may be any (signed) integer; negative integers are mapped to 0; values greater than n-1 are mapped to n-1; and then the new array is constructed as above.
Parameters:

a : int array

This array must contain integers in [0, n-1], where n is the number of choices, unless mode=wrap or mode=clip, in which cases any integers are permissible.

choices : sequence of arrays

Choice arrays. a and all of the choices must be broadcastable to the same shape. If choices is itself an array (not recommended), then its outermost dimension (i.e., the one corresponding to choices.shape[0]) is taken as defining the “sequence”.

out : array, optional

If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype.

mode : {‘raise’ (default), ‘wrap’, ‘clip’}, optional

Specifies how indices outside [0, n-1] will be treated:

  • ‘raise’ : an exception is raised
  • ‘wrap’ : value becomes value mod n
  • ‘clip’ : values < 0 are mapped to 0, values > n-1 are mapped to n-1
Returns:

merged_array : array

The merged result.
Raises:

ValueError: shape mismatch

If a and each choice array are not all broadcastable to the same shape.

See also

ndarray.choose
equivalent method

Notes

To reduce the chance of misinterpretation, even though the following “abuse” is nominally supported, choices should neither be, nor be thought of as, a single array, i.e., the outermost sequence-like container should be either a list or a tuple.

Examples

>>> choices = [[0, 1, 2, 3], [10, 11, 12, 13],
...   [20, 21, 22, 23], [30, 31, 32, 33]]
>>> np.choose([2, 3, 1, 0], choices
... # the first element of the result will be the first element of the
... # third (2+1) "array" in choices, namely, 20; the second element
... # will be the second element of the fourth (3+1) choice array, i.e.,
... # 31, etc.
... )
array([20, 31, 12,  3])
>>> np.choose([2, 4, 1, 0], choices, mode='clip') # 4 goes to 3 (4-1)
array([20, 31, 12,  3])
>>> # because there are 4 choice arrays
>>> np.choose([2, 4, 1, 0], choices, mode='wrap') # 4 goes to (4 mod 4)
array([20,  1, 12,  3])
>>> # i.e., 0

A couple examples illustrating how choose broadcasts:

>>> a = [[1, 0, 1], [0, 1, 0], [1, 0, 1]]
>>> choices = [-10, 10]
>>> np.choose(a, choices)
array([[ 10, -10,  10],
       [-10,  10, -10],
       [ 10, -10,  10]])

>>> # With thanks to Anne Archibald
>>> a = np.array([0, 1]).reshape((2,1,1))
>>> c1 = np.array([1, 2, 3]).reshape((1,3,1))
>>> c2 = np.array([-1, -2, -3, -4, -5]).reshape((1,1,5))
>>> np.choose(a, (c1, c2)) # result is 2x3x5, res[0,:,:]=c1, res[1,:,:]=c2
array([[[ 1,  1,  1,  1,  1],
        [ 2,  2,  2,  2,  2],
        [ 3,  3,  3,  3,  3]],
       [[-1, -2, -3, -4, -5],
        [-1, -2, -3, -4, -5],
        [-1, -2, -3, -4, -5]]])


numpy.compress

  • Indexing routines
  • next
  • previous

Previous topic

numpy.choose

Next topic

numpy.diag

numpy.compress

numpy.compress(condition, a, axis=None, out=None) [source]

Return selected slices of an array along given axis.

When working along a given axis, a slice along that axis is returned in output for each index where condition evaluates to True. When working on a 1-D array, compress is equivalent to extract.

Parameters:

condition : 1-D array of bools

Array that selects which entries to return. If len(condition) is less than the size of a along the given axis, then output is truncated to the length of the condition array.

a : array_like

Array from which to extract a part.

axis : int, optional

Axis along which to take slices. If None (default), work on the flattened array.

out : ndarray, optional

Output array. Its type is preserved and it must be of the right shape to hold the output.
Returns:

compressed_array : ndarray

A copy of a without the slices along axis for which condition is false.

See also

take, choose, diag, diagonal, select

ndarray.compress
Equivalent method in ndarray
np.extract
Equivalent method when working on 1-D arrays
numpy.doc.ufuncs
Section “Output arguments”

Examples

>>> a = np.array([[1, 2], [3, 4], [5, 6]])
>>> a
array([[1, 2],
       [3, 4],
       [5, 6]])
>>> np.compress([0, 1], a, axis=0)
array([[3, 4]])
>>> np.compress([False, True, True], a, axis=0)
array([[3, 4],
       [5, 6]])
>>> np.compress([False, True], a, axis=1)
array([[2],
       [4],
       [6]])

Working on the flattened array does not return slices along an axis but selects elements.

>>> np.compress([False, True], a)
array([2])


numpy.diagonal

  • Indexing routines
  • next
  • previous

Previous topic

numpy.diag

Next topic

numpy.select

numpy.diagonal

numpy.diagonal(a, offset=0, axis1=0, axis2=1) [source]

Return specified diagonals.

If a is 2-D, returns the diagonal of a with the given offset, i.e., the collection of elements of the form a[i, i+offset]. If a has more than two dimensions, then the axes specified by axis1 and axis2 are used to determine the 2-D sub-array whose diagonal is returned. The shape of the resulting array can be determined by removing axis1 and axis2 and appending an index to the right equal to the size of the resulting diagonals.

In versions of NumPy prior to 1.7, this function always returned a new, independent array containing a copy of the values in the diagonal.

In NumPy 1.7 and 1.8, it continues to return a copy of the diagonal, but depending on this fact is deprecated. Writing to the resulting array continues to work as it used to, but a FutureWarning is issued.

In NumPy 1.9 it returns a read-only view on the original array. Attempting to write to the resulting array will produce an error.

In NumPy 1.10, it will return a read/write view, Writing to the returned array will alter your original array.

If you don’t write to the array returned by this function, then you can just ignore all of the above.

If you depend on the current behavior, then we suggest copying the returned array explicitly, i.e., use np.diagonal(a).copy() instead of just np.diagonal(a). This will work with both past and future versions of NumPy.

Parameters:

a : array_like

Array from which the diagonals are taken.

offset : int, optional

Offset of the diagonal from the main diagonal. Can be positive or negative. Defaults to main diagonal (0).

axis1 : int, optional

Axis to be used as the first axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults to first axis (0).

axis2 : int, optional

Axis to be used as the second axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults to second axis (1).
Returns:

array_of_diagonals : ndarray

If a is 2-D, a 1-D array containing the diagonal is returned. If the dimension of a is larger, then an array of diagonals is returned, “packed” from left-most dimension to right-most (e.g., if a is 3-D, then the diagonals are “packed” along rows).
Raises:

ValueError

If the dimension of a is less than 2.

See also

diag
MATLAB work-a-like for 1-D and 2-D arrays.
diagflat
Create diagonal arrays.
trace
Sum along diagonals.

Examples

>>> a = np.arange(4).reshape(2,2)
>>> a
array([[0, 1],
       [2, 3]])
>>> a.diagonal()
array([0, 3])
>>> a.diagonal(1)
array([1])

A 3-D example:

>>> a = np.arange(8).reshape(2,2,2); a
array([[[0, 1],
        [2, 3]],
       [[4, 5],
        [6, 7]]])
>>> a.diagonal(0, # Main diagonals of two arrays created by skipping
...            0, # across the outer(left)-most axis last and
...            1) # the "middle" (row) axis first.
array([[0, 6],
       [1, 7]])

The sub-arrays whose main diagonals we just obtained; note that each corresponds to fixing the right-most (column) axis, and that the diagonals are “packed” in rows.

>>> a[:,:,0] # main diagonal is [0 6]
array([[0, 2],
       [4, 6]])
>>> a[:,:,1] # main diagonal is [1 7]
array([[1, 3],
       [5, 7]])


numpy.select

  • Indexing routines
  • next
  • previous

Previous topic

numpy.diagonal

Next topic

numpy.place

numpy.select

numpy.select(condlist, choicelist, default=0) [source]

Return an array drawn from elements in choicelist, depending on conditions.

Parameters:

condlist : list of bool ndarrays

The list of conditions which determine from which array in choicelist the output elements are taken. When multiple conditions are satisfied, the first one encountered in condlist is used.

choicelist : list of ndarrays

The list of arrays from which the output elements are taken. It has to be of the same length as condlist.

default : scalar, optional

The element inserted in output when all conditions evaluate to False.
Returns:

output : ndarray

The output at position m is the m-th element of the array in choicelist where the m-th element of the corresponding array in condlist is True.

See also

where
Return elements from one of two arrays depending on condition.

take, choose, compress, diag, diagonal

Examples

>>> x = np.arange(10)
>>> condlist = [x<3, x>5]
>>> choicelist = [x, x**2]
>>> np.select(condlist, choicelist)
array([ 0,  1,  2,  0,  0,  0, 36, 49, 64, 81])


numpy.place

  • Indexing routines
  • next
  • previous

Previous topic

numpy.select

Next topic

numpy.put

numpy.place

numpy.place(arr, mask, vals) [source]

Change elements of an array based on conditional and input values.

Similar to np.copyto(arr, vals, where=mask), the difference is that place uses the first N elements of vals, where N is the number of True values in mask, while copyto uses the elements where mask is True.

Note that extract does the exact opposite of place.

Parameters:

arr : array_like

Array to put data into.

mask : array_like

Boolean mask array. Must have the same size as a.

vals : 1-D sequence

Values to put into a. Only the first N elements are used, where N is the number of True values in mask. If vals is smaller than N it will be repeated.

See also

copyto, put, take, extract

Examples

>>> arr = np.arange(6).reshape(2, 3)
>>> np.place(arr, arr>2, [44, 55])
>>> arr
array([[ 0,  1,  2],
       [44, 55, 44]])


numpy.put

  • Indexing routines
  • next
  • previous

Previous topic

numpy.place

Next topic

numpy.putmask

numpy.put

numpy.put(a, ind, v, mode='raise') [source]

Replaces specified elements of an array with given values.

The indexing works on the flattened target array. put is roughly equivalent to:

a.flat[ind] = v
Parameters:

a : ndarray

Target array.

ind : array_like

Target indices, interpreted as integers.

v : array_like

Values to place in a at target indices. If v is shorter than ind it will be repeated as necessary.

mode : {‘raise’, ‘wrap’, ‘clip’}, optional

Specifies how out-of-bounds indices will behave.

  • ‘raise’ – raise an error (default)
  • ‘wrap’ – wrap around
  • ‘clip’ – clip to the range

‘clip’ mode means that all indices that are too large are replaced by the index that addresses the last element along that axis. Note that this disables indexing with negative numbers.

See also

putmask, place

Examples

>>> a = np.arange(5)
>>> np.put(a, [0, 2], [-44, -55])
>>> a
array([-44,   1, -55,   3,   4])

>>> a = np.arange(5)
>>> np.put(a, 22, -5, mode='clip')
>>> a
array([ 0,  1,  2,  3, -5])


numpy.putmask

  • Indexing routines
  • next
  • previous

Previous topic

numpy.put

Next topic

numpy.fill_diagonal

numpy.putmask

numpy.putmask(a, mask, values)

Changes elements of an array based on conditional and input values.

Sets a.flat[n] = values[n] for each n where mask.flat[n]==True.

If values is not the same size as a and mask then it will repeat. This gives behavior different from a[mask] = values.

Note

The putmask functionality is also provided by copyto, which can be significantly faster and in addition is NA-aware (preservena keyword). Replacing putmask with np.copyto(a, values, where=mask) is recommended.

Parameters:

a : array_like

Target array.

mask : array_like

Boolean mask array. It has to be the same shape as a.

values : array_like

Values to put into a where mask is True. If values is smaller than a it will be repeated.

See also

place, put, take, copyto

Examples

>>> x = np.arange(6).reshape(2, 3)
>>> np.putmask(x, x>2, x**2)
>>> x
array([[ 0,  1,  2],
       [ 9, 16, 25]])

If values is smaller than a it is repeated:

>>> x = np.arange(5)
>>> np.putmask(x, x>1, [-33, -44])
>>> x
array([  0,   1, -33, -44, -33])


numpy.fill_diagonal

  • Indexing routines
  • next
  • previous

Previous topic

numpy.putmask

Next topic

numpy.nditer

numpy.fill_diagonal

numpy.fill_diagonal(a, val, wrap=False) [source]

Fill the main diagonal of the given array of any dimensionality.

For an array a with a.ndim > 2, the diagonal is the list of locations with indices a[i, i, ..., i] all identical. This function modifies the input array in-place, it does not return a value.

Parameters:

a : array, at least 2-D.

Array whose diagonal is to be filled, it gets modified in-place.

val : scalar

Value to be written on the diagonal, its type must be compatible with that of the array a.

wrap : bool

For tall matrices in NumPy version up to 1.6.2, the diagonal “wrapped” after N columns. You can have this behavior with this option. This affect only tall matrices.

See also

diag_indices, diag_indices_from

Notes

New in version 1.4.0.

This functionality can be obtained via diag_indices, but internally this version uses a much faster implementation that never constructs the indices and uses simple slicing.

Examples

>>> a = np.zeros((3, 3), int)
>>> np.fill_diagonal(a, 5)
>>> a
array([[5, 0, 0],
       [0, 5, 0],
       [0, 0, 5]])

The same function can operate on a 4-D array:

>>> a = np.zeros((3, 3, 3, 3), int)
>>> np.fill_diagonal(a, 4)

We only show a few blocks for clarity:

>>> a[0, 0]
array([[4, 0, 0],
       [0, 0, 0],
       [0, 0, 0]])
>>> a[1, 1]
array([[0, 0, 0],
       [0, 4, 0],
       [0, 0, 0]])
>>> a[2, 2]
array([[0, 0, 0],
       [0, 0, 0],
       [0, 0, 4]])

# tall matrices no wrap >>> a = np.zeros((5, 3),int) >>> fill_diagonal(a, 4) array([[4, 0, 0],

[0, 4, 0], [0, 0, 4], [0, 0, 0], [0, 0, 0]])

# tall matrices wrap >>> a = np.zeros((5, 3),int) >>> fill_diagonal(a, 4) array([[4, 0, 0],

[0, 4, 0], [0, 0, 4], [0, 0, 0], [4, 0, 0]])

# wide matrices >>> a = np.zeros((3, 5),int) >>> fill_diagonal(a, 4) array([[4, 0, 0, 0, 0],

[0, 4, 0, 0, 0], [0, 0, 4, 0, 0]])


numpy.nditer

  • Indexing routines
  • next
  • previous

Previous topic

numpy.fill_diagonal

Next topic

numpy.nditer.copy

numpy.nditer

class numpy.nditer [source]

Efficient multi-dimensional iterator object to iterate over arrays. To get started using this object, see the introductory guide to array iteration.

Parameters:

op : ndarray or sequence of array_like

The array(s) to iterate over.

flags : sequence of str, optional

Flags to control the behavior of the iterator.

  • “buffered” enables buffering when required.
  • “c_index” causes a C-order index to be tracked.
  • “f_index” causes a Fortran-order index to be tracked.
  • “multi_index” causes a multi-index, or a tuple of indices with one per iteration dimension, to be tracked.
  • “common_dtype” causes all the operands to be converted to a common data type, with copying or buffering as necessary.
  • “delay_bufalloc” delays allocation of the buffers until a reset() call is made. Allows “allocate” operands to be initialized before their values are copied into the buffers.
  • “external_loop” causes the values given to be one-dimensional arrays with multiple values instead of zero-dimensional arrays.
  • “grow_inner” allows the value array sizes to be made larger than the buffer size when both “buffered” and “external_loop” is used.
  • “ranged” allows the iterator to be restricted to a sub-range of the iterindex values.
  • “refs_ok” enables iteration of reference types, such as object arrays.
  • “reduce_ok” enables iteration of “readwrite” operands which are broadcasted, also known as reduction operands.
  • “zerosize_ok” allows itersize to be zero.

op_flags : list of list of str, optional

This is a list of flags for each operand. At minimum, one of “readonly”, “readwrite”, or “writeonly” must be specified.

  • “readonly” indicates the operand will only be read from.
  • “readwrite” indicates the operand will be read from and written to.
  • “writeonly” indicates the operand will only be written to.
  • “no_broadcast” prevents the operand from being broadcasted.
  • “contig” forces the operand data to be contiguous.
  • “aligned” forces the operand data to be aligned.
  • “nbo” forces the operand data to be in native byte order.
  • “copy” allows a temporary read-only copy if required.
  • “updateifcopy” allows a temporary read-write copy if required.
  • “allocate” causes the array to be allocated if it is None in the op parameter.
  • “no_subtype” prevents an “allocate” operand from using a subtype.
  • “arraymask” indicates that this operand is the mask to use for selecting elements when writing to operands with the ‘writemasked’ flag set. The iterator does not enforce this, but when writing from a buffer back to the array, it only copies those elements indicated by this mask.
  • ‘writemasked’ indicates that only elements where the chosen ‘arraymask’ operand is True will be written to.

op_dtypes : dtype or tuple of dtype(s), optional

The required data type(s) of the operands. If copying or buffering is enabled, the data will be converted to/from their original types.

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the iteration order. ‘C’ means C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran contiguous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements appear in memory as possible. This also affects the element memory order of “allocate” operands, as they are allocated to be compatible with iteration order. Default is ‘K’.

casting : {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

Controls what kind of data casting may occur when making a copy or buffering. Setting this to ‘unsafe’ is not recommended, as it can adversely affect accumulations.

  • ‘no’ means the data types should not be cast at all.
  • ‘equiv’ means only byte-order changes are allowed.
  • ‘safe’ means only casts which can preserve values are allowed.
  • ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.
  • ‘unsafe’ means any data conversions may be done.

op_axes : list of list of ints, optional

If provided, is a list of ints or None for each operands. The list of axes for an operand is a mapping from the dimensions of the iterator to the dimensions of the operand. A value of -1 can be placed for entries, causing that dimension to be treated as “newaxis”.

itershape : tuple of ints, optional

The desired shape of the iterator. This allows “allocate” operands with a dimension mapped by op_axes not corresponding to a dimension of a different operand to get a value not equal to 1 for that dimension.

buffersize : int, optional

When buffering is enabled, controls the size of the temporary buffers. Set to 0 for the default value.

Notes

nditer supersedes flatiter. The iterator implementation behind nditer is also exposed by the Numpy C API.

The Python exposure supplies two iteration interfaces, one which follows the Python iterator protocol, and another which mirrors the C-style do-while pattern. The native Python approach is better in most cases, but if you need the iterator’s coordinates or index, use the C-style pattern.

Examples

Here is how we might write an iter_add function, using the Python iterator protocol:

def iter_add_py(x, y, out=None):
    addop = np.add
    it = np.nditer([x, y, out], [],
                [['readonly'], ['readonly'], ['writeonly','allocate']])
    for (a, b, c) in it:
        addop(a, b, out=c)
    return it.operands[2]

Here is the same function, but following the C-style pattern:

def iter_add(x, y, out=None):
    addop = np.add

    it = np.nditer([x, y, out], [],
                [['readonly'], ['readonly'], ['writeonly','allocate']])

    while not it.finished:
        addop(it[0], it[1], out=it[2])
        it.iternext()

    return it.operands[2]

Here is an example outer product function:

def outer_it(x, y, out=None):
    mulop = np.multiply

    it = np.nditer([x, y, out], ['external_loop'],
            [['readonly'], ['readonly'], ['writeonly', 'allocate']],
            op_axes=[range(x.ndim)+[-1]*y.ndim,
                     [-1]*x.ndim+range(y.ndim),
                     None])

    for (a, b, c) in it:
        mulop(a, b, out=c)

    return it.operands[2]

>>> a = np.arange(2)+1
>>> b = np.arange(3)+1
>>> outer_it(a,b)
array([[1, 2, 3],
       [2, 4, 6]])

Here is an example function which operates like a “lambda” ufunc:

def luf(lamdaexpr, *args, **kwargs):
    "luf(lambdaexpr, op1, ..., opn, out=None, order='K', casting='safe', buffersize=0)"
    nargs = len(args)
    op = (kwargs.get('out',None),) + args
    it = np.nditer(op, ['buffered','external_loop'],
            [['writeonly','allocate','no_broadcast']] +
                            [['readonly','nbo','aligned']]*nargs,
            order=kwargs.get('order','K'),
            casting=kwargs.get('casting','safe'),
            buffersize=kwargs.get('buffersize',0))
    while not it.finished:
        it[0] = lamdaexpr(*it[1:])
        it.iternext()
    return it.operands[0]

>>> a = np.arange(5)
>>> b = np.ones(5)
>>> luf(lambda i,j:i*i + j/2, a, b)
array([  0.5,   1.5,   4.5,   9.5,  16.5])

Attributes

dtypes | (tuple of dtype(s)) The data types of the values provided in value. This may be different from the operand data types if buffering is enabled.
finished | (bool) Whether the iteration over the operands is finished or not.
has_delayed_bufalloc | (bool) If True, the iterator was created with the “delay_bufalloc” flag, and no reset() function was called on it yet.
has_index | (bool) If True, the iterator was created with either the “c_index” or the “f_index” flag, and the property index can be used to retrieve it.
has_multi_index | (bool) If True, the iterator was created with the “multi_index” flag, and the property multi_index can be used to retrieve it.
index : When the “c_index” or “f_index” flag was used, this property provides access to the index. Raises a ValueError if accessed and has_index is False.
iterationneedsapi | (bool) Whether iteration requires access to the Python API, for example if one of the operands is an object array.
iterindex | (int) An index which matches the order of iteration.
itersize | (int) Size of the iterator.
itviews : Structured view(s) of operands in memory, matching the reordered and optimized iterator access pattern.
multi_index : When the “multi_index” flag was used, this property provides access to the index. Raises a ValueError if accessed accessed and has_multi_index is False.
ndim | (int) The iterator’s dimension.
nop | (int) The number of iterator operands.
operands | (tuple of operand(s)) The array(s) to be iterated over.
shape | (tuple of ints) Shape tuple, the shape of the iterator.
value : Value of operands at current iteration. Normally, this is a tuple of array scalars, but if the flag “external_loop” is used, it is a tuple of one dimensional arrays.

Methods

copy() | Get a copy of the iterator in its current state.
debug_print() | Print the current state of the nditer instance and debug info to stdout.
enable_external_loop() | When the “external_loop” was not used during construction, but is desired, this modifies the iterator to behave as if the flag was specified.
iternext() | Check whether iterations are left, and perform a single internal iteration without returning the result.
next | x.next() -> the next value, or raise StopIteration
remove_axis(i) | Removes axis i from the iterator.
remove_multi_index() | When the “multi_index” flag was specified, this removes it, allowing the internal iteration structure to be optimized further.
reset() | Reset the iterator to its initial state.


numpy.nditer.copy

  • Indexing routines
  • numpy.nditer
  • index
  • next
  • previous

Previous topic

numpy.nditer

Next topic

numpy.nditer.debug_print

numpy.nditer.copy

nditer.copy()

Get a copy of the iterator in its current state.

Examples

>>> x = np.arange(10)
>>> y = x + 1
>>> it = np.nditer([x, y])
>>> it.next()
(array(0), array(1))
>>> it2 = it.copy()
>>> it2.next()
(array(1), array(2))


numpy.nditer.debug_print

  • Indexing routines
  • numpy.nditer
  • index
  • next
  • previous

Previous topic

numpy.nditer.copy

Next topic

numpy.nditer.enable_external_loop

numpy.nditer.debug_print

nditer.debug_print()

Print the current state of the nditer instance and debug info to stdout.


numpy.nditer.enable_external_loop

  • Indexing routines
  • numpy.nditer
  • index
  • next
  • previous

Previous topic

numpy.nditer.debug_print

Next topic

numpy.nditer.iternext

numpy.nditer.enable_external_loop

nditer.enable_external_loop()

When the “external_loop” was not used during construction, but is desired, this modifies the iterator to behave as if the flag was specified.


numpy.nditer.iternext

  • Indexing routines
  • numpy.nditer
  • index
  • next
  • previous

Previous topic

numpy.nditer.enable_external_loop

Next topic

numpy.nditer.next

numpy.nditer.iternext

nditer.iternext()

Check whether iterations are left, and perform a single internal iteration without returning the result. Used in the C-style pattern do-while pattern. For an example, see nditer.

Returns:

iternext : bool

Whether or not there are iterations left.


numpy.nditer.next

  • Indexing routines
  • numpy.nditer
  • index
  • next
  • previous

Previous topic

numpy.nditer.iternext

Next topic

numpy.nditer.remove_axis

numpy.nditer.next

nditer.next

x.next() -> the next value, or raise StopIteration


numpy.nditer.remove_axis

  • Indexing routines
  • numpy.nditer
  • index
  • next
  • previous

Previous topic

numpy.nditer.next

Next topic

numpy.nditer.remove_multi_index

numpy.nditer.remove_axis

nditer.remove_axis(i)

Removes axis i from the iterator. Requires that the flag “multi_index” be enabled.


numpy.nditer.remove_multi_index

  • Indexing routines
  • numpy.nditer
  • index
  • next
  • previous

Previous topic

numpy.nditer.remove_axis

Next topic

numpy.nditer.reset

numpy.nditer.remove_multi_index

nditer.remove_multi_index()

When the “multi_index” flag was specified, this removes it, allowing the internal iteration structure to be optimized further.


numpy.nditer.reset

  • Indexing routines
  • numpy.nditer
  • index
  • next
  • previous

Previous topic

numpy.nditer.remove_multi_index

Next topic

numpy.ndenumerate

numpy.nditer.reset

nditer.reset()

Reset the iterator to its initial state.


numpy.ndindex

  • Indexing routines
  • next
  • previous

Previous topic

numpy.ndenumerate.next

Next topic

numpy.ndindex.ndincr

numpy.ndindex

class numpy.ndindex(*shape) [source]

An N-dimensional iterator object to index arrays.

Given the shape of an array, an ndindex instance iterates over the N-dimensional index of the array. At each iteration a tuple of indices is returned, the last dimension is iterated over first.

Parameters:

`*args` : ints

The size of each dimension of the array.

See also

ndenumerate, flatiter

Examples

>>> for index in np.ndindex(3, 2, 1):
...     print index
(0, 0, 0)
(0, 1, 0)
(1, 0, 0)
(1, 1, 0)
(2, 0, 0)
(2, 1, 0)

Methods

ndincr() | Increment the multi-dimensional index by one.
next() | Standard iterator method, updates the index and returns the index tuple.


numpy.ndindex.ndincr

  • Indexing routines
  • numpy.ndindex
  • index
  • next
  • previous

Previous topic

numpy.ndindex

Next topic

numpy.ndindex.next

numpy.ndindex.ndincr

ndindex.ndincr() [source]

Increment the multi-dimensional index by one.

This method is for backward compatibility only: do not use.


numpy.ndindex.next

  • Indexing routines
  • numpy.ndindex
  • index
  • next
  • previous

Previous topic

numpy.ndindex.ndincr

Next topic

numpy.flatiter

numpy.ndindex.next

ndindex.next() [source]

Standard iterator method, updates the index and returns the index tuple.

Returns:

val : tuple of ints

Returns a tuple containing the indices of the current iteration.


numpy.flatiter

  • Indexing routines
  • next
  • previous

Previous topic

numpy.ndindex.next

Next topic

numpy.flatiter.coords

numpy.flatiter

class numpy.flatiter [source]

Flat iterator object to iterate over arrays.

A flatiter iterator is returned by x.flat for any array x. It allows iterating over the array as if it were a 1-D array, either in a for-loop or by calling its next method.

Iteration is done in C-contiguous style, with the last index varying the fastest. The iterator can also be indexed using basic slicing or advanced indexing.

See also

ndarray.flat
Return a flat iterator over an array.
ndarray.flatten
Returns a flattened copy of an array.

Notes

A flatiter iterator can not be constructed directly from Python code by calling the flatiter constructor.

Examples

>>> x = np.arange(6).reshape(2, 3)
>>> fl = x.flat
>>> type(fl)
<type 'numpy.flatiter'>
>>> for item in fl:
...     print item
...
0
1
2
3
4
5

>>> fl[2:4]
array([2, 3])

Attributes

coords An N-dimensional tuple of current coordinates.

Methods

copy() | Get a copy of the iterator as a 1-D array.
next | x.next() -> the next value, or raise StopIteration


numpy.flatiter.coords

  • Indexing routines
  • numpy.flatiter
  • index
  • next
  • previous

Previous topic

numpy.flatiter

Next topic

numpy.flatiter.copy

numpy.flatiter.coords

flatiter.coords

An N-dimensional tuple of current coordinates.

Examples

>>> x = np.arange(6).reshape(2, 3)
>>> fl = x.flat
>>> fl.coords
(0, 0)
>>> fl.next()
0
>>> fl.coords
(0, 1)


numpy.flatiter.copy

  • Indexing routines
  • numpy.flatiter
  • index
  • next
  • previous

Previous topic

numpy.flatiter.coords

Next topic

numpy.flatiter.next

numpy.flatiter.copy

flatiter.copy()

Get a copy of the iterator as a 1-D array.

Examples

>>> x = np.arange(6).reshape(2, 3)
>>> x
array([[0, 1, 2],
       [3, 4, 5]])
>>> fl = x.flat
>>> fl.copy()
array([0, 1, 2, 3, 4, 5])


numpy.flatiter.next

  • Indexing routines
  • numpy.flatiter
  • index
  • next
  • previous

Previous topic

numpy.flatiter.copy

Next topic

Input and output

numpy.flatiter.next

flatiter.next

x.next() -> the next value, or raise StopIteration


Input and output

  • next
  • previous

Table Of Contents

  • Input and output
    • NPZ files
    • Text files
    • Raw binary files
    • String formatting
    • Memory mapping files
    • Text formatting options
    • Base-n representations
    • Data sources

Previous topic

numpy.flatiter.next

Next topic

numpy.load

Input and output

NPZ files

load(file[, mmap_mode]) | Load arrays or pickled objects from .npy, .npz or pickled files.
save(file, arr) | Save an array to a binary file in NumPy .npy format.
savez(file, *args, **kwds) | Save several arrays into a single file in uncompressed .npz format.
savez_compressed(file, *args, **kwds) | Save several arrays into a single file in compressed .npz format.

Text files

loadtxt(fname[, dtype, comments, delimiter, ...]) | Load data from a text file.
savetxt(fname, X[, fmt, delimiter, newline, ...]) | Save an array to a text file.
genfromtxt(fname[, dtype, comments, ...]) | Load data from a text file, with missing values handled as specified.
fromregex(file, regexp, dtype) | Construct an array from a text file, using regular expression parsing.
fromstring(string[, dtype, count, sep]) | A new 1-D array initialized from raw binary or text data in a string.
ndarray.tofile(fid[, sep, format]) | Write array to a file as text or binary (default).
ndarray.tolist() | Return the array as a (possibly nested) list.

Raw binary files

fromfile(file[, dtype, count, sep]) | Construct an array from data in a text or binary file.
ndarray.tofile(fid[, sep, format]) | Write array to a file as text or binary (default).

String formatting

array_repr(arr[, max_line_width, precision, ...]) | Return the string representation of an array.
array_str(a[, max_line_width, precision, ...]) | Return a string representation of the data in an array.

Memory mapping files

memmap Create a memory-map to an array stored in a binary file on disk.

Text formatting options

set_printoptions([precision, threshold, ...]) | Set printing options.
get_printoptions() | Return the current print options.
set_string_function(f[, repr]) | Set a Python function to be used when pretty printing arrays.

Base-n representations

binary_repr(num[, width]) | Return the binary representation of the input number as a string.
base_repr(number[, base, padding]) | Return a string representation of a number in the given base system.

Data sources

DataSource([destpath]) A generic data source file (file, http, ftp, ...).


numpy.load

  • Input and output
  • next
  • previous

Previous topic

numpy.DataSource.open

Next topic

numpy.save

numpy.load

numpy.load(file, mmap_mode=None) [source]

Load arrays or pickled objects from .npy, .npz or pickled files.

Parameters:

file : file-like object or string

The file to read. File-like objects must support the seek() and read() methods. Pickled files require that the file-like object support the readline() method as well.

mmap_mode : {None, ‘r+’, ‘r’, ‘w+’, ‘c’}, optional

If not None, then memory-map the file, using the given mode (see numpy.memmap for a detailed description of the modes). A memory-mapped array is kept on disk. However, it can be accessed and sliced like any ndarray. Memory mapping is especially useful for accessing small fragments of large files without reading the entire file into memory.
Returns:

result : array, tuple, dict, etc.

Data stored in the file. For .npz files, the returned instance of NpzFile class must be closed to avoid leaking file descriptors.
Raises:

IOError

If the input file does not exist or cannot be read.

See also

save, savez, savez_compressed, loadtxt

memmap
Create a memory-map to an array stored in a file on disk.

Notes

  • If the file contains pickle data, then whatever object is stored in the pickle is returned.

  • If the file is a .npy file, then a single array is returned.

  • If the file is a .npz file, then a dictionary-like object is returned, containing {filename: array} key-value pairs, one for each file in the archive.

  • If the file is a .npz file, the returned value supports the context manager protocol in a similar fashion to the open function:

    with load('foo.npz') as data:
    a = data['a']

    The underlying file descriptor is closed when exiting the ‘with’ block.

Examples

Store data to disk, and load it again:

>>> np.save('/tmp/123', np.array([[1, 2, 3], [4, 5, 6]]))
>>> np.load('/tmp/123.npy')
array([[1, 2, 3],
       [4, 5, 6]])

Store compressed data to disk, and load it again:

>>> a=np.array([[1, 2, 3], [4, 5, 6]])
>>> b=np.array([1, 2])
>>> np.savez('/tmp/123.npz', a=a, b=b)
>>> data = np.load('/tmp/123.npz')
>>> data['a']
array([[1, 2, 3],
       [4, 5, 6]])
>>> data['b']
array([1, 2])
>>> data.close()

Mem-map the stored array, and then access the second row directly from disk:

>>> X = np.load('/tmp/123.npy', mmap_mode='r')
>>> X[1, :]
memmap([4, 5, 6])


numpy.save

  • Input and output
  • next
  • previous

Previous topic

numpy.load

Next topic

numpy.savez

numpy.save

numpy.save(file, arr) [source]

Save an array to a binary file in NumPy .npy format.

Parameters:

file : file or str

File or filename to which the data is saved. If file is a file-object, then the filename is unchanged. If file is a string, a .npy extension will be appended to the file name if it does not already have one.

arr : array_like

Array data to be saved.

See also

savez
Save several arrays into a .npz archive

savetxt, load

Notes

For a description of the .npy format, see format.

Examples

>>> from tempfile import TemporaryFile
>>> outfile = TemporaryFile()

>>> x = np.arange(10)
>>> np.save(outfile, x)

>>> outfile.seek(0) # Only needed here to simulate closing & reopening file
>>> np.load(outfile)
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])


numpy.savez

  • Input and output
  • next
  • previous

Previous topic

numpy.save

Next topic

numpy.savez_compressed

numpy.savez

numpy.savez(file, *args, **kwds) [source]

Save several arrays into a single file in uncompressed .npz format.

If arguments are passed in with no keywords, the corresponding variable names, in the .npz file, are ‘arr_0’, ‘arr_1’, etc. If keyword arguments are given, the corresponding variable names, in the .npz file will match the keyword names.

Parameters:

file : str or file

Either the file name (string) or an open file (file-like object) where the data will be saved. If file is a string, the .npz extension will be appended to the file name if it is not already there.

args : Arguments, optional

Arrays to save to the file. Since it is not possible for Python to know the names of the arrays outside savez, the arrays will be saved with names “arr_0”, “arr_1”, and so on. These arguments can be any expression.

kwds : Keyword arguments, optional

Arrays to save to the file. Arrays will be saved in the file with the keyword names.
Returns:

None

See also

save
Save a single array to a binary file in NumPy format.
savetxt
Save an array to a file as plain text.
savez_compressed
Save several arrays into a compressed .npz archive

Notes

The .npz file format is a zipped archive of files named after the variables they contain. The archive is not compressed and each file in the archive contains one variable in .npy format. For a description of the .npy format, see format.

When opening the saved .npz file with load a NpzFile object is returned. This is a dictionary-like object which can be queried for its list of arrays (with the .files attribute), and for the arrays themselves.

Examples

>>> from tempfile import TemporaryFile
>>> outfile = TemporaryFile()
>>> x = np.arange(10)
>>> y = np.sin(x)

Using savez with *args, the arrays are saved with default names.

>>> np.savez(outfile, x, y)
>>> outfile.seek(0) # Only needed here to simulate closing & reopening file
>>> npzfile = np.load(outfile)
>>> npzfile.files
['arr_1', 'arr_0']
>>> npzfile['arr_0']
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

Using savez with **kwds, the arrays are saved with the keyword names.

>>> outfile = TemporaryFile()
>>> np.savez(outfile, x=x, y=y)
>>> outfile.seek(0)
>>> npzfile = np.load(outfile)
>>> npzfile.files
['y', 'x']
>>> npzfile['x']
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])


numpy.savez_compressed

  • Input and output
  • next
  • previous

Previous topic

numpy.savez

Next topic

numpy.loadtxt

numpy.savez_compressed

numpy.savez_compressed(file, *args, **kwds) [source]

Save several arrays into a single file in compressed .npz format.

If keyword arguments are given, then filenames are taken from the keywords. If arguments are passed in with no keywords, then stored file names are arr_0, arr_1, etc.

Parameters:

file : str

File name of .npz file.

args : Arguments

Function arguments.

kwds : Keyword arguments

Keywords.

See also

numpy.savez
Save several arrays into an uncompressed .npz file format
numpy.load
Load the files created by savez_compressed.


numpy.savetxt

  • Input and output
  • next
  • previous

Previous topic

numpy.loadtxt

Next topic

numpy.genfromtxt

numpy.savetxt

numpy.savetxt(fname, X, fmt='%.18e', delimiter=' ', newline='\n', header='', footer='', comments='# ') [source]

Save an array to a text file.

Parameters:

fname : filename or file handle

If the filename ends in .gz, the file is automatically saved in compressed gzip format. loadtxt understands gzipped files transparently.

X : array_like

Data to be saved to a text file.

fmt : str or sequence of strs, optional

A single format (%10.5f), a sequence of formats, or a multi-format string, e.g. ‘Iteration %d – %10.5f’, in which case delimiter is ignored. For complex X, the legal options for fmt are:

  1. a single specifier, fmt=’%.4e’, resulting in numbers formatted

    like ‘ (%s+%sj)’ % (fmt, fmt)

  2. a full string specifying every real and imaginary part, e.g.

    ‘ %.4e %+.4j %.4e %+.4j %.4e %+.4j’ for 3 columns

  3. a list of specifiers, one per column - in this case, the real

    and imaginary part must have separate specifiers, e.g. [‘%.3e + %.3ej’, ‘(%.15e%+.15ej)’] for 2 columns

delimiter : str, optional

String or character separating columns.

newline : str, optional

String or character separating lines.

New in version 1.5.0.

header : str, optional

String that will be written at the beginning of the file.

New in version 1.7.0.

footer : str, optional

String that will be written at the end of the file.

New in version 1.7.0.

comments : str, optional

String that will be prepended to the header and footer strings, to mark them as comments. Default: ‘# ‘, as expected by e.g. numpy.loadtxt.

New in version 1.7.0.

See also

save
Save an array to a binary file in NumPy .npy format
savez
Save several arrays into an uncompressed .npz archive
savez_compressed
Save several arrays into a compressed .npz archive

Notes

Further explanation of the fmt parameter (%[flag]width[.precision]specifier):

flags:

- : left justify

+ : Forces to precede result with + or -.

0 : Left pad the number with zeros instead of space (see width).

width:
Minimum number of characters to be printed. The value is not truncated if it has more characters.
precision:
  • For integer specifiers (eg. d,i,o,x), the minimum number of digits.
  • For e, E and f specifiers, the number of digits to print after the decimal point.
  • For g and G, the maximum number of significant digits.
  • For s, the maximum number of characters.
specifiers:

c : character

d or i : signed decimal integer

e or E : scientific notation with e or E.

f : decimal floating point

g,G : use the shorter of e,E or f

o : signed octal

s : string of characters

u : unsigned decimal integer

x,X : unsigned hexadecimal integer

This explanation of fmt is not complete, for an exhaustive specification see [R244].

References

[R244] (1, 2) Format Specification Mini-Language, Python Documentation.

Examples

>>> x = y = z = np.arange(0.0,5.0,1.0)
>>> np.savetxt('test.out', x, delimiter=',')   # X is an array
>>> np.savetxt('test.out', (x,y,z))   # x,y,z equal sized 1D arrays
>>> np.savetxt('test.out', x, fmt='%1.4e')   # use exponential notation


numpy.genfromtxt

  • Input and output
  • next
  • previous

Previous topic

numpy.savetxt

Next topic

numpy.fromregex

numpy.genfromtxt

numpy.genfromtxt(fname, dtype=<type 'float'>, comments='#', delimiter=None, skiprows=0, skip_header=0, skip_footer=0, converters=None, missing='', missing_values=None, filling_values=None, usecols=None, names=None, excludelist=None, deletechars=None, replace_space='_', autostrip=False, case_sensitive=True, defaultfmt='f%i', unpack=None, usemask=False, loose=True, invalid_raise=True) [source]

Load data from a text file, with missing values handled as specified.

Each line past the first skip_header lines is split at the delimiter character, and characters following the comments character are discarded.

Parameters:

fname : file or str

File, filename, or generator to read. If the filename extension is gz or bz2, the file is first decompressed. Note that generators must return byte strings in Python 3k.

dtype : dtype, optional

Data type of the resulting array. If None, the dtypes will be determined by the contents of each column, individually.

comments : str, optional

The character used to indicate the start of a comment. All the characters occurring on a line after a comment are discarded

delimiter : str, int, or sequence, optional

The string used to separate values. By default, any consecutive whitespaces act as delimiter. An integer or sequence of integers can also be provided as width(s) of each field.

skip_rows : int, optional

skip_rows was deprecated in numpy 1.5, and will be removed in numpy 2.0. Please use skip_header instead.

skip_header : int, optional

The number of lines to skip at the beginning of the file.

skip_footer : int, optional

The number of lines to skip at the end of the file.

converters : variable, optional

The set of functions that convert the data of a column to a value. The converters can also be used to provide a default value for missing data: converters = {3: lambda s: float(s or 0)}.

missing : variable, optional

missing was deprecated in numpy 1.5, and will be removed in numpy 2.0. Please use missing_values instead.

missing_values : variable, optional

The set of strings corresponding to missing data.

filling_values : variable, optional

The set of values to be used as default when the data are missing.

usecols : sequence, optional

Which columns to read, with 0 being the first. For example, usecols = (1, 4, 5) will extract the 2nd, 5th and 6th columns.

names : {None, True, str, sequence}, optional

If names is True, the field names are read from the first valid line after the first skip_header lines. If names is a sequence or a single-string of comma-separated names, the names will be used to define the field names in a structured dtype. If names is None, the names of the dtype fields will be used, if any.

excludelist : sequence, optional

A list of names to exclude. This list is appended to the default list [‘return’,’file’,’print’]. Excluded names are appended an underscore: for example, file would become file_.

deletechars : str, optional

A string combining invalid characters that must be deleted from the names.

defaultfmt : str, optional

A format used to define default field names, such as “f%i” or “f_%02i”.

autostrip : bool, optional

Whether to automatically strip white spaces from the variables.

replace_space : char, optional

Character(s) used in replacement of white spaces in the variables names. By default, use a ‘_’.

case_sensitive : {True, False, ‘upper’, ‘lower’}, optional

If True, field names are case sensitive. If False or ‘upper’, field names are converted to upper case. If ‘lower’, field names are converted to lower case.

unpack : bool, optional

If True, the returned array is transposed, so that arguments may be unpacked using x, y, z = loadtxt(...)

usemask : bool, optional

If True, return a masked array. If False, return a regular array.

loose : bool, optional

If True, do not raise errors for invalid values.

invalid_raise : bool, optional

If True, an exception is raised if an inconsistency is detected in the number of columns. If False, a warning is emitted and the offending lines are skipped.
Returns:

out : ndarray

Data read from the text file. If usemask is True, this is a masked array.

See also

numpy.loadtxt
equivalent function when no data is missing.

Notes

  • When spaces are used as delimiters, or when no delimiter has been given as input, there should not be any missing data between two fields.
  • When the variables are named (either by a flexible dtype or with names, there must not be any header in the file (else a ValueError exception is raised).
  • Individual values are not stripped of spaces by default. When using a custom converter, make sure the function does remove spaces.

References

[R20] Numpy User Guide, section I/O with Numpy.

Examples

>>> from StringIO import StringIO
>>> import numpy as np

Comma delimited file with mixed dtype

>>> s = StringIO("1,1.3,abcde")
>>> data = np.genfromtxt(s, dtype=[('myint','i8'),('myfloat','f8'),
... ('mystring','S5')], delimiter=",")
>>> data
array((1, 1.3, 'abcde'),
      dtype=[('myint', '<i8'), ('myfloat', '<f8'), ('mystring', '|S5')])

Using dtype = None

>>> s.seek(0) # needed for StringIO example only
>>> data = np.genfromtxt(s, dtype=None,
... names = ['myint','myfloat','mystring'], delimiter=",")
>>> data
array((1, 1.3, 'abcde'),
      dtype=[('myint', '<i8'), ('myfloat', '<f8'), ('mystring', '|S5')])

Specifying dtype and names

>>> s.seek(0)
>>> data = np.genfromtxt(s, dtype="i8,f8,S5",
... names=['myint','myfloat','mystring'], delimiter=",")
>>> data
array((1, 1.3, 'abcde'),
      dtype=[('myint', '<i8'), ('myfloat', '<f8'), ('mystring', '|S5')])

An example with fixed-width columns

>>> s = StringIO("11.3abcde")
>>> data = np.genfromtxt(s, dtype=None, names=['intvar','fltvar','strvar'],
...     delimiter=[1,3,5])
>>> data
array((1, 1.3, 'abcde'),
      dtype=[('intvar', '<i8'), ('fltvar', '<f8'), ('strvar', '|S5')])


numpy.fromregex

  • Input and output
  • next
  • previous

Previous topic

numpy.genfromtxt

Next topic

numpy.fromstring

numpy.fromregex

numpy.fromregex(file, regexp, dtype) [source]

Construct an array from a text file, using regular expression parsing.

The returned array is always a structured array, and is constructed from all matches of the regular expression in the file. Groups in the regular expression are converted to fields of the structured array.

Parameters:

file : str or file

File name or file object to read.

regexp : str or regexp

Regular expression used to parse the file. Groups in the regular expression correspond to fields in the dtype.

dtype : dtype or list of dtypes

Dtype for the structured array.
Returns:

output : ndarray

The output array, containing the part of the content of file that was matched by regexp. output is always a structured array.
Raises:

TypeError

When dtype is not a valid dtype for a structured array.

See also

fromstring, loadtxt

Notes

Dtypes for structured arrays can be specified in several forms, but all forms specify at least the data type and field name. For details see doc.structured_arrays.

Examples

>>> f = open('test.dat', 'w')
>>> f.write("1312 foo\n1534  bar\n444   qux")
>>> f.close()

>>> regexp = r"(\d+)\s+(...)"  # match [digits, whitespace, anything]
>>> output = np.fromregex('test.dat', regexp,
...                       [('num', np.int64), ('key', 'S3')])
>>> output
array([(1312L, 'foo'), (1534L, 'bar'), (444L, 'qux')],
      dtype=[('num', '<i8'), ('key', '|S3')])
>>> output['num']
array([1312, 1534,  444], dtype=int64)


numpy.array_repr

  • Input and output
  • next
  • previous

Previous topic

numpy.ndarray.tolist

Next topic

numpy.array_str

numpy.array_repr

numpy.array_repr(arr, max_line_width=None, precision=None, suppress_small=None) [source]

Return the string representation of an array.

Parameters:

arr : ndarray

Input array.

max_line_width : int, optional

The maximum number of columns the string should span. Newline characters split the string appropriately after array elements.

precision : int, optional

Floating point precision. Default is the current printing precision (usually 8), which can be altered using set_printoptions.

suppress_small : bool, optional

Represent very small numbers as zero, default is False. Very small is defined by precision, if the precision is 8 then numbers smaller than 5e-9 are represented as zero.
Returns:

string : str

The string representation of an array.

See also

array_str, array2string, set_printoptions

Examples

>>> np.array_repr(np.array([1,2]))
'array([1, 2])'
>>> np.array_repr(np.ma.array([0.]))
'MaskedArray([ 0.])'
>>> np.array_repr(np.array([], np.int32))
'array([], dtype=int32)'

>>> x = np.array([1e-6, 4e-7, 2, 3])
>>> np.array_repr(x, precision=6, suppress_small=True)
'array([ 0.000001,  0.      ,  2.      ,  3.      ])'


numpy.array_str

  • Input and output
  • next
  • previous

Previous topic

numpy.array_repr

Next topic

numpy.memmap

numpy.array_str

numpy.array_str(a, max_line_width=None, precision=None, suppress_small=None) [source]

Return a string representation of the data in an array.

The data in the array is returned as a single string. This function is similar to array_repr, the difference being that array_repr also returns information on the kind of array and its data type.

Parameters:

a : ndarray

Input array.

max_line_width : int, optional

Inserts newlines if text is longer than max_line_width. The default is, indirectly, 75.

precision : int, optional

Floating point precision. Default is the current printing precision (usually 8), which can be altered using set_printoptions.

suppress_small : bool, optional

Represent numbers “very close” to zero as zero; default is False. Very close is defined by precision: if the precision is 8, e.g., numbers smaller (in absolute value) than 5e-9 are represented as zero.

See also

array2string, array_repr, set_printoptions

Examples

>>> np.array_str(np.arange(3))
'[0 1 2]'


numpy.set_printoptions

  • Input and output
  • next
  • previous

Previous topic

numpy.memmap.flush

Next topic

numpy.get_printoptions

numpy.set_printoptions

numpy.set_printoptions(precision=None, threshold=None, edgeitems=None, linewidth=None, suppress=None, nanstr=None, infstr=None, formatter=None) [source]

Set printing options.

These options determine the way floating point numbers, arrays and other NumPy objects are displayed.

Parameters:

precision : int, optional

Number of digits of precision for floating point output (default 8).

threshold : int, optional

Total number of array elements which trigger summarization rather than full repr (default 1000).

edgeitems : int, optional

Number of array items in summary at beginning and end of each dimension (default 3).

linewidth : int, optional

The number of characters per line for the purpose of inserting line breaks (default 75).

suppress : bool, optional

Whether or not suppress printing of small floating point values using scientific notation (default False).

nanstr : str, optional

String representation of floating point not-a-number (default nan).

infstr : str, optional

String representation of floating point infinity (default inf).

formatter : dict of callables, optional

If not None, the keys should indicate the type(s) that the respective formatting function applies to. Callables should return a string. Types that are not specified (by their corresponding keys) are handled by the default formatters. Individual types for which a formatter can be set are:

- 'bool'
- 'int'
- 'timedelta' : a `numpy.timedelta64`
- 'datetime' : a `numpy.datetime64`
- 'float'
- 'longfloat' : 128-bit floats
- 'complexfloat'
- 'longcomplexfloat' : composed of two 128-bit floats
- 'numpy_str' : types `numpy.string_` and `numpy.unicode_`
- 'str' : all other strings

Other keys that can be used to set a group of types at once are:

- 'all' : sets all types
- 'int_kind' : sets 'int'
- 'float_kind' : sets 'float' and 'longfloat'
- 'complex_kind' : sets 'complexfloat' and 'longcomplexfloat'
- 'str_kind' : sets 'str' and 'numpystr'

See also

get_printoptions, set_string_function, array2string

Notes

formatter is always reset with a call to set_printoptions.

Examples

Floating point precision can be set:

>>> np.set_printoptions(precision=4)
>>> print np.array([1.123456789])
[ 1.1235]

Long arrays can be summarised:

>>> np.set_printoptions(threshold=5)
>>> print np.arange(10)
[0 1 2 ..., 7 8 9]

Small results can be suppressed:

>>> eps = np.finfo(float).eps
>>> x = np.arange(4.)
>>> x**2 - (x + eps)**2
array([ -4.9304e-32,  -4.4409e-16,   0.0000e+00,   0.0000e+00])
>>> np.set_printoptions(suppress=True)
>>> x**2 - (x + eps)**2
array([-0., -0.,  0.,  0.])

A custom formatter can be used to display array elements as desired:

>>> np.set_printoptions(formatter={'all':lambda x: 'int: '+str(-x)})
>>> x = np.arange(3)
>>> x
array([int: 0, int: -1, int: -2])
>>> np.set_printoptions()  # formatter gets reset
>>> x
array([0, 1, 2])

To put back the default options, you can use:

>>> np.set_printoptions(edgeitems=3,infstr='inf',
... linewidth=75, nanstr='nan', precision=8,
... suppress=False, threshold=1000, formatter=None)


numpy.get_printoptions

  • Input and output
  • next
  • previous

Previous topic

numpy.set_printoptions

Next topic

numpy.set_string_function

numpy.get_printoptions

numpy.get_printoptions() [source]

Return the current print options.

Returns:

print_opts : dict

Dictionary of current print options with keys

  • precision : int
  • threshold : int
  • edgeitems : int
  • linewidth : int
  • suppress : bool
  • nanstr : str
  • infstr : str
  • formatter : dict of callables

For a full description of these options, see set_printoptions.

See also

set_printoptions, set_string_function


numpy.set_string_function

  • Input and output
  • next
  • previous

Previous topic

numpy.get_printoptions

Next topic

numpy.binary_repr

numpy.set_string_function

numpy.set_string_function(f, repr=True) [source]

Set a Python function to be used when pretty printing arrays.

Parameters:

f : function or None

Function to be used to pretty print arrays. The function should expect a single array argument and return a string of the representation of the array. If None, the function is reset to the default NumPy function to print arrays.

repr : bool, optional

If True (default), the function for pretty printing (__repr__) is set, if False the function that returns the default string representation (__str__) is set.

See also

set_printoptions, get_printoptions

Examples

>>> def pprint(arr):
...     return 'HA! - What are you going to do now?'
...
>>> np.set_string_function(pprint)
>>> a = np.arange(10)
>>> a
HA! - What are you going to do now?
>>> print a
[0 1 2 3 4 5 6 7 8 9]

We can reset the function to the default:

>>> np.set_string_function(None)
>>> a
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

repr affects either pretty printing or normal string representation. Note that __repr__ is still affected by setting __str__ because the width of each array element in the returned string becomes equal to the length of the result of __str__().

>>> x = np.arange(4)
>>> np.set_string_function(lambda x:'random', repr=False)
>>> x.__str__()
'random'
>>> x.__repr__()
'array([     0,      1,      2,      3])'


numpy.base_repr

  • Input and output
  • next
  • previous

Previous topic

numpy.binary_repr

Next topic

numpy.DataSource

numpy.base_repr

numpy.base_repr(number, base=2, padding=0) [source]

Return a string representation of a number in the given base system.

Parameters:

number : int

The value to convert. Only positive values are handled.

base : int, optional

Convert number to the base number system. The valid range is 2-36, the default value is 2.

padding : int, optional

Number of zeros padded on the left. Default is 0 (no padding).
Returns:

out : str

String representation of number in base system.

See also

binary_repr
Faster version of base_repr for base 2.

Examples

>>> np.base_repr(5)
'101'
>>> np.base_repr(6, 5)
'11'
>>> np.base_repr(7, base=5, padding=3)
'00012'

>>> np.base_repr(10, base=16)
'A'
>>> np.base_repr(32, base=16)
'20'


numpy.DataSource

  • Input and output
  • next
  • previous

Previous topic

numpy.base_repr

Next topic

numpy.DataSource.abspath

numpy.DataSource

class numpy.DataSource(destpath='.') [source]

A generic data source file (file, http, ftp, ...).

DataSources can be local files or remote files/URLs. The files may also be compressed or uncompressed. DataSource hides some of the low-level details of downloading the file, allowing you to simply pass in a valid file path (or URL) and obtain a file object.

Parameters:

destpath : str or None, optional

Path to the directory where the source file gets downloaded to for use. If destpath is None, a temporary directory will be created. The default path is the current directory.

Notes

URLs require a scheme string (http://) to be used, without it they will fail:

>>> repos = DataSource()
>>> repos.exists('www.google.com/index.html')
False
>>> repos.exists('http://www.google.com/index.html')
True

Temporary directories are deleted when the DataSource is deleted.

Examples

>>> ds = DataSource('/home/guido')
>>> urlname = 'http://www.google.com/index.html'
>>> gfile = ds.open('http://www.google.com/index.html')  # remote file
>>> ds.abspath(urlname)
'/home/guido/www.google.com/site/index.html'

>>> ds = DataSource(None)  # use with temporary file
>>> ds.open('/home/guido/foobar.txt')
<open file '/home/guido.foobar.txt', mode 'r' at 0x91d4430>
>>> ds.abspath('/home/guido/foobar.txt')
'/tmp/tmpy4pgsP/home/guido/foobar.txt'

Methods

abspath(path) | Return absolute path of file in the DataSource directory.
exists(path) | Test if path exists.
open(path[, mode]) | Open and return file-like object.


numpy.DataSource.abspath

  • Input and output
  • numpy.DataSource
  • index
  • next
  • previous

Previous topic

numpy.DataSource

Next topic

numpy.DataSource.exists

numpy.DataSource.abspath

DataSource.abspath(path) [source]

Return absolute path of file in the DataSource directory.

If path is an URL, then abspath will return either the location the file exists locally or the location it would exist when opened using the open method.

Parameters:

path : str

Can be a local file or a remote URL.
Returns:

out : str

Complete path, including the DataSource destination directory.

Notes

The functionality is based on os.path.abspath.


numpy.DataSource.exists

  • Input and output
  • numpy.DataSource
  • index
  • next
  • previous

Previous topic

numpy.DataSource.abspath

Next topic

numpy.DataSource.open

numpy.DataSource.exists

DataSource.exists(path) [source]

Test if path exists.

Test if path exists as (and in this order):

  • a local file.
  • a remote URL that has been downloaded and stored locally in the DataSource directory.
  • a remote URL that has not been downloaded, but is valid and accessible.
Parameters:

path : str

Can be a local file or a remote URL.
Returns:

out : bool

True if path exists.

Notes

When path is an URL, exists will return True if it’s either stored locally in the DataSource directory, or is a valid remote URL. DataSource does not discriminate between the two, the file is accessible if it exists in either location.


numpy.DataSource.open

  • Input and output
  • numpy.DataSource
  • index
  • next
  • previous

Previous topic

numpy.DataSource.exists

Next topic

Linear algebra (numpy.linalg)

numpy.DataSource.open

DataSource.open(path, mode='r') [source]

Open and return file-like object.

If path is an URL, it will be downloaded, stored in the DataSource directory and opened from there.

Parameters:

path : str

Local file path or URL to open.

mode : {‘r’, ‘w’, ‘a’}, optional

Mode to open path. Mode ‘r’ for reading, ‘w’ for writing, ‘a’ to append. Available modes depend on the type of object specified by path. Default is ‘r’.
Returns:

out : file object

File object.


Linear algebra (numpy.linalg)

  • next
  • previous

Table Of Contents

  • Linear algebra (numpy.linalg)
    • Matrix and vector products
    • Decompositions
    • Matrix eigenvalues
    • Norms and other numbers
    • Solving equations and inverting matrices
    • Exceptions
    • Linear algebra on several matrices at once

Previous topic

numpy.DataSource.open

Next topic

numpy.dot

Linear algebra (numpy.linalg)

Matrix and vector products

dot(a, b[, out]) | Dot product of two arrays.
vdot(a, b) | Return the dot product of two vectors.
inner(a, b) | Inner product of two arrays.
outer(a, b[, out]) | Compute the outer product of two vectors.
tensordot(a, b[, axes]) | Compute tensor dot product along specified axes for arrays >= 1-D.
einsum(subscripts, *operands[, out, dtype, ...]) | Evaluates the Einstein summation convention on the operands.
linalg.matrix_power(M, n) | Raise a square matrix to the (integer) power n.
kron(a, b) | Kronecker product of two arrays.

Decompositions

linalg.cholesky(a) | Cholesky decomposition.
linalg.qr(a[, mode]) | Compute the qr factorization of a matrix.
linalg.svd(a[, full_matrices, compute_uv]) | Singular Value Decomposition.

Matrix eigenvalues

linalg.eig(a) | Compute the eigenvalues and right eigenvectors of a square array.
linalg.eigh(a[, UPLO]) | Return the eigenvalues and eigenvectors of a Hermitian or symmetric matrix.
linalg.eigvals(a) | Compute the eigenvalues of a general matrix.
linalg.eigvalsh(a[, UPLO]) | Compute the eigenvalues of a Hermitian or real symmetric matrix.

Norms and other numbers

linalg.norm(x[, ord, axis]) | Matrix or vector norm.
linalg.cond(x[, p]) | Compute the condition number of a matrix.
linalg.det(a) | Compute the determinant of an array.
linalg.matrix_rank(M[, tol]) | Return matrix rank of array using SVD method
linalg.slogdet(a) | Compute the sign and (natural) logarithm of the determinant of an array.
trace(a[, offset, axis1, axis2, dtype, out]) | Return the sum along diagonals of the array.

Solving equations and inverting matrices

linalg.solve(a, b) | Solve a linear matrix equation, or system of linear scalar equations.
linalg.tensorsolve(a, b[, axes]) | Solve the tensor equation a x = b for x.
linalg.lstsq(a, b[, rcond]) | Return the least-squares solution to a linear matrix equation.
linalg.inv(a) | Compute the (multiplicative) inverse of a matrix.
linalg.pinv(a[, rcond]) | Compute the (Moore-Penrose) pseudo-inverse of a matrix.
linalg.tensorinv(a[, ind]) | Compute the ‘inverse’ of an N-dimensional array.

Exceptions

linalg.LinAlgError Generic Python-exception-derived object raised by linalg functions.

Linear algebra on several matrices at once

Several of the linear algebra routines listed above are able to compute results for several matrices at once, if they are stacked into the same array.

This is indicated in the documentation via input parameter specifications such as a : (..., M, M) array_like. This means that if for instance given an input array a.shape == (N, M, M), it is interpreted as a “stack” of N matrices, each of size M-by-M. Similar specification applies to return values, for instance the determinant has det : (...) and will in this case return an array of shape det(a).shape == (N,). This generalizes to linear algebra operations on higher-dimensional arrays: the last 1 or 2 dimensions of a multidimensional array are interpreted as vectors or matrices, as appropriate for each operation.


numpy.dot

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.LinAlgError

Next topic

numpy.vdot

numpy.dot

numpy.dot(a, b, out=None)

Dot product of two arrays.

For 2-D arrays it is equivalent to matrix multiplication, and for 1-D arrays to inner product of vectors (without complex conjugation). For N dimensions it is a sum product over the last axis of a and the second-to-last of b:

dot(a, b)[i,j,k,m] = sum(a[i,j,:] * b[k,:,m])
Parameters:

a : array_like

First argument.

b : array_like

Second argument.

out : ndarray, optional

Output argument. This must have the exact kind that would be returned if it was not used. In particular, it must have the right type, must be C-contiguous, and its dtype must be the dtype that would be returned for dot(a,b). This is a performance feature. Therefore, if these conditions are not met, an exception is raised, instead of attempting to be flexible.
Returns:

output : ndarray

Returns the dot product of a and b. If a and b are both scalars or both 1-D arrays then a scalar is returned; otherwise an array is returned. If out is given, then it is returned.
Raises:

ValueError

If the last dimension of a is not the same size as the second-to-last dimension of b.

See also

vdot
Complex-conjugating dot product.
tensordot
Sum products over arbitrary axes.
einsum
Einstein summation convention.

Examples

>>> np.dot(3, 4)
12

Neither argument is complex-conjugated:

>>> np.dot([2j, 3j], [2j, 3j])
(-13+0j)

For 2-D arrays it’s the matrix product:

>>> a = [[1, 0], [0, 1]]
>>> b = [[4, 1], [2, 2]]
>>> np.dot(a, b)
array([[4, 1],
       [2, 2]])

>>> a = np.arange(3*4*5*6).reshape((3,4,5,6))
>>> b = np.arange(3*4*5*6)[::-1].reshape((5,4,6,3))
>>> np.dot(a, b)[2,3,2,1,2,2]
499128
>>> sum(a[2,3,2,:] * b[1,2,:,2])
499128


numpy.vdot

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.dot

Next topic

numpy.inner

numpy.vdot

numpy.vdot(a, b)

Return the dot product of two vectors.

The vdot(a, b) function handles complex numbers differently than dot(a, b). If the first argument is complex the complex conjugate of the first argument is used for the calculation of the dot product.

Note that vdot handles multidimensional arrays differently than dot: it does not perform a matrix product, but flattens input arguments to 1-D vectors first. Consequently, it should only be used for vectors.

Parameters:

a : array_like

If a is complex the complex conjugate is taken before calculation of the dot product.

b : array_like

Second argument to the dot product.
Returns:

output : ndarray

Dot product of a and b. Can be an int, float, or complex depending on the types of a and b.

See also

dot
Return the dot product without using the complex conjugate of the first argument.

Examples

>>> a = np.array([1+2j,3+4j])
>>> b = np.array([5+6j,7+8j])
>>> np.vdot(a, b)
(70-8j)
>>> np.vdot(b, a)
(70+8j)

Note that higher-dimensional arrays are flattened!

>>> a = np.array([[1, 4], [5, 6]])
>>> b = np.array([[4, 1], [2, 2]])
>>> np.vdot(a, b)
30
>>> np.vdot(b, a)
30
>>> 1*4 + 4*1 + 5*2 + 6*2
30


numpy.inner

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.vdot

Next topic

numpy.outer

numpy.inner

numpy.inner(a, b)

Inner product of two arrays.

Ordinary inner product of vectors for 1-D arrays (without complex conjugation), in higher dimensions a sum product over the last axes.

Parameters:

a, b : array_like

If a and b are nonscalar, their last dimensions of must match.
Returns:

out : ndarray

out.shape = a.shape[:-1] + b.shape[:-1]
Raises:

ValueError

If the last dimension of a and b has different size.

See also

tensordot
Sum products over arbitrary axes.
dot
Generalised matrix product, using second last dimension of b.
einsum
Einstein summation convention.

Notes

For vectors (1-D arrays) it computes the ordinary inner-product:

np.inner(a, b) = sum(a[:]*b[:])

More generally, if ndim(a) = r > 0 and ndim(b) = s > 0:

np.inner(a, b) = np.tensordot(a, b, axes=(-1,-1))

or explicitly:

np.inner(a, b)[i0,...,ir-1,j0,...,js-1]
     = sum(a[i0,...,ir-1,:]*b[j0,...,js-1,:])

In addition a or b may be scalars, in which case:

np.inner(a,b) = a*b

Examples

Ordinary inner product for vectors:

>>> a = np.array([1,2,3])
>>> b = np.array([0,1,0])
>>> np.inner(a, b)
2

A multidimensional example:

>>> a = np.arange(24).reshape((2,3,4))
>>> b = np.arange(4)
>>> np.inner(a, b)
array([[ 14,  38,  62],
       [ 86, 110, 134]])

An example where b is a scalar:

>>> np.inner(np.eye(2), 7)
array([[ 7.,  0.],
       [ 0.,  7.]])


numpy.outer

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.inner

Next topic

numpy.tensordot

numpy.outer

numpy.outer(a, b, out=None) [source]

Compute the outer product of two vectors.

Given two vectors, a = [a0, a1, ..., aM] and b = [b0, b1, ..., bN], the outer product [R55] is:

[[a0*b0  a0*b1 ... a0*bN ]
 [a1*b0    .
 [ ...          .
 [aM*b0            aM*bN ]]
Parameters:

a : (M,) array_like

First input vector. Input is flattened if not already 1-dimensional.

b : (N,) array_like

Second input vector. Input is flattened if not already 1-dimensional.

out : (M, N) ndarray, optional

A location where the result is stored

New in version 1.9.0.
Returns:

out : (M, N) ndarray

out[i, j] = a[i] * b[j]

See also

inner, einsum

References

[R55] (1, 2) : G. H. Golub and C. F. van Loan, Matrix Computations, 3rd ed., Baltimore, MD, Johns Hopkins University Press, 1996, pg. 8.

Examples

Make a (very coarse) grid for computing a Mandelbrot set:

>>> rl = np.outer(np.ones((5,)), np.linspace(-2, 2, 5))
>>> rl
array([[-2., -1.,  0.,  1.,  2.],
       [-2., -1.,  0.,  1.,  2.],
       [-2., -1.,  0.,  1.,  2.],
       [-2., -1.,  0.,  1.,  2.],
       [-2., -1.,  0.,  1.,  2.]])
>>> im = np.outer(1j*np.linspace(2, -2, 5), np.ones((5,)))
>>> im
array([[ 0.+2.j,  0.+2.j,  0.+2.j,  0.+2.j,  0.+2.j],
       [ 0.+1.j,  0.+1.j,  0.+1.j,  0.+1.j,  0.+1.j],
       [ 0.+0.j,  0.+0.j,  0.+0.j,  0.+0.j,  0.+0.j],
       [ 0.-1.j,  0.-1.j,  0.-1.j,  0.-1.j,  0.-1.j],
       [ 0.-2.j,  0.-2.j,  0.-2.j,  0.-2.j,  0.-2.j]])
>>> grid = rl + im
>>> grid
array([[-2.+2.j, -1.+2.j,  0.+2.j,  1.+2.j,  2.+2.j],
       [-2.+1.j, -1.+1.j,  0.+1.j,  1.+1.j,  2.+1.j],
       [-2.+0.j, -1.+0.j,  0.+0.j,  1.+0.j,  2.+0.j],
       [-2.-1.j, -1.-1.j,  0.-1.j,  1.-1.j,  2.-1.j],
       [-2.-2.j, -1.-2.j,  0.-2.j,  1.-2.j,  2.-2.j]])

An example using a “vector” of letters:

>>> x = np.array(['a', 'b', 'c'], dtype=object)
>>> np.outer(x, [1, 2, 3])
array([[a, aa, aaa],
       [b, bb, bbb],
       [c, cc, ccc]], dtype=object)


numpy.tensordot

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.outer

Next topic

numpy.einsum

numpy.tensordot

numpy.tensordot(a, b, axes=2) [source]

Compute tensor dot product along specified axes for arrays >= 1-D.

Given two tensors (arrays of dimension greater than or equal to one), a and b, and an array_like object containing two array_like objects, (a_axes, b_axes), sum the products of a‘s and b‘s elements (components) over the axes specified by a_axes and b_axes. The third argument can be a single non-negative integer_like scalar, N; if it is such, then the last N dimensions of a and the first N dimensions of b are summed over.

Parameters:

a, b : array_like, len(shape) >= 1

Tensors to “dot”.

axes : variable type

  • integer_like scalar Number of axes to sum over (applies to both arrays); or
  • (2,) array_like, both elements array_like of the same length List of axes to be summed over, first sequence applying to a, second to b.

See also

dot, einsum

Notes

When there is more than one axis to sum over - and they are not the last (first) axes of a (b) - the argument axes should consist of two sequences of the same length, with the first axis to sum over given first in both sequences, the second axis second, and so forth.

Examples

A “traditional” example:

>>> a = np.arange(60.).reshape(3,4,5)
>>> b = np.arange(24.).reshape(4,3,2)
>>> c = np.tensordot(a,b, axes=([1,0],[0,1]))
>>> c.shape
(5, 2)
>>> c
array([[ 4400.,  4730.],
       [ 4532.,  4874.],
       [ 4664.,  5018.],
       [ 4796.,  5162.],
       [ 4928.,  5306.]])
>>> # A slower but equivalent way of computing the same...
>>> d = np.zeros((5,2))
>>> for i in range(5):
...   for j in range(2):
...     for k in range(3):
...       for n in range(4):
...         d[i,j] += a[k,n,i] * b[n,k,j]
>>> c == d
array([[ True,  True],
       [ True,  True],
       [ True,  True],
       [ True,  True],
       [ True,  True]], dtype=bool)

An extended example taking advantage of the overloading of + and *:

>>> a = np.array(range(1, 9))
>>> a.shape = (2, 2, 2)
>>> A = np.array(('a', 'b', 'c', 'd'), dtype=object)
>>> A.shape = (2, 2)
>>> a; A
array([[[1, 2],
        [3, 4]],
       [[5, 6],
        [7, 8]]])
array([[a, b],
       [c, d]], dtype=object)

>>> np.tensordot(a, A) # third argument default is 2
array([abbcccdddd, aaaaabbbbbbcccccccdddddddd], dtype=object)

>>> np.tensordot(a, A, 1)
array([[[acc, bdd],
        [aaacccc, bbbdddd]],
       [[aaaaacccccc, bbbbbdddddd],
        [aaaaaaacccccccc, bbbbbbbdddddddd]]], dtype=object)

>>> np.tensordot(a, A, 0) # "Left for reader" (result too long to incl.)
array([[[[[a, b],
          [c, d]],
          ...

>>> np.tensordot(a, A, (0, 1))
array([[[abbbbb, cddddd],
        [aabbbbbb, ccdddddd]],
       [[aaabbbbbbb, cccddddddd],
        [aaaabbbbbbbb, ccccdddddddd]]], dtype=object)

>>> np.tensordot(a, A, (2, 1))
array([[[abb, cdd],
        [aaabbbb, cccdddd]],
       [[aaaaabbbbbb, cccccdddddd],
        [aaaaaaabbbbbbbb, cccccccdddddddd]]], dtype=object)

>>> np.tensordot(a, A, ((0, 1), (0, 1)))
array([abbbcccccddddddd, aabbbbccccccdddddddd], dtype=object)

>>> np.tensordot(a, A, ((2, 1), (1, 0)))
array([acccbbdddd, aaaaacccccccbbbbbbdddddddd], dtype=object)


numpy.einsum

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.tensordot

Next topic

numpy.linalg.matrix_power

numpy.einsum

numpy.einsum(subscripts, *operands, out=None, dtype=None, order='K', casting='safe')

Evaluates the Einstein summation convention on the operands.

Using the Einstein summation convention, many common multi-dimensional array operations can be represented in a simple fashion. This function provides a way compute such summations. The best way to understand this function is to try the examples below, which show how many common NumPy functions can be implemented as calls to einsum.

Parameters:

subscripts : str

Specifies the subscripts for summation.

operands : list of array_like

These are the arrays for the operation.

out : ndarray, optional

If provided, the calculation is done into this array.

dtype : data-type, optional

If provided, forces the calculation to use the data type specified. Note that you may have to also give a more liberal casting parameter to allow the conversions.

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout of the output. ‘C’ means it should be C contiguous. ‘F’ means it should be Fortran contiguous, ‘A’ means it should be ‘F’ if the inputs are all ‘F’, ‘C’ otherwise. ‘K’ means it should be as close to the layout as the inputs as is possible, including arbitrarily permuted axes. Default is ‘K’.

casting : {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

Controls what kind of data casting may occur. Setting this to ‘unsafe’ is not recommended, as it can adversely affect accumulations.

  • ‘no’ means the data types should not be cast at all.
  • ‘equiv’ means only byte-order changes are allowed.
  • ‘safe’ means only casts which can preserve values are allowed.
  • ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.
  • ‘unsafe’ means any data conversions may be done.
Returns:

output : ndarray

The calculation based on the Einstein summation convention.

See also

dot, inner, outer, tensordot

Notes

New in version 1.6.0.

The subscripts string is a comma-separated list of subscript labels, where each label refers to a dimension of the corresponding operand. Repeated subscripts labels in one operand take the diagonal. For example, np.einsum('ii', a) is equivalent to np.trace(a).

Whenever a label is repeated, it is summed, so np.einsum('i,i', a, b) is equivalent to np.inner(a,b). If a label appears only once, it is not summed, so np.einsum('i', a) produces a view of a with no changes.

The order of labels in the output is by default alphabetical. This means that np.einsum('ij', a) doesn’t affect a 2D array, while np.einsum('ji', a) takes its transpose.

The output can be controlled by specifying output subscript labels as well. This specifies the label order, and allows summing to be disallowed or forced when desired. The call np.einsum('i->', a) is like np.sum(a, axis=-1), and np.einsum('ii->i', a) is like np.diag(a). The difference is that einsum does not allow broadcasting by default.

To enable and control broadcasting, use an ellipsis. Default NumPy-style broadcasting is done by adding an ellipsis to the left of each term, like np.einsum('...ii->...i', a). To take the trace along the first and last axes, you can do np.einsum('i...i', a), or to do a matrix-matrix product with the left-most indices instead of rightmost, you can do np.einsum('ij...,jk...->ik...', a, b).

When there is only one operand, no axes are summed, and no output parameter is provided, a view into the operand is returned instead of a new array. Thus, taking the diagonal as np.einsum('ii->i', a) produces a view.

An alternative way to provide the subscripts and operands is as einsum(op0, sublist0, op1, sublist1, ..., [sublistout]). The examples below have corresponding einsum calls with the two parameter methods.

Examples

>>> a = np.arange(25).reshape(5,5)
>>> b = np.arange(5)
>>> c = np.arange(6).reshape(2,3)

>>> np.einsum('ii', a)
60
>>> np.einsum(a, [0,0])
60
>>> np.trace(a)
60

>>> np.einsum('ii->i', a)
array([ 0,  6, 12, 18, 24])
>>> np.einsum(a, [0,0], [0])
array([ 0,  6, 12, 18, 24])
>>> np.diag(a)
array([ 0,  6, 12, 18, 24])

>>> np.einsum('ij,j', a, b)
array([ 30,  80, 130, 180, 230])
>>> np.einsum(a, [0,1], b, [1])
array([ 30,  80, 130, 180, 230])
>>> np.dot(a, b)
array([ 30,  80, 130, 180, 230])
>>> np.einsum('...j,j', a, b)
array([ 30,  80, 130, 180, 230])

>>> np.einsum('ji', c)
array([[0, 3],
       [1, 4],
       [2, 5]])
>>> np.einsum(c, [1,0])
array([[0, 3],
       [1, 4],
       [2, 5]])
>>> c.T
array([[0, 3],
       [1, 4],
       [2, 5]])

>>> np.einsum('..., ...', 3, c)
array([[ 0,  3,  6],
       [ 9, 12, 15]])
>>> np.einsum(3, [Ellipsis], c, [Ellipsis])
array([[ 0,  3,  6],
       [ 9, 12, 15]])
>>> np.multiply(3, c)
array([[ 0,  3,  6],
       [ 9, 12, 15]])

>>> np.einsum('i,i', b, b)
30
>>> np.einsum(b, [0], b, [0])
30
>>> np.inner(b,b)
30

>>> np.einsum('i,j', np.arange(2)+1, b)
array([[0, 1, 2, 3, 4],
       [0, 2, 4, 6, 8]])
>>> np.einsum(np.arange(2)+1, [0], b, [1])
array([[0, 1, 2, 3, 4],
       [0, 2, 4, 6, 8]])
>>> np.outer(np.arange(2)+1, b)
array([[0, 1, 2, 3, 4],
       [0, 2, 4, 6, 8]])

>>> np.einsum('i...->...', a)
array([50, 55, 60, 65, 70])
>>> np.einsum(a, [0,Ellipsis], [Ellipsis])
array([50, 55, 60, 65, 70])
>>> np.sum(a, axis=0)
array([50, 55, 60, 65, 70])

>>> a = np.arange(60.).reshape(3,4,5)
>>> b = np.arange(24.).reshape(4,3,2)
>>> np.einsum('ijk,jil->kl', a, b)
array([[ 4400.,  4730.],
       [ 4532.,  4874.],
       [ 4664.,  5018.],
       [ 4796.,  5162.],
       [ 4928.,  5306.]])
>>> np.einsum(a, [0,1,2], b, [1,0,3], [2,3])
array([[ 4400.,  4730.],
       [ 4532.,  4874.],
       [ 4664.,  5018.],
       [ 4796.,  5162.],
       [ 4928.,  5306.]])
>>> np.tensordot(a,b, axes=([1,0],[0,1]))
array([[ 4400.,  4730.],
       [ 4532.,  4874.],
       [ 4664.,  5018.],
       [ 4796.,  5162.],
       [ 4928.,  5306.]])

>>> a = np.arange(6).reshape((3,2))
>>> b = np.arange(12).reshape((4,3))
>>> np.einsum('ki,jk->ij', a, b)
array([[10, 28, 46, 64],
       [13, 40, 67, 94]])
>>> np.einsum('ki,...k->i...', a, b)
array([[10, 28, 46, 64],
       [13, 40, 67, 94]])
>>> np.einsum('k...,jk', a, b)
array([[10, 28, 46, 64],
       [13, 40, 67, 94]])


numpy.linalg.matrix_power

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.einsum

Next topic

numpy.kron

numpy.linalg.matrix_power

numpy.linalg.matrix_power(M, n) [source]

Raise a square matrix to the (integer) power n.

For positive integers n, the power is computed by repeated matrix squarings and matrix multiplications. If n == 0, the identity matrix of the same shape as M is returned. If n < 0, the inverse is computed and then raised to the abs(n).

Parameters:

M : ndarray or matrix object

Matrix to be “powered.” Must be square, i.e. M.shape == (m, m), with m a positive integer.

n : int

The exponent can be any integer or long integer, positive, negative, or zero.
Returns:

M**n : ndarray or matrix object

The return value is the same shape and type as M; if the exponent is positive or zero then the type of the elements is the same as those of M. If the exponent is negative the elements are floating-point.
Raises:

LinAlgError

If the matrix is not numerically invertible.

See also

matrix
Provides an equivalent function as the exponentiation operator (**, not ^).

Examples

>>> from numpy import linalg as LA
>>> i = np.array([[0, 1], [-1, 0]]) # matrix equiv. of the imaginary unit
>>> LA.matrix_power(i, 3) # should = -i
array([[ 0, -1],
       [ 1,  0]])
>>> LA.matrix_power(np.matrix(i), 3) # matrix arg returns matrix
matrix([[ 0, -1],
        [ 1,  0]])
>>> LA.matrix_power(i, 0)
array([[1, 0],
       [0, 1]])
>>> LA.matrix_power(i, -3) # should = 1/(-i) = i, but w/ f.p. elements
array([[ 0.,  1.],
       [-1.,  0.]])

Somewhat more sophisticated example

>>> q = np.zeros((4, 4))
>>> q[0:2, 0:2] = -i
>>> q[2:4, 2:4] = i
>>> q # one of the three quarternion units not equal to 1
array([[ 0., -1.,  0.,  0.],
       [ 1.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  1.],
       [ 0.,  0., -1.,  0.]])
>>> LA.matrix_power(q, 2) # = -np.eye(4)
array([[-1.,  0.,  0.,  0.],
       [ 0., -1.,  0.,  0.],
       [ 0.,  0., -1.,  0.],
       [ 0.,  0.,  0., -1.]])


numpy.kron

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.matrix_power

Next topic

numpy.linalg.cholesky

numpy.kron

numpy.kron(a, b) [source]

Kronecker product of two arrays.

Computes the Kronecker product, a composite array made of blocks of the second array scaled by the first.

Parameters: a, b : array_like
Returns: out : ndarray

See also

outer
The outer product

Notes

The function assumes that the number of dimenensions of a and b are the same, if necessary prepending the smallest with ones. If a.shape = (r0,r1,..,rN) and b.shape = (s0,s1,...,sN), the Kronecker product has shape (r0*s0, r1*s1, ..., rN*SN). The elements are products of elements from a and b, organized explicitly by:

kron(a,b)[k0,k1,...,kN] = a[i0,i1,...,iN] * b[j0,j1,...,jN]

where:

kt = it * st + jt,  t = 0,...,N

In the common 2-D case (N=1), the block structure can be visualized:

[[ a[0,0]*b,   a[0,1]*b,  ... , a[0,-1]*b  ],
 [  ...                              ...   ],
 [ a[-1,0]*b,  a[-1,1]*b, ... , a[-1,-1]*b ]]

Examples

>>> np.kron([1,10,100], [5,6,7])
array([  5,   6,   7,  50,  60,  70, 500, 600, 700])
>>> np.kron([5,6,7], [1,10,100])
array([  5,  50, 500,   6,  60, 600,   7,  70, 700])

>>> np.kron(np.eye(2), np.ones((2,2)))
array([[ 1.,  1.,  0.,  0.],
       [ 1.,  1.,  0.,  0.],
       [ 0.,  0.,  1.,  1.],
       [ 0.,  0.,  1.,  1.]])

>>> a = np.arange(100).reshape((2,5,2,5))
>>> b = np.arange(24).reshape((2,3,4))
>>> c = np.kron(a,b)
>>> c.shape
(2, 10, 6, 20)
>>> I = (1,3,0,2)
>>> J = (0,2,1)
>>> J1 = (0,) + J             # extend to ndim=4
>>> S1 = (1,) + b.shape
>>> K = tuple(np.array(I) * np.array(S1) + np.array(J1))
>>> c[K] == a[I]*b[J]
True


numpy.linalg.cholesky

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.kron

Next topic

numpy.linalg.qr

numpy.linalg.cholesky

numpy.linalg.cholesky(a) [source]

Cholesky decomposition.

Return the Cholesky decomposition, L * L.H, of the square matrix a, where L is lower-triangular and .H is the conjugate transpose operator (which is the ordinary transpose if a is real-valued). a must be Hermitian (symmetric if real-valued) and positive-definite. Only L is actually returned.

Parameters:

a : (..., M, M) array_like

Hermitian (symmetric if all elements are real), positive-definite input matrix.
Returns:

L : (..., M, M) array_like

Upper or lower-triangular Cholesky factor of a. Returns a matrix object if a is a matrix object.
Raises:

LinAlgError

If the decomposition fails, for example, if a is not positive-definite.

Notes

Broadcasting rules apply, see the numpy.linalg documentation for details.

The Cholesky decomposition is often used as a fast way of solving

(when A is both Hermitian/symmetric and positive-definite).

First, we solve for [image] in

and then for [image] in

Examples

>>> A = np.array([[1,-2j],[2j,5]])
>>> A
array([[ 1.+0.j,  0.-2.j],
       [ 0.+2.j,  5.+0.j]])
>>> L = np.linalg.cholesky(A)
>>> L
array([[ 1.+0.j,  0.+0.j],
       [ 0.+2.j,  1.+0.j]])
>>> np.dot(L, L.T.conj()) # verify that L * L.H = A
array([[ 1.+0.j,  0.-2.j],
       [ 0.+2.j,  5.+0.j]])
>>> A = [[1,-2j],[2j,5]] # what happens if A is only array_like?
>>> np.linalg.cholesky(A) # an ndarray object is returned
array([[ 1.+0.j,  0.+0.j],
       [ 0.+2.j,  1.+0.j]])
>>> # But a matrix object is returned if A is a matrix object
>>> LA.cholesky(np.matrix(A))
matrix([[ 1.+0.j,  0.+0.j],
        [ 0.+2.j,  1.+0.j]])


numpy.linalg.qr

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.cholesky

Next topic

numpy.linalg.svd

numpy.linalg.qr

numpy.linalg.qr(a, mode='reduced') [source]

Compute the qr factorization of a matrix.

Factor the matrix a as qr, where q is orthonormal and r is upper-triangular.

Parameters:

a : array_like, shape (M, N)

Matrix to be factored.

mode : {‘reduced’, ‘complete’, ‘r’, ‘raw’, ‘full’, ‘economic’}, optional

If K = min(M, N), then

‘reduced’ : returns q, r with dimensions (M, K), (K, N) (default) ‘complete’ : returns q, r with dimensions (M, M), (M, N) ‘r’ : returns r only with dimensions (K, N) ‘raw’ : returns h, tau with dimensions (N, M), (K,) ‘full’ : alias of ‘reduced’, deprecated ‘economic’ : returns h from ‘raw’, deprecated.

The options ‘reduced’, ‘complete, and ‘raw’ are new in numpy 1.8, see the notes for more information. The default is ‘reduced’ and to maintain backward compatibility with earlier versions of numpy both it and the old default ‘full’ can be omitted. Note that array h returned in ‘raw’ mode is transposed for calling Fortran. The ‘economic’ mode is deprecated. The modes ‘full’ and ‘economic’ may be passed using only the first letter for backwards compatibility, but all others must be spelled out. See the Notes for more explanation.
Returns:

q : ndarray of float or complex, optional

A matrix with orthonormal columns. When mode = ‘complete’ the result is an orthogonal/unitary matrix depending on whether or not a is real/complex. The determinant may be either +/- 1 in that case.

r : ndarray of float or complex, optional

The upper-triangular matrix.

(h, tau) : ndarrays of np.double or np.cdouble, optional

The array h contains the Householder reflectors that generate q along with r. The tau array contains scaling factors for the reflectors. In the deprecated ‘economic’ mode only h is returned.
Raises:

LinAlgError

If factoring fails.

Notes

This is an interface to the LAPACK routines dgeqrf, zgeqrf, dorgqr, and zungqr.

For more information on the qr factorization, see for example: http://en.wikipedia.org/wiki/QR_factorization

Subclasses of ndarray are preserved except for the ‘raw’ mode. So if a is of type matrix, all the return values will be matrices too.

New ‘reduced’, ‘complete’, and ‘raw’ options for mode were added in Numpy 1.8 and the old option ‘full’ was made an alias of ‘reduced’. In addition the options ‘full’ and ‘economic’ were deprecated. Because ‘full’ was the previous default and ‘reduced’ is the new default, backward compatibility can be maintained by letting mode default. The ‘raw’ option was added so that LAPACK routines that can multiply arrays by q using the Householder reflectors can be used. Note that in this case the returned arrays are of type np.double or np.cdouble and the h array is transposed to be FORTRAN compatible. No routines using the ‘raw’ return are currently exposed by numpy, but some are available in lapack_lite and just await the necessary work.

Examples

>>> a = np.random.randn(9, 6)
>>> q, r = np.linalg.qr(a)
>>> np.allclose(a, np.dot(q, r))  # a does equal qr
True
>>> r2 = np.linalg.qr(a, mode='r')
>>> r3 = np.linalg.qr(a, mode='economic')
>>> np.allclose(r, r2)  # mode='r' returns the same r as mode='full'
True
>>> # But only triu parts are guaranteed equal when mode='economic'
>>> np.allclose(r, np.triu(r3[:6,:6], k=0))
True

Example illustrating a common use of qr: solving of least squares problems

What are the least-squares-best m and y0 in y = y0 + mx for the following data: {(0,1), (1,0), (1,2), (2,1)}. (Graph the points and you’ll see that it should be y0 = 0, m = 1.) The answer is provided by solving the over-determined matrix equation Ax = b, where:

A = array([[0, 1], [1, 1], [1, 1], [2, 1]])
x = array([[y0], [m]])
b = array([[1], [0], [2], [1]])

If A = qr such that q is orthonormal (which is always possible via Gram-Schmidt), then x = inv(r) * (q.T) * b. (In numpy practice, however, we simply use lstsq.)

>>> A = np.array([[0, 1], [1, 1], [1, 1], [2, 1]])
>>> A
array([[0, 1],
       [1, 1],
       [1, 1],
       [2, 1]])
>>> b = np.array([1, 0, 2, 1])
>>> q, r = LA.qr(A)
>>> p = np.dot(q.T, b)
>>> np.dot(LA.inv(r), p)
array([  1.1e-16,   1.0e+00])


numpy.linalg.svd

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.qr

Next topic

numpy.linalg.eig

numpy.linalg.svd

numpy.linalg.svd(a, full_matrices=1, compute_uv=1) [source]

Singular Value Decomposition.

Factors the matrix a as u * np.diag(s) * v, where u and v are unitary and s is a 1-d array of a‘s singular values.

Parameters:

a : (..., M, N) array_like

A real or complex matrix of shape (M, N) .

full_matrices : bool, optional

If True (default), u and v have the shapes (M, M) and (N, N), respectively. Otherwise, the shapes are (M, K) and (K, N), respectively, where K = min(M, N).

compute_uv : bool, optional

Whether or not to compute u and v in addition to s. True by default.
Returns:

u : { (..., M, M), (..., M, K) } array

Unitary matrices. The actual shape depends on the value of full_matrices. Only returned when compute_uv is True.

s : (..., K) array

The singular values for every matrix, sorted in descending order.

v : { (..., N, N), (..., K, N) } array

Unitary matrices. The actual shape depends on the value of full_matrices. Only returned when compute_uv is True.
Raises:

LinAlgError

If SVD computation does not converge.

Notes

Broadcasting rules apply, see the numpy.linalg documentation for details.

The decomposition is performed using LAPACK routine _gesdd

The SVD is commonly written as a = U S V.H. The v returned by this function is V.H and u = U.

If U is a unitary matrix, it means that it satisfies U.H = inv(U).

The rows of v are the eigenvectors of a.H a. The columns of u are the eigenvectors of a a.H. For row i in v and column i in u, the corresponding eigenvalue is s[i]**2.

If a is a matrix object (as opposed to an ndarray), then so are all the return values.

Examples

>>> a = np.random.randn(9, 6) + 1j*np.random.randn(9, 6)

Reconstruction based on full SVD:

>>> U, s, V = np.linalg.svd(a, full_matrices=True)
>>> U.shape, V.shape, s.shape
((9, 9), (6, 6), (6,))
>>> S = np.zeros((9, 6), dtype=complex)
>>> S[:6, :6] = np.diag(s)
>>> np.allclose(a, np.dot(U, np.dot(S, V)))
True

Reconstruction based on reduced SVD:

>>> U, s, V = np.linalg.svd(a, full_matrices=False)
>>> U.shape, V.shape, s.shape
((9, 6), (6, 6), (6,))
>>> S = np.diag(s)
>>> np.allclose(a, np.dot(U, np.dot(S, V)))
True


numpy.linalg.eig

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.svd

Next topic

numpy.linalg.eigh

numpy.linalg.eig

numpy.linalg.eig(a) [source]

Compute the eigenvalues and right eigenvectors of a square array.

Parameters:

a : (..., M, M) array

Matrices for which the eigenvalues and right eigenvectors will be computed
Returns:

w : (..., M) array

The eigenvalues, each repeated according to its multiplicity. The eigenvalues are not necessarily ordered. The resulting array will be always be of complex type. When a is real the resulting eigenvalues will be real (0 imaginary part) or occur in conjugate pairs

v : (..., M, M) array

The normalized (unit “length”) eigenvectors, such that the column v[:,i] is the eigenvector corresponding to the eigenvalue w[i].
Raises:

LinAlgError

If the eigenvalue computation does not converge.

See also

eigvalsh
eigenvalues of a symmetric or Hermitian (conjugate symmetric) array.
eigvals
eigenvalues of a non-symmetric array.

Notes

Broadcasting rules apply, see the numpy.linalg documentation for details.

This is implemented using the _geev LAPACK routines which compute the eigenvalues and eigenvectors of general square arrays.

The number w is an eigenvalue of a if there exists a vector v such that dot(a,v) = w * v. Thus, the arrays a, w, and v satisfy the equations dot(a[:,:], v[:,i]) = w[i] * v[:,i] for [image].

The array v of eigenvectors may not be of maximum rank, that is, some of the columns may be linearly dependent, although round-off error may obscure that fact. If the eigenvalues are all different, then theoretically the eigenvectors are linearly independent. Likewise, the (complex-valued) matrix of eigenvectors v is unitary if the matrix a is normal, i.e., if dot(a, a.H) = dot(a.H, a), where a.H denotes the conjugate transpose of a.

Finally, it is emphasized that v consists of the right (as in right-hand side) eigenvectors of a. A vector y satisfying dot(y.T, a) = z * y.T for some number z is called a left eigenvector of a, and, in general, the left and right eigenvectors of a matrix are not necessarily the (perhaps conjugate) transposes of each other.

References

G. Strang, Linear Algebra and Its Applications, 2nd Ed., Orlando, FL, Academic Press, Inc., 1980, Various pp.

Examples

>>> from numpy import linalg as LA

(Almost) trivial example with real e-values and e-vectors.

>>> w, v = LA.eig(np.diag((1, 2, 3)))
>>> w; v
array([ 1.,  2.,  3.])
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])

Real matrix possessing complex e-values and e-vectors; note that the e-values are complex conjugates of each other.

>>> w, v = LA.eig(np.array([[1, -1], [1, 1]]))
>>> w; v
array([ 1. + 1.j,  1. - 1.j])
array([[ 0.70710678+0.j        ,  0.70710678+0.j        ],
       [ 0.00000000-0.70710678j,  0.00000000+0.70710678j]])

Complex-valued matrix with real e-values (but complex-valued e-vectors); note that a.conj().T = a, i.e., a is Hermitian.

>>> a = np.array([[1, 1j], [-1j, 1]])
>>> w, v = LA.eig(a)
>>> w; v
array([  2.00000000e+00+0.j,   5.98651912e-36+0.j]) # i.e., {2, 0}
array([[ 0.00000000+0.70710678j,  0.70710678+0.j        ],
       [ 0.70710678+0.j        ,  0.00000000+0.70710678j]])

Be careful about round-off error!

>>> a = np.array([[1 + 1e-9, 0], [0, 1 - 1e-9]])
>>> # Theor. e-values are 1 +/- 1e-9
>>> w, v = LA.eig(a)
>>> w; v
array([ 1.,  1.])
array([[ 1.,  0.],
       [ 0.,  1.]])


numpy.linalg.eigh

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.eig

Next topic

numpy.linalg.eigvals

numpy.linalg.eigh

numpy.linalg.eigh(a, UPLO='L') [source]

Return the eigenvalues and eigenvectors of a Hermitian or symmetric matrix.

Returns two objects, a 1-D array containing the eigenvalues of a, and a 2-D square array or matrix (depending on the input type) of the corresponding eigenvectors (in columns).

Parameters:

A : (..., M, M) array

Hermitian/Symmetric matrices whose eigenvalues and eigenvectors are to be computed.

UPLO : {‘L’, ‘U’}, optional

Specifies whether the calculation is done with the lower triangular part of a (‘L’, default) or the upper triangular part (‘U’).
Returns:

w : (..., M) ndarray

The eigenvalues, not necessarily ordered.

v : {(..., M, M) ndarray, (..., M, M) matrix}

The column v[:, i] is the normalized eigenvector corresponding to the eigenvalue w[i]. Will return a matrix object if a is a matrix object.
Raises:

LinAlgError

If the eigenvalue computation does not converge.

See also

eigvalsh
eigenvalues of symmetric or Hermitian arrays.
eig
eigenvalues and right eigenvectors for non-symmetric arrays.
eigvals
eigenvalues of non-symmetric arrays.

Notes

Broadcasting rules apply, see the numpy.linalg documentation for details.

The eigenvalues/eigenvectors are computed using LAPACK routines _ssyevd, _heevd

The eigenvalues of real symmetric or complex Hermitian matrices are always real. [R38] The array v of (column) eigenvectors is unitary and a, w, and v satisfy the equations dot(a, v[:, i]) = w[i] * v[:, i].

References

[R38] (1, 2) G. Strang, Linear Algebra and Its Applications, 2nd Ed., Orlando, FL, Academic Press, Inc., 1980, pg. 222.

Examples

>>> from numpy import linalg as LA
>>> a = np.array([[1, -2j], [2j, 5]])
>>> a
array([[ 1.+0.j,  0.-2.j],
       [ 0.+2.j,  5.+0.j]])
>>> w, v = LA.eigh(a)
>>> w; v
array([ 0.17157288,  5.82842712])
array([[-0.92387953+0.j        , -0.38268343+0.j        ],
       [ 0.00000000+0.38268343j,  0.00000000-0.92387953j]])

>>> np.dot(a, v[:, 0]) - w[0] * v[:, 0] # verify 1st e-val/vec pair
array([2.77555756e-17 + 0.j, 0. + 1.38777878e-16j])
>>> np.dot(a, v[:, 1]) - w[1] * v[:, 1] # verify 2nd e-val/vec pair
array([ 0.+0.j,  0.+0.j])

>>> A = np.matrix(a) # what happens if input is a matrix object
>>> A
matrix([[ 1.+0.j,  0.-2.j],
        [ 0.+2.j,  5.+0.j]])
>>> w, v = LA.eigh(A)
>>> w; v
array([ 0.17157288,  5.82842712])
matrix([[-0.92387953+0.j        , -0.38268343+0.j        ],
        [ 0.00000000+0.38268343j,  0.00000000-0.92387953j]])


numpy.linalg.eigvals

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.eigh

Next topic

numpy.linalg.eigvalsh

numpy.linalg.eigvals

numpy.linalg.eigvals(a) [source]

Compute the eigenvalues of a general matrix.

Main difference between eigvals and eig: the eigenvectors aren’t returned.

Parameters:

a : (..., M, M) array_like

A complex- or real-valued matrix whose eigenvalues will be computed.
Returns:

w : (..., M,) ndarray

The eigenvalues, each repeated according to its multiplicity. They are not necessarily ordered, nor are they necessarily real for real matrices.
Raises:

LinAlgError

If the eigenvalue computation does not converge.

See also

eig
eigenvalues and right eigenvectors of general arrays
eigvalsh
eigenvalues of symmetric or Hermitian arrays.
eigh
eigenvalues and eigenvectors of symmetric/Hermitian arrays.

Notes

Broadcasting rules apply, see the numpy.linalg documentation for details.

This is implemented using the _geev LAPACK routines which compute the eigenvalues and eigenvectors of general square arrays.

Examples

Illustration, using the fact that the eigenvalues of a diagonal matrix are its diagonal elements, that multiplying a matrix on the left by an orthogonal matrix, Q, and on the right by Q.T (the transpose of Q), preserves the eigenvalues of the “middle” matrix. In other words, if Q is orthogonal, then Q * A * Q.T has the same eigenvalues as A:

>>> from numpy import linalg as LA
>>> x = np.random.random()
>>> Q = np.array([[np.cos(x), -np.sin(x)], [np.sin(x), np.cos(x)]])
>>> LA.norm(Q[0, :]), LA.norm(Q[1, :]), np.dot(Q[0, :],Q[1, :])
(1.0, 1.0, 0.0)

Now multiply a diagonal matrix by Q on one side and by Q.T on the other:

>>> D = np.diag((-1,1))
>>> LA.eigvals(D)
array([-1.,  1.])
>>> A = np.dot(Q, D)
>>> A = np.dot(A, Q.T)
>>> LA.eigvals(A)
array([ 1., -1.])


numpy.linalg.eigvalsh

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.eigvals

Next topic

numpy.linalg.norm

numpy.linalg.eigvalsh

numpy.linalg.eigvalsh(a, UPLO='L') [source]

Compute the eigenvalues of a Hermitian or real symmetric matrix.

Main difference from eigh: the eigenvectors are not computed.

Parameters:

a : (..., M, M) array_like

A complex- or real-valued matrix whose eigenvalues are to be computed.

UPLO : {‘L’, ‘U’}, optional

Same as lower, with ‘L’ for lower and ‘U’ for upper triangular. Deprecated.
Returns:

w : (..., M,) ndarray

The eigenvalues, not necessarily ordered, each repeated according to its multiplicity.
Raises:

LinAlgError

If the eigenvalue computation does not converge.

See also

eigh
eigenvalues and eigenvectors of symmetric/Hermitian arrays.
eigvals
eigenvalues of general real or complex arrays.
eig
eigenvalues and right eigenvectors of general real or complex arrays.

Notes

Broadcasting rules apply, see the numpy.linalg documentation for details.

The eigenvalues are computed using LAPACK routines _ssyevd, _heevd

Examples

>>> from numpy import linalg as LA
>>> a = np.array([[1, -2j], [2j, 5]])
>>> LA.eigvalsh(a)
array([ 0.17157288+0.j,  5.82842712+0.j])


numpy.linalg.norm

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.eigvalsh

Next topic

numpy.linalg.cond

numpy.linalg.norm

numpy.linalg.norm(x, ord=None, axis=None) [source]

Matrix or vector norm.

This function is able to return one of seven different matrix norms, or one of an infinite number of vector norms (described below), depending on the value of the ord parameter.

Parameters:

x : array_like

Input array. If axis is None, x must be 1-D or 2-D.

ord : {non-zero int, inf, -inf, ‘fro’}, optional

Order of the norm (see table under Notes). inf means numpy’s inf object.

axis : {int, 2-tuple of ints, None}, optional

If axis is an integer, it specifies the axis of x along which to compute the vector norms. If axis is a 2-tuple, it specifies the axes that hold 2-D matrices, and the matrix norms of these matrices are computed. If axis is None then either a vector norm (when x is 1-D) or a matrix norm (when x is 2-D) is returned.
Returns:

n : float or ndarray

Norm of the matrix or vector(s).

Notes

For values of ord <= 0, the result is, strictly speaking, not a mathematical ‘norm’, but it may still be useful for various numerical purposes.

The following norms can be calculated:

ord | norm for matrices | norm for vectors
None | Frobenius norm | 2-norm
‘fro’ Frobenius norm –
inf | max(sum(abs(x), axis=1)) | max(abs(x))
-inf | min(sum(abs(x), axis=1)) | min(abs(x))
0 – sum(x != 0)
1 | max(sum(abs(x), axis=0)) | as below
-1 | min(sum(abs(x), axis=0)) | as below
2 | 2-norm (largest sing. value) | as below
-2 | smallest singular value | as below
other – sum(abs(x)**ord)**(1./ord)

The Frobenius norm is given by [R41]:

References

[R41] (1, 2) G. H. Golub and C. F. Van Loan, Matrix Computations, Baltimore, MD, Johns Hopkins University Press, 1985, pg. 15

Examples

>>> from numpy import linalg as LA
>>> a = np.arange(9) - 4
>>> a
array([-4, -3, -2, -1,  0,  1,  2,  3,  4])
>>> b = a.reshape((3, 3))
>>> b
array([[-4, -3, -2],
       [-1,  0,  1],
       [ 2,  3,  4]])

>>> LA.norm(a)
7.745966692414834
>>> LA.norm(b)
7.745966692414834
>>> LA.norm(b, 'fro')
7.745966692414834
>>> LA.norm(a, np.inf)
4
>>> LA.norm(b, np.inf)
9
>>> LA.norm(a, -np.inf)
0
>>> LA.norm(b, -np.inf)
2

>>> LA.norm(a, 1)
20
>>> LA.norm(b, 1)
7
>>> LA.norm(a, -1)
-4.6566128774142013e-010
>>> LA.norm(b, -1)
6
>>> LA.norm(a, 2)
7.745966692414834
>>> LA.norm(b, 2)
7.3484692283495345

>>> LA.norm(a, -2)
nan
>>> LA.norm(b, -2)
1.8570331885190563e-016
>>> LA.norm(a, 3)
5.8480354764257312
>>> LA.norm(a, -3)
nan

Using the axis argument to compute vector norms:

>>> c = np.array([[ 1, 2, 3],
...               [-1, 1, 4]])
>>> LA.norm(c, axis=0)
array([ 1.41421356,  2.23606798,  5.        ])
>>> LA.norm(c, axis=1)
array([ 3.74165739,  4.24264069])
>>> LA.norm(c, ord=1, axis=1)
array([6, 6])

Using the axis argument to compute matrix norms:

>>> m = np.arange(8).reshape(2,2,2)
>>> LA.norm(m, axis=(1,2))
array([  3.74165739,  11.22497216])
>>> LA.norm(m[0, :, :]), LA.norm(m[1, :, :])
(3.7416573867739413, 11.224972160321824)


numpy.linalg.cond

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.norm

Next topic

numpy.linalg.det

numpy.linalg.cond

numpy.linalg.cond(x, p=None) [source]

Compute the condition number of a matrix.

This function is capable of returning the condition number using one of seven different norms, depending on the value of p (see Parameters below).

Parameters:

x : (M, N) array_like

The matrix whose condition number is sought.

p : {None, 1, -1, 2, -2, inf, -inf, ‘fro’}, optional

Order of the norm:

p | norm for matrices
None | 2-norm, computed directly using the SVD
‘fro’ | Frobenius norm
inf | max(sum(abs(x), axis=1))
-inf | min(sum(abs(x), axis=1))
1 | max(sum(abs(x), axis=0))
-1 | min(sum(abs(x), axis=0))
2 | 2-norm (largest sing. value)
-2 | smallest singular value

inf means the numpy.inf object, and the Frobenius norm is the root-of-sum-of-squares norm.
Returns:

c : {float, inf}

The condition number of the matrix. May be infinite.

See also

numpy.linalg.norm

Notes

The condition number of x is defined as the norm of x times the norm of the inverse of x [R37]; the norm can be the usual L2-norm (root-of-sum-of-squares) or one of a number of other matrix norms.

References

[R37] (1, 2) G. Strang, Linear Algebra and Its Applications, Orlando, FL, Academic Press, Inc., 1980, pg. 285.

Examples

>>> from numpy import linalg as LA
>>> a = np.array([[1, 0, -1], [0, 1, 0], [1, 0, 1]])
>>> a
array([[ 1,  0, -1],
       [ 0,  1,  0],
       [ 1,  0,  1]])
>>> LA.cond(a)
1.4142135623730951
>>> LA.cond(a, 'fro')
3.1622776601683795
>>> LA.cond(a, np.inf)
2.0
>>> LA.cond(a, -np.inf)
1.0
>>> LA.cond(a, 1)
2.0
>>> LA.cond(a, -1)
1.0
>>> LA.cond(a, 2)
1.4142135623730951
>>> LA.cond(a, -2)
0.70710678118654746
>>> min(LA.svd(a, compute_uv=0))*min(LA.svd(LA.inv(a), compute_uv=0))
0.70710678118654746


numpy.linalg.det

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.cond

Next topic

numpy.linalg.matrix_rank

numpy.linalg.det

numpy.linalg.det(a) [source]

Compute the determinant of an array.

Parameters:

a : (..., M, M) array_like

Input array to compute determinants for.
Returns:

det : (...) array_like

Determinant of a.

See also

slogdet
Another way to representing the determinant, more suitable for large matrices where underflow/overflow may occur.

Notes

Broadcasting rules apply, see the numpy.linalg documentation for details.

The determinant is computed via LU factorization using the LAPACK routine z/dgetrf.

Examples

The determinant of a 2-D array [[a, b], [c, d]] is ad - bc:

>>> a = np.array([[1, 2], [3, 4]])
>>> np.linalg.det(a)
-2.0

Computing determinants for a stack of matrices:

>>> a = np.array([ [[1, 2], [3, 4]], [[1, 2], [2, 1]], [[1, 3], [3, 1]] ])
>>> a.shape
(2, 2, 2
>>> np.linalg.det(a)
array([-2., -3., -8.])


numpy.linalg.matrix_rank

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.det

Next topic

numpy.linalg.slogdet

numpy.linalg.matrix_rank

numpy.linalg.matrix_rank(M, tol=None) [source]

Return matrix rank of array using SVD method

Rank of the array is the number of SVD singular values of the array that are greater than tol.

Parameters:

M : {(M,), (M, N)} array_like

array of <=2 dimensions

tol : {None, float}, optional

threshold below which SVD values are considered zero. If tol is None, and S is an array with singular values for M, and eps is the epsilon value for datatype of S, then tol is set to S.max() * max(M.shape) * eps.

Notes

The default threshold to detect rank deficiency is a test on the magnitude of the singular values of M. By default, we identify singular values less than S.max() * max(M.shape) * eps as indicating rank deficiency (with the symbols defined above). This is the algorithm MATLAB uses [1]. It also appears in Numerical recipes in the discussion of SVD solutions for linear least squares [2].

This default threshold is designed to detect rank deficiency accounting for the numerical errors of the SVD computation. Imagine that there is a column in M that is an exact (in floating point) linear combination of other columns in M. Computing the SVD on M will not produce a singular value exactly equal to 0 in general: any difference of the smallest SVD value from 0 will be caused by numerical imprecision in the calculation of the SVD. Our threshold for small SVD values takes this numerical imprecision into account, and the default threshold will detect such numerical rank deficiency. The threshold may declare a matrix M rank deficient even if the linear combination of some columns of M is not exactly equal to another column of M but only numerically very close to another column of M.

We chose our default threshold because it is in wide use. Other thresholds are possible. For example, elsewhere in the 2007 edition of Numerical recipes there is an alternative threshold of S.max() * np.finfo(M.dtype).eps / 2. * np.sqrt(m + n + 1.). The authors describe this threshold as being based on “expected roundoff error” (p 71).

The thresholds above deal with floating point roundoff error in the calculation of the SVD. However, you may have more information about the sources of error in M that would make you consider other tolerance values to detect effective rank deficiency. The most useful measure of the tolerance depends on the operations you intend to use on your matrix. For example, if your data come from uncertain measurements with uncertainties greater than floating point epsilon, choosing a tolerance near that uncertainty may be preferable. The tolerance may be absolute if the uncertainties are absolute rather than relative.

References

[R39] MATLAB reference documention, “Rank” http://www.mathworks.com/help/techdoc/ref/rank.html
[R40] W. H. Press, S. A. Teukolsky, W. T. Vetterling and B. P. Flannery, “Numerical Recipes (3rd edition)”, Cambridge University Press, 2007, page 795.

Examples

>>> from numpy.linalg import matrix_rank
>>> matrix_rank(np.eye(4)) # Full rank matrix
4
>>> I=np.eye(4); I[-1,-1] = 0. # rank deficient matrix
>>> matrix_rank(I)
3
>>> matrix_rank(np.ones((4,))) # 1 dimension - rank 1 unless all 0
1
>>> matrix_rank(np.zeros((4,)))
0


numpy.linalg.slogdet

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.matrix_rank

Next topic

numpy.trace

numpy.linalg.slogdet

numpy.linalg.slogdet(a) [source]

Compute the sign and (natural) logarithm of the determinant of an array.

If an array has a very small or very large determinant, than a call to det may overflow or underflow. This routine is more robust against such issues, because it computes the logarithm of the determinant rather than the determinant itself.

Parameters:

a : (..., M, M) array_like

Input array, has to be a square 2-D array.
Returns:

sign : (...) array_like

A number representing the sign of the determinant. For a real matrix, this is 1, 0, or -1. For a complex matrix, this is a complex number with absolute value 1 (i.e., it is on the unit circle), or else 0.

logdet : (...) array_like

The natural log of the absolute value of the determinant.

If the determinant is zero, then sign will be 0 and logdet will be

-Inf. In all cases, the determinant is equal to sign * np.exp(logdet).

See also

det

Notes

Broadcasting rules apply, see the numpy.linalg documentation for details.

The determinant is computed via LU factorization using the LAPACK routine z/dgetrf.

New in version 1.6.0..

Examples

The determinant of a 2-D array [[a, b], [c, d]] is ad - bc:

>>> a = np.array([[1, 2], [3, 4]])
>>> (sign, logdet) = np.linalg.slogdet(a)
>>> (sign, logdet)
(-1, 0.69314718055994529)
>>> sign * np.exp(logdet)
-2.0

Computing log-determinants for a stack of matrices:

>>> a = np.array([ [[1, 2], [3, 4]], [[1, 2], [2, 1]], [[1, 3], [3, 1]] ])
>>> a.shape
(3, 2, 2)
>>> sign, logdet = np.linalg.slogdet(a)
>>> (sign, logdet)
(array([-1., -1., -1.]), array([ 0.69314718,  1.09861229,  2.07944154]))
>>> sign * np.exp(logdet)
array([-2., -3., -8.])

This routine succeeds where ordinary det does not:

>>> np.linalg.det(np.eye(500) * 0.1)
0.0
>>> np.linalg.slogdet(np.eye(500) * 0.1)
(1, -1151.2925464970228)


numpy.trace

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.slogdet

Next topic

numpy.linalg.solve

numpy.trace

numpy.trace(a, offset=0, axis1=0, axis2=1, dtype=None, out=None) [source]

Return the sum along diagonals of the array.

If a is 2-D, the sum along its diagonal with the given offset is returned, i.e., the sum of elements a[i,i+offset] for all i.

If a has more than two dimensions, then the axes specified by axis1 and axis2 are used to determine the 2-D sub-arrays whose traces are returned. The shape of the resulting array is the same as that of a with axis1 and axis2 removed.

Parameters:

a : array_like

Input array, from which the diagonals are taken.

offset : int, optional

Offset of the diagonal from the main diagonal. Can be both positive and negative. Defaults to 0.

axis1, axis2 : int, optional

Axes to be used as the first and second axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults are the first two axes of a.

dtype : dtype, optional

Determines the data-type of the returned array and of the accumulator where the elements are summed. If dtype has the value None and a is of integer type of precision less than the default integer precision, then the default integer precision is used. Otherwise, the precision is the same as that of a.

out : ndarray, optional

Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output.
Returns:

sum_along_diagonals : ndarray

If a is 2-D, the sum along the diagonal is returned. If a has larger dimensions, then an array of sums along diagonals is returned.

See also

diag, diagonal, diagflat

Examples

>>> np.trace(np.eye(3))
3.0
>>> a = np.arange(8).reshape((2,2,2))
>>> np.trace(a)
array([6, 8])

>>> a = np.arange(24).reshape((2,2,2,3))
>>> np.trace(a).shape
(2, 3)


numpy.linalg.solve

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.trace

Next topic

numpy.linalg.tensorsolve

numpy.linalg.solve

numpy.linalg.solve(a, b) [source]

Solve a linear matrix equation, or system of linear scalar equations.

Computes the “exact” solution, x, of the well-determined, i.e., full rank, linear matrix equation ax = b.

Parameters:

a : (..., M, M) array_like

Coefficient matrix.

b : {(..., M,), (..., M, K)}, array_like

Ordinate or “dependent variable” values.
Returns:

x : {(..., M,), (..., M, K)} ndarray

Solution to the system a x = b. Returned shape is identical to b.
Raises:

LinAlgError

If a is singular or not square.

Notes

Broadcasting rules apply, see the numpy.linalg documentation for details.

The solutions are computed using LAPACK routine _gesv

a must be square and of full-rank, i.e., all rows (or, equivalently, columns) must be linearly independent; if either is not true, use lstsq for the least-squares best “solution” of the system/equation.

References

[R43] G. Strang, Linear Algebra and Its Applications, 2nd Ed., Orlando, FL, Academic Press, Inc., 1980, pg. 22.

Examples

Solve the system of equations 3 * x0 + x1 = 9 and x0 + 2 * x1 = 8:

>>> a = np.array([[3,1], [1,2]])
>>> b = np.array([9,8])
>>> x = np.linalg.solve(a, b)
>>> x
array([ 2.,  3.])

Check that the solution is correct:

>>> np.allclose(np.dot(a, x), b)
True


numpy.linalg.tensorsolve

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.solve

Next topic

numpy.linalg.lstsq

numpy.linalg.tensorsolve

numpy.linalg.tensorsolve(a, b, axes=None) [source]

Solve the tensor equation a x = b for x.

It is assumed that all indices of x are summed over in the product, together with the rightmost indices of a, as is done in, for example, tensordot(a, x, axes=len(b.shape)).

Parameters:

a : array_like

Coefficient tensor, of shape b.shape + Q. Q, a tuple, equals the shape of that sub-tensor of a consisting of the appropriate number of its rightmost indices, and must be such that

prod(Q) == prod(b.shape) (in which sense a is said to be ‘square’).

b : array_like

Right-hand tensor, which can be of any shape.

axes : tuple of ints, optional

Axes in a to reorder to the right, before inversion. If None (default), no reordering is done.
Returns:

x : ndarray, shape Q
Raises:

LinAlgError

If a is singular or not ‘square’ (in the above sense).

See also

tensordot, tensorinv, einsum

Examples

>>> a = np.eye(2*3*4)
>>> a.shape = (2*3, 4, 2, 3, 4)
>>> b = np.random.randn(2*3, 4)
>>> x = np.linalg.tensorsolve(a, b)
>>> x.shape
(2, 3, 4)
>>> np.allclose(np.tensordot(a, x, axes=3), b)
True


numpy.linalg.lstsq

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.tensorsolve

Next topic

numpy.linalg.inv

numpy.linalg.lstsq

numpy.linalg.lstsq(a, b, rcond=-1) [source]

Return the least-squares solution to a linear matrix equation.

Solves the equation a x = b by computing a vector x that minimizes the Euclidean 2-norm || b - a x ||^2. The equation may be under-, well-, or over- determined (i.e., the number of linearly independent rows of a can be less than, equal to, or greater than its number of linearly independent columns). If a is square and of full rank, then x (but for round-off error) is the “exact” solution of the equation.

Parameters:

a : (M, N) array_like

“Coefficient” matrix.

b : {(M,), (M, K)} array_like

Ordinate or “dependent variable” values. If b is two-dimensional, the least-squares solution is calculated for each of the K columns of b.

rcond : float, optional

Cut-off ratio for small singular values of a. Singular values are set to zero if they are smaller than rcond times the largest singular value of a.
Returns:

x : {(N,), (N, K)} ndarray

Least-squares solution. If b is two-dimensional, the solutions are in the K columns of x.

residuals : {(), (1,), (K,)} ndarray

Sums of residuals; squared Euclidean 2-norm for each column in b - a*x. If the rank of a is < N or M <= N, this is an empty array. If b is 1-dimensional, this is a (1,) shape array. Otherwise the shape is (K,).

rank : int

Rank of matrix a.

s : (min(M, N),) ndarray

Singular values of a.
Raises:

LinAlgError

If computation does not converge.

Notes

If b is a matrix, then all array results are returned as matrices.

Examples

Fit a line, y = mx + c, through some noisy data-points:

>>> x = np.array([0, 1, 2, 3])
>>> y = np.array([-1, 0.2, 0.9, 2.1])

By examining the coefficients, we see that the line should have a gradient of roughly 1 and cut the y-axis at, more or less, -1.

We can rewrite the line equation as y = Ap, where A = [[x 1]] and p = [[m], [c]]. Now use lstsq to solve for p:

>>> A = np.vstack([x, np.ones(len(x))]).T
>>> A
array([[ 0.,  1.],
       [ 1.,  1.],
       [ 2.,  1.],
       [ 3.,  1.]])

>>> m, c = np.linalg.lstsq(A, y)[0]
>>> print m, c
1.0 -0.95

Plot the data along with the fitted line:

>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y, 'o', label='Original data', markersize=10)
>>> plt.plot(x, m*x + c, 'r', label='Fitted line')
>>> plt.legend()
>>> plt.show()

(Source code, png, pdf)


numpy.linalg.inv

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.lstsq

Next topic

numpy.linalg.pinv

numpy.linalg.inv

numpy.linalg.inv(a) [source]

Compute the (multiplicative) inverse of a matrix.

Given a square matrix a, return the matrix ainv satisfying dot(a, ainv) = dot(ainv, a) = eye(a.shape[0]).

Parameters:

a : (..., M, M) array_like

Matrix to be inverted.
Returns:

ainv : (..., M, M) ndarray or matrix

(Multiplicative) inverse of the matrix a.
Raises:

LinAlgError

If a is not square or inversion fails.

Notes

Broadcasting rules apply, see the numpy.linalg documentation for details.

Examples

>>> from numpy.linalg import inv
>>> a = np.array([[1., 2.], [3., 4.]])
>>> ainv = inv(a)
>>> np.allclose(np.dot(a, ainv), np.eye(2))
True
>>> np.allclose(np.dot(ainv, a), np.eye(2))
True

If a is a matrix object, then the return value is a matrix as well:

>>> ainv = inv(np.matrix(a))
>>> ainv
matrix([[-2. ,  1. ],
        [ 1.5, -0.5]])

Inverses of several matrices can be computed at once:

>>> a = np.array([[[1., 2.], [3., 4.]], [[1, 3], [3, 5]]])
>>> inv(a)
array([[[-2. ,  1. ],
        [ 1.5, -0.5]],
       [[-5. ,  2. ],
        [ 3. , -1. ]]])


numpy.linalg.pinv

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.inv

Next topic

numpy.linalg.tensorinv

numpy.linalg.pinv

numpy.linalg.pinv(a, rcond=1e-15) [source]

Compute the (Moore-Penrose) pseudo-inverse of a matrix.

Calculate the generalized inverse of a matrix using its singular-value decomposition (SVD) and including all large singular values.

Parameters:

a : (M, N) array_like

Matrix to be pseudo-inverted.

rcond : float

Cutoff for small singular values. Singular values smaller (in modulus) than rcond * largest_singular_value (again, in modulus) are set to zero.
Returns:

B : (N, M) ndarray

The pseudo-inverse of a. If a is a matrix instance, then so is B.
Raises:

LinAlgError

If the SVD computation does not converge.

Notes

The pseudo-inverse of a matrix A, denoted [image], is defined as: “the matrix that ‘solves’ [the least-squares problem] Ax = b,” i.e., if [image] is said solution, then [image] is that matrix such that [image].

It can be shown that if [image] is the singular value decomposition of A, then [image], where [image] are orthogonal matrices, [image] is a diagonal matrix consisting of A’s so-called singular values, (followed, typically, by zeros), and then [image] is simply the diagonal matrix consisting of the reciprocals of A’s singular values (again, followed by zeros). [R42]

References

[R42] (1, 2) G. Strang, Linear Algebra and Its Applications, 2nd Ed., Orlando, FL, Academic Press, Inc., 1980, pp. 139-142.

Examples

The following example checks that a * a+ * a == a and a+ * a * a+ == a+:

>>> a = np.random.randn(9, 6)
>>> B = np.linalg.pinv(a)
>>> np.allclose(a, np.dot(a, np.dot(B, a)))
True
>>> np.allclose(B, np.dot(B, np.dot(a, B)))
True


numpy.linalg.tensorinv

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.pinv

Next topic

numpy.linalg.LinAlgError

numpy.linalg.tensorinv

numpy.linalg.tensorinv(a, ind=2) [source]

Compute the ‘inverse’ of an N-dimensional array.

The result is an inverse for a relative to the tensordot operation tensordot(a, b, ind), i. e., up to floating-point accuracy, tensordot(tensorinv(a), a, ind) is the “identity” tensor for the tensordot operation.

Parameters:

a : array_like

Tensor to ‘invert’. Its shape must be ‘square’, i. e., prod(a.shape[:ind]) == prod(a.shape[ind:]).

ind : int, optional

Number of first indices that are involved in the inverse sum. Must be a positive integer, default is 2.
Returns:

b : ndarray

a‘s tensordot inverse, shape a.shape[ind:] + a.shape[:ind].
Raises:

LinAlgError

If a is singular or not ‘square’ (in the above sense).

See also

tensordot, tensorsolve

Examples

>>> a = np.eye(4*6)
>>> a.shape = (4, 6, 8, 3)
>>> ainv = np.linalg.tensorinv(a, ind=2)
>>> ainv.shape
(8, 3, 4, 6)
>>> b = np.random.randn(4, 6)
>>> np.allclose(np.tensordot(ainv, b), np.linalg.tensorsolve(a, b))
True

>>> a = np.eye(4*6)
>>> a.shape = (24, 8, 3)
>>> ainv = np.linalg.tensorinv(a, ind=1)
>>> ainv.shape
(8, 3, 24)
>>> b = np.random.randn(24)
>>> np.allclose(np.tensordot(ainv, b, 1), np.linalg.tensorsolve(a, b))
True


numpy.linalg.LinAlgError

  • Linear algebra (numpy.linalg)
  • index
  • next
  • previous

Previous topic

numpy.linalg.tensorinv

Next topic

Logic functions

numpy.linalg.LinAlgError

exception numpy.linalg.LinAlgError [source]

Generic Python-exception-derived object raised by linalg functions.

General purpose exception class, derived from Python’s exception.Exception class, programmatically raised in linalg functions when a Linear Algebra-related condition would prevent further correct execution of the function.

Parameters: None

Examples

>>> from numpy import linalg as LA
>>> LA.inv(np.zeros((2,2)))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "...linalg.py", line 350,
    in inv return wrap(solve(a, identity(a.shape[0], dtype=a.dtype)))
  File "...linalg.py", line 249,
    in solve
    raise LinAlgError('Singular matrix')
numpy.linalg.LinAlgError: Singular matrix


Logic functions

  • next
  • previous

Table Of Contents

  • Logic functions
    • Truth value testing
    • Array contents
    • Array type testing
    • Logical operations
    • Comparison

Previous topic

numpy.linalg.LinAlgError

Next topic

numpy.all

Logic functions

Truth value testing

all(a[, axis, out, keepdims]) | Test whether all array elements along a given axis evaluate to True.
any(a[, axis, out, keepdims]) | Test whether any array element along a given axis evaluates to True.

Array contents

isfinite(x[, out]) | Test element-wise for finiteness (not infinity or not Not a Number).
isinf(x[, out]) | Test element-wise for positive or negative infinity.
isnan(x[, out]) | Test element-wise for NaN and return result as a boolean array.
isneginf(x[, y]) | Test element-wise for negative infinity, return result as bool array.
isposinf(x[, y]) | Test element-wise for positive infinity, return result as bool array.

Array type testing

iscomplex(x) | Returns a bool array, where True if input element is complex.
iscomplexobj(x) | Check for a complex type or an array of complex numbers.
isfortran(a) | Returns True if array is arranged in Fortran-order in memory and not C-order.
isreal(x) | Returns a bool array, where True if input element is real.
isrealobj(x) | Return True if x is a not complex type or an array of complex numbers.
isscalar(num) | Returns True if the type of num is a scalar type.

Logical operations

logical_and(x1, x2[, out]) | Compute the truth value of x1 AND x2 element-wise.
logical_or(x1, x2[, out]) | Compute the truth value of x1 OR x2 element-wise.
logical_not(x[, out]) | Compute the truth value of NOT x element-wise.
logical_xor(x1, x2[, out]) | Compute the truth value of x1 XOR x2, element-wise.

Comparison

allclose(a, b[, rtol, atol]) | Returns True if two arrays are element-wise equal within a tolerance.
isclose(a, b[, rtol, atol, equal_nan]) | Returns a boolean array where two arrays are element-wise equal within a tolerance.
array_equal(a1, a2) | True if two arrays have the same shape and elements, False otherwise.
array_equiv(a1, a2) | Returns True if input arrays are shape consistent and all elements equal.
greater(x1, x2[, out]) | Return the truth value of (x1 > x2) element-wise.
greater_equal(x1, x2[, out]) | Return the truth value of (x1 >= x2) element-wise.
less(x1, x2[, out]) | Return the truth value of (x1 < x2) element-wise.
less_equal(x1, x2[, out]) | Return the truth value of (x1 =< x2) element-wise.
equal(x1, x2[, out]) | Return (x1 == x2) element-wise.
not_equal(x1, x2[, out]) | Return (x1 != x2) element-wise.


numpy.all

  • Logic functions
  • next
  • previous

Previous topic

numpy.not_equal

Next topic

numpy.any

numpy.all

numpy.all(a, axis=None, out=None, keepdims=False) [source]

Test whether all array elements along a given axis evaluate to True.

Parameters:

a : array_like

Input array or object that can be converted to an array.

axis : None or int or tuple of ints, optional

Axis or axes along which a logical AND reduction is performed. The default (axis = None) is to perform a logical AND over all the dimensions of the input array. axis may be negative, in which case it counts from the last to the first axis.

New in version 1.7.0.

If this is a tuple of ints, a reduction is performed on multiple axes, instead of a single axis or all the axes as before.

out : ndarray, optional

Alternate output array in which to place the result. It must have the same shape as the expected output and its type is preserved (e.g., if dtype(out) is float, the result will consist of 0.0’s and 1.0’s). See doc.ufuncs (Section “Output arguments”) for more details.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

all : ndarray, bool

A new boolean or array is returned unless out is specified, in which case a reference to out is returned.

See also

ndarray.all
equivalent method
any
Test whether any element along a given axis evaluates to True.

Notes

Not a Number (NaN), positive infinity and negative infinity evaluate to True because these are not equal to zero.

Examples

>>> np.all([[True,False],[True,True]])
False

>>> np.all([[True,False],[True,True]], axis=0)
array([ True, False], dtype=bool)

>>> np.all([-1, 4, 5])
True

>>> np.all([1.0, np.nan])
True

>>> o=np.array([False])
>>> z=np.all([-1, 4, 5], out=o)
>>> id(z), id(o), z
(28293632, 28293632, array([ True], dtype=bool))


numpy.any

  • Logic functions
  • next
  • previous

Previous topic

numpy.all

Next topic

numpy.isfinite

numpy.any

numpy.any(a, axis=None, out=None, keepdims=False) [source]

Test whether any array element along a given axis evaluates to True.

Returns single boolean unless axis is not None

Parameters:

a : array_like

Input array or object that can be converted to an array.

axis : None or int or tuple of ints, optional

Axis or axes along which a logical OR reduction is performed. The default (axis = None) is to perform a logical OR over all the dimensions of the input array. axis may be negative, in which case it counts from the last to the first axis.

New in version 1.7.0.

If this is a tuple of ints, a reduction is performed on multiple axes, instead of a single axis or all the axes as before.

out : ndarray, optional

Alternate output array in which to place the result. It must have the same shape as the expected output and its type is preserved (e.g., if it is of type float, then it will remain so, returning 1.0 for True and 0.0 for False, regardless of the type of a). See doc.ufuncs (Section “Output arguments”) for details.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

any : bool or ndarray

A new boolean or ndarray is returned unless out is specified, in which case a reference to out is returned.

See also

ndarray.any
equivalent method
all
Test whether all elements along a given axis evaluate to True.

Notes

Not a Number (NaN), positive infinity and negative infinity evaluate to True because these are not equal to zero.

Examples

>>> np.any([[True, False], [True, True]])
True

>>> np.any([[True, False], [False, False]], axis=0)
array([ True, False], dtype=bool)

>>> np.any([-1, 0, 5])
True

>>> np.any(np.nan)
True

>>> o=np.array([False])
>>> z=np.any([-1, 4, 5], out=o)
>>> z, o
(array([ True], dtype=bool), array([ True], dtype=bool))
>>> # Check now that z is a reference to o
>>> z is o
True
>>> id(z), id(o) # identity of z and o
(191614240, 191614240)


numpy.isfinite

  • Logic functions
  • next
  • previous

Previous topic

numpy.any

Next topic

numpy.isinf

numpy.isfinite

numpy.isfinite(x[, out]) = <ufunc 'isfinite'>

Test element-wise for finiteness (not infinity or not Not a Number).

The result is returned as a boolean array.

Parameters:

x : array_like

Input values.

out : ndarray, optional

Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output. See doc.ufuncs.
Returns:

y : ndarray, bool

For scalar input, the result is a new boolean with value True if the input is finite; otherwise the value is False (input is either positive infinity, negative infinity or Not a Number).

For array input, the result is a boolean array with the same dimensions as the input and the values are True if the corresponding element of the input is finite; otherwise the values are False (element is either positive infinity, negative infinity or Not a Number).

See also

isinf, isneginf, isposinf, isnan

Notes

Not a Number, positive infinity and negative infinity are considered to be non-finite.

Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). This means that Not a Number is not equivalent to infinity. Also that positive infinity is not equivalent to negative infinity. But infinity is equivalent to positive infinity. Errors result if the second argument is also supplied when x is a scalar input, or if first and second arguments have different shapes.

Examples

>>> np.isfinite(1)
True
>>> np.isfinite(0)
True
>>> np.isfinite(np.nan)
False
>>> np.isfinite(np.inf)
False
>>> np.isfinite(np.NINF)
False
>>> np.isfinite([np.log(-1.),1.,np.log(0)])
array([False,  True, False], dtype=bool)

>>> x = np.array([-np.inf, 0., np.inf])
>>> y = np.array([2, 2, 2])
>>> np.isfinite(x, y)
array([0, 1, 0])
>>> y
array([0, 1, 0])


numpy.isinf

  • Logic functions
  • next
  • previous

Previous topic

numpy.isfinite

Next topic

numpy.isnan

numpy.isinf

numpy.isinf(x[, out]) = <ufunc 'isinf'>

Test element-wise for positive or negative infinity.

Returns a boolean array of the same shape as x, True where x == +/-inf, otherwise False.

Parameters:

x : array_like

Input values

out : array_like, optional

An array with the same shape as x to store the result.
Returns:

y : bool (scalar) or boolean ndarray

For scalar input, the result is a new boolean with value True if the input is positive or negative infinity; otherwise the value is False.

For array input, the result is a boolean array with the same shape as the input and the values are True where the corresponding element of the input is positive or negative infinity; elsewhere the values are False. If a second argument was supplied the result is stored there. If the type of that array is a numeric type the result is represented as zeros and ones, if the type is boolean then as False and True, respectively. The return value y is then a reference to that array.

See also

isneginf, isposinf, isnan, isfinite

Notes

Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754).

Errors result if the second argument is supplied when the first argument is a scalar, or if the first and second arguments have different shapes.

Examples

>>> np.isinf(np.inf)
True
>>> np.isinf(np.nan)
False
>>> np.isinf(np.NINF)
True
>>> np.isinf([np.inf, -np.inf, 1.0, np.nan])
array([ True,  True, False, False], dtype=bool)

>>> x = np.array([-np.inf, 0., np.inf])
>>> y = np.array([2, 2, 2])
>>> np.isinf(x, y)
array([1, 0, 1])
>>> y
array([1, 0, 1])


numpy.isnan

  • Logic functions
  • next
  • previous

Previous topic

numpy.isinf

Next topic

numpy.isneginf

numpy.isnan

numpy.isnan(x[, out]) = <ufunc 'isnan'>

Test element-wise for NaN and return result as a boolean array.

Parameters:

x : array_like

Input array.
Returns:

y : {ndarray, bool}

For scalar input, the result is a new boolean with value True if the input is NaN; otherwise the value is False.

For array input, the result is a boolean array of the same dimensions as the input and the values are True if the corresponding element of the input is NaN; otherwise the values are False.

See also

isinf, isneginf, isposinf, isfinite

Notes

Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). This means that Not a Number is not equivalent to infinity.

Examples

>>> np.isnan(np.nan)
True
>>> np.isnan(np.inf)
False
>>> np.isnan([np.log(-1.),1.,np.log(0)])
array([ True, False, False], dtype=bool)


numpy.isneginf

  • Logic functions
  • next
  • previous

Previous topic

numpy.isnan

Next topic

numpy.isposinf

numpy.isneginf

numpy.isneginf(x, y=None) [source]

Test element-wise for negative infinity, return result as bool array.

Parameters:

x : array_like

The input array.

y : array_like, optional

A boolean array with the same shape and type as x to store the result.
Returns:

y : ndarray

A boolean array with the same dimensions as the input. If second argument is not supplied then a numpy boolean array is returned with values True where the corresponding element of the input is negative infinity and values False where the element of the input is not negative infinity.

If a second argument is supplied the result is stored there. If the type of that array is a numeric type the result is represented as zeros and ones, if the type is boolean then as False and True. The return value y is then a reference to that array.

See also

isinf, isposinf, isnan, isfinite

Notes

Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754).

Errors result if the second argument is also supplied when x is a scalar input, or if first and second arguments have different shapes.

Examples

>>> np.isneginf(np.NINF)
array(True, dtype=bool)
>>> np.isneginf(np.inf)
array(False, dtype=bool)
>>> np.isneginf(np.PINF)
array(False, dtype=bool)
>>> np.isneginf([-np.inf, 0., np.inf])
array([ True, False, False], dtype=bool)

>>> x = np.array([-np.inf, 0., np.inf])
>>> y = np.array([2, 2, 2])
>>> np.isneginf(x, y)
array([1, 0, 0])
>>> y
array([1, 0, 0])


numpy.isposinf

  • Logic functions
  • next
  • previous

Previous topic

numpy.isneginf

Next topic

numpy.iscomplex

numpy.isposinf

numpy.isposinf(x, y=None) [source]

Test element-wise for positive infinity, return result as bool array.

Parameters:

x : array_like

The input array.

y : array_like, optional

A boolean array with the same shape as x to store the result.
Returns:

y : ndarray

A boolean array with the same dimensions as the input. If second argument is not supplied then a boolean array is returned with values True where the corresponding element of the input is positive infinity and values False where the element of the input is not positive infinity.

If a second argument is supplied the result is stored there. If the type of that array is a numeric type the result is represented as zeros and ones, if the type is boolean then as False and True. The return value y is then a reference to that array.

See also

isinf, isneginf, isfinite, isnan

Notes

Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754).

Errors result if the second argument is also supplied when x is a scalar input, or if first and second arguments have different shapes.

Examples

>>> np.isposinf(np.PINF)
array(True, dtype=bool)
>>> np.isposinf(np.inf)
array(True, dtype=bool)
>>> np.isposinf(np.NINF)
array(False, dtype=bool)
>>> np.isposinf([-np.inf, 0., np.inf])
array([False, False,  True], dtype=bool)

>>> x = np.array([-np.inf, 0., np.inf])
>>> y = np.array([2, 2, 2])
>>> np.isposinf(x, y)
array([0, 0, 1])
>>> y
array([0, 0, 1])


numpy.iscomplex

  • Logic functions
  • next
  • previous

Previous topic

numpy.isposinf

Next topic

numpy.iscomplexobj

numpy.iscomplex

numpy.iscomplex(x) [source]

Returns a bool array, where True if input element is complex.

What is tested is whether the input has a non-zero imaginary part, not if the input type is complex.

Parameters:

x : array_like

Input array.
Returns:

out : ndarray of bools

Output array.

See also

isreal

iscomplexobj
Return True if x is a complex type or an array of complex numbers.

Examples

>>> np.iscomplex([1+1j, 1+0j, 4.5, 3, 2, 2j])
array([ True, False, False, False, False,  True], dtype=bool)


numpy.iscomplexobj

  • Logic functions
  • next
  • previous

Previous topic

numpy.iscomplex

Next topic

numpy.isfortran

numpy.iscomplexobj

numpy.iscomplexobj(x) [source]

Check for a complex type or an array of complex numbers.

The type of the input is checked, not the value. Even if the input has an imaginary part equal to zero, iscomplexobj evaluates to True.

Parameters:

x : any

The input can be of any type and shape.
Returns:

iscomplexobj : bool

The return value, True if x is of a complex type or has at least one complex element.

See also

isrealobj, iscomplex

Examples

>>> np.iscomplexobj(1)
False
>>> np.iscomplexobj(1+0j)
True
>>> np.iscomplexobj([3, 1+0j, True])
True


numpy.isfortran

  • Logic functions
  • next
  • previous

Previous topic

numpy.iscomplexobj

Next topic

numpy.isreal

numpy.isfortran

numpy.isfortran(a) [source]

Returns True if array is arranged in Fortran-order in memory and not C-order.

Parameters:

a : ndarray

Input array.

Examples

np.array allows to specify whether the array is written in C-contiguous order (last index varies the fastest), or FORTRAN-contiguous order in memory (first index varies the fastest).

>>> a = np.array([[1, 2, 3], [4, 5, 6]], order='C')
>>> a
array([[1, 2, 3],
       [4, 5, 6]])
>>> np.isfortran(a)
False

>>> b = np.array([[1, 2, 3], [4, 5, 6]], order='FORTRAN')
>>> b
array([[1, 2, 3],
       [4, 5, 6]])
>>> np.isfortran(b)
True

The transpose of a C-ordered array is a FORTRAN-ordered array.

>>> a = np.array([[1, 2, 3], [4, 5, 6]], order='C')
>>> a
array([[1, 2, 3],
       [4, 5, 6]])
>>> np.isfortran(a)
False
>>> b = a.T
>>> b
array([[1, 4],
       [2, 5],
       [3, 6]])
>>> np.isfortran(b)
True

C-ordered arrays evaluate as False even if they are also FORTRAN-ordered.

>>> np.isfortran(np.array([1, 2], order='FORTRAN'))
False


numpy.isreal

  • Logic functions
  • next
  • previous

Previous topic

numpy.isfortran

Next topic

numpy.isrealobj

numpy.isreal

numpy.isreal(x) [source]

Returns a bool array, where True if input element is real.

If element has complex type with zero complex part, the return value for that element is True.

Parameters:

x : array_like

Input array.
Returns:

out : ndarray, bool

Boolean array of same shape as x.

See also

iscomplex

isrealobj
Return True if x is not a complex type.

Examples

>>> np.isreal([1+1j, 1+0j, 4.5, 3, 2, 2j])
array([False,  True,  True,  True,  True, False], dtype=bool)


numpy.isrealobj

  • Logic functions
  • next
  • previous

Previous topic

numpy.isreal

Next topic

numpy.isscalar

numpy.isrealobj

numpy.isrealobj(x) [source]

Return True if x is a not complex type or an array of complex numbers.

The type of the input is checked, not the value. So even if the input has an imaginary part equal to zero, isrealobj evaluates to False if the data type is complex.

Parameters:

x : any

The input can be of any type and shape.
Returns:

y : bool

The return value, False if x is of a complex type.

See also

iscomplexobj, isreal

Examples

>>> np.isrealobj(1)
True
>>> np.isrealobj(1+0j)
False
>>> np.isrealobj([3, 1+0j, True])
False


numpy.isscalar

  • Logic functions
  • next
  • previous

Previous topic

numpy.isrealobj

Next topic

numpy.logical_and

numpy.isscalar

numpy.isscalar(num) [source]

Returns True if the type of num is a scalar type.

Parameters:

num : any

Input argument, can be of any type and shape.
Returns:

val : bool

True if num is a scalar type, False if it is not.

Examples

>>> np.isscalar(3.1)
True
>>> np.isscalar([3.1])
False
>>> np.isscalar(False)
True


numpy.logical_and

  • Logic functions
  • next
  • previous

Previous topic

numpy.isscalar

Next topic

numpy.logical_or

numpy.logical_and

numpy.logical_and(x1, x2[, out]) = <ufunc 'logical_and'>

Compute the truth value of x1 AND x2 element-wise.

Parameters:

x1, x2 : array_like

Input arrays. x1 and x2 must be of the same shape.
Returns:

y : {ndarray, bool}

Boolean result with the same shape as x1 and x2 of the logical AND operation on corresponding elements of x1 and x2.

See also

logical_or, logical_not, logical_xor, bitwise_and

Examples

>>> np.logical_and(True, False)
False
>>> np.logical_and([True, False], [False, False])
array([False, False], dtype=bool)

>>> x = np.arange(5)
>>> np.logical_and(x>1, x<4)
array([False, False,  True,  True, False], dtype=bool)


numpy.logical_or

  • Logic functions
  • next
  • previous

Previous topic

numpy.logical_and

Next topic

numpy.logical_not

numpy.logical_or

numpy.logical_or(x1, x2[, out]) = <ufunc 'logical_or'>

Compute the truth value of x1 OR x2 element-wise.

Parameters:

x1, x2 : array_like

Logical OR is applied to the elements of x1 and x2. They have to be of the same shape.
Returns:

y : {ndarray, bool}

Boolean result with the same shape as x1 and x2 of the logical OR operation on elements of x1 and x2.

See also

logical_and, logical_not, logical_xor, bitwise_or

Examples

>>> np.logical_or(True, False)
True
>>> np.logical_or([True, False], [False, False])
array([ True, False], dtype=bool)

>>> x = np.arange(5)
>>> np.logical_or(x < 1, x > 3)
array([ True, False, False, False,  True], dtype=bool)


numpy.logical_not

  • Logic functions
  • next
  • previous

Previous topic

numpy.logical_or

Next topic

numpy.logical_xor

numpy.logical_not

numpy.logical_not(x[, out]) = <ufunc 'logical_not'>

Compute the truth value of NOT x element-wise.

Parameters:

x : array_like

Logical NOT is applied to the elements of x.
Returns:

y : bool or ndarray of bool

Boolean result with the same shape as x of the NOT operation on elements of x.

See also

logical_and, logical_or, logical_xor

Examples

>>> np.logical_not(3)
False
>>> np.logical_not([True, False, 0, 1])
array([False,  True,  True, False], dtype=bool)

>>> x = np.arange(5)
>>> np.logical_not(x<3)
array([False, False, False,  True,  True], dtype=bool)


numpy.logical_xor

  • Logic functions
  • next
  • previous

Previous topic

numpy.logical_not

Next topic

numpy.allclose

numpy.logical_xor

numpy.logical_xor(x1, x2[, out]) = <ufunc 'logical_xor'>

Compute the truth value of x1 XOR x2, element-wise.

Parameters:

x1, x2 : array_like

Logical XOR is applied to the elements of x1 and x2. They must be broadcastable to the same shape.
Returns:

y : bool or ndarray of bool

Boolean result of the logical XOR operation applied to the elements of x1 and x2; the shape is determined by whether or not broadcasting of one or both arrays was required.

See also

logical_and, logical_or, logical_not, bitwise_xor

Examples

>>> np.logical_xor(True, False)
True
>>> np.logical_xor([True, True, False, False], [True, False, True, False])
array([False,  True,  True, False], dtype=bool)

>>> x = np.arange(5)
>>> np.logical_xor(x < 1, x > 3)
array([ True, False, False, False,  True], dtype=bool)

Simple example showing support of broadcasting

>>> np.logical_xor(0, np.eye(2))
array([[ True, False],
       [False,  True]], dtype=bool)


numpy.allclose

  • Logic functions
  • next
  • previous

Previous topic

numpy.logical_xor

Next topic

numpy.isclose

numpy.allclose

numpy.allclose(a, b, rtol=1e-05, atol=1e-08) [source]

Returns True if two arrays are element-wise equal within a tolerance.

The tolerance values are positive, typically very small numbers. The relative difference (rtol * abs(b)) and the absolute difference atol are added together to compare against the absolute difference between a and b.

If either array contains one or more NaNs, False is returned. Infs are treated as equal if they are in the same place and of the same sign in both arrays.

Parameters:

a, b : array_like

Input arrays to compare.

rtol : float

The relative tolerance parameter (see Notes).

atol : float

The absolute tolerance parameter (see Notes).
Returns:

allclose : bool

Returns True if the two arrays are equal within the given tolerance; False otherwise.

See also

isclose, all, any

Notes

If the following equation is element-wise True, then allclose returns True.

absolute(a - b) <= (atol + rtol * absolute(b))

The above equation is not symmetric in a and b, so that allclose(a, b) might be different from allclose(b, a) in some rare cases.

Examples

>>> np.allclose([1e10,1e-7], [1.00001e10,1e-8])
False
>>> np.allclose([1e10,1e-8], [1.00001e10,1e-9])
True
>>> np.allclose([1e10,1e-8], [1.0001e10,1e-9])
False
>>> np.allclose([1.0, np.nan], [1.0, np.nan])
False


numpy.isclose

  • Logic functions
  • next
  • previous

Previous topic

numpy.allclose

Next topic

numpy.array_equal

numpy.isclose

numpy.isclose(a, b, rtol=1e-05, atol=1e-08, equal_nan=False) [source]

Returns a boolean array where two arrays are element-wise equal within a tolerance.

The tolerance values are positive, typically very small numbers. The relative difference (rtol * abs(b)) and the absolute difference atol are added together to compare against the absolute difference between a and b.

Parameters:

a, b : array_like

Input arrays to compare.

rtol : float

The relative tolerance parameter (see Notes).

atol : float

The absolute tolerance parameter (see Notes).

equal_nan : bool

Whether to compare NaN’s as equal. If True, NaN’s in a will be considered equal to NaN’s in b in the output array.
Returns:

y : array_like

Returns a boolean array of where a and b are equal within the given tolerance. If both a and b are scalars, returns a single boolean value.

See also

allclose

Notes

New in version 1.7.0.

For finite values, isclose uses the following equation to test whether two floating point values are equivalent.

absolute(a - b) <= (atol + rtol * absolute(b))

The above equation is not symmetric in a and b, so that isclose(a, b) might be different from isclose(b, a) in some rare cases.

Examples

>>> np.isclose([1e10,1e-7], [1.00001e10,1e-8])
array([True, False])
>>> np.isclose([1e10,1e-8], [1.00001e10,1e-9])
array([True, True])
>>> np.isclose([1e10,1e-8], [1.0001e10,1e-9])
array([False, True])
>>> np.isclose([1.0, np.nan], [1.0, np.nan])
array([True, False])
>>> np.isclose([1.0, np.nan], [1.0, np.nan], equal_nan=True)
array([True, True])


numpy.array_equal

  • Logic functions
  • next
  • previous

Previous topic

numpy.isclose

Next topic

numpy.array_equiv

numpy.array_equal

numpy.array_equal(a1, a2) [source]

True if two arrays have the same shape and elements, False otherwise.

Parameters:

a1, a2 : array_like

Input arrays.
Returns:

b : bool

Returns True if the arrays are equal.

See also

allclose
Returns True if two arrays are element-wise equal within a tolerance.
array_equiv
Returns True if input arrays are shape consistent and all elements equal.

Examples

>>> np.array_equal([1, 2], [1, 2])
True
>>> np.array_equal(np.array([1, 2]), np.array([1, 2]))
True
>>> np.array_equal([1, 2], [1, 2, 3])
False
>>> np.array_equal([1, 2], [1, 4])
False


numpy.array_equiv

  • Logic functions
  • next
  • previous

Previous topic

numpy.array_equal

Next topic

numpy.greater

numpy.array_equiv

numpy.array_equiv(a1, a2) [source]

Returns True if input arrays are shape consistent and all elements equal.

Shape consistent means they are either the same shape, or one input array can be broadcasted to create the same shape as the other one.

Parameters:

a1, a2 : array_like

Input arrays.
Returns:

out : bool

True if equivalent, False otherwise.

Examples

>>> np.array_equiv([1, 2], [1, 2])
True
>>> np.array_equiv([1, 2], [1, 3])
False

Showing the shape equivalence:

>>> np.array_equiv([1, 2], [[1, 2], [1, 2]])
True
>>> np.array_equiv([1, 2], [[1, 2, 1, 2], [1, 2, 1, 2]])
False

>>> np.array_equiv([1, 2], [[1, 2], [1, 3]])
False


numpy.greater

  • Logic functions
  • next
  • previous

Previous topic

numpy.array_equiv

Next topic

numpy.greater_equal

numpy.greater

numpy.greater(x1, x2[, out]) = <ufunc 'greater'>

Return the truth value of (x1 > x2) element-wise.

Parameters:

x1, x2 : array_like

Input arrays. If x1.shape != x2.shape, they must be broadcastable to a common shape (which may be the shape of one or the other).
Returns:

out : bool or ndarray of bool

Array of bools, or a single bool if x1 and x2 are scalars.

See also

greater_equal, less, less_equal, equal, not_equal

Examples

>>> np.greater([4,2],[2,2])
array([ True, False], dtype=bool)

If the inputs are ndarrays, then np.greater is equivalent to ‘>’.

>>> a = np.array([4,2])
>>> b = np.array([2,2])
>>> a > b
array([ True, False], dtype=bool)


numpy.greater_equal

  • Logic functions
  • next
  • previous

Previous topic

numpy.greater

Next topic

numpy.less

numpy.greater_equal

numpy.greater_equal(x1, x2[, out]) = <ufunc 'greater_equal'>

Return the truth value of (x1 >= x2) element-wise.

Parameters:

x1, x2 : array_like

Input arrays. If x1.shape != x2.shape, they must be broadcastable to a common shape (which may be the shape of one or the other).
Returns:

out : bool or ndarray of bool

Array of bools, or a single bool if x1 and x2 are scalars.

See also

greater, less, less_equal, equal, not_equal

Examples

>>> np.greater_equal([4, 2, 1], [2, 2, 2])
array([ True, True, False], dtype=bool)


numpy.less

  • Logic functions
  • next
  • previous

Previous topic

numpy.greater_equal

Next topic

numpy.less_equal

numpy.less

numpy.less(x1, x2[, out]) = <ufunc 'less'>

Return the truth value of (x1 < x2) element-wise.

Parameters:

x1, x2 : array_like

Input arrays. If x1.shape != x2.shape, they must be broadcastable to a common shape (which may be the shape of one or the other).
Returns:

out : bool or ndarray of bool

Array of bools, or a single bool if x1 and x2 are scalars.

See also

greater, less_equal, greater_equal, equal, not_equal

Examples

>>> np.less([1, 2], [2, 2])
array([ True, False], dtype=bool)


numpy.less_equal

  • Logic functions
  • next
  • previous

Previous topic

numpy.less

Next topic

numpy.equal

numpy.less_equal

numpy.less_equal(x1, x2[, out]) = <ufunc 'less_equal'>

Return the truth value of (x1 =< x2) element-wise.

Parameters:

x1, x2 : array_like

Input arrays. If x1.shape != x2.shape, they must be broadcastable to a common shape (which may be the shape of one or the other).
Returns:

out : bool or ndarray of bool

Array of bools, or a single bool if x1 and x2 are scalars.

See also

greater, less, greater_equal, equal, not_equal

Examples

>>> np.less_equal([4, 2, 1], [2, 2, 2])
array([False,  True,  True], dtype=bool)


numpy.equal

  • Logic functions
  • next
  • previous

Previous topic

numpy.less_equal

Next topic

numpy.not_equal

numpy.equal

numpy.equal(x1, x2[, out]) = <ufunc 'equal'>

Return (x1 == x2) element-wise.

Parameters:

x1, x2 : array_like

Input arrays of the same shape.
Returns:

out : {ndarray, bool}

Output array of bools, or a single bool if x1 and x2 are scalars.

See also

not_equal, greater_equal, less_equal, greater, less

Examples

>>> np.equal([0, 1, 3], np.arange(3))
array([ True,  True, False], dtype=bool)

What is compared are values, not types. So an int (1) and an array of length one can evaluate as True:

>>> np.equal(1, np.ones(1))
array([ True], dtype=bool)


numpy.not_equal

  • Logic functions
  • next
  • previous

Previous topic

numpy.equal

Next topic

Masked array operations

numpy.not_equal

numpy.not_equal(x1, x2[, out]) = <ufunc 'not_equal'>

Return (x1 != x2) element-wise.

Parameters:

x1, x2 : array_like

Input arrays.

out : ndarray, optional

A placeholder the same shape as x1 to store the result. See doc.ufuncs (Section “Output arguments”) for more details.
Returns:

not_equal : ndarray bool, scalar bool

For each element in x1, x2, return True if x1 is not equal to x2 and False otherwise.

See also

equal, greater, greater_equal, less, less_equal

Examples

>>> np.not_equal([1.,2.], [1., 3.])
array([False,  True], dtype=bool)
>>> np.not_equal([1, 2], [[1, 3],[1, 4]])
array([[False,  True],
       [False,  True]], dtype=bool)


Mathematical functions

  • next
  • previous

Table Of Contents

  • Mathematical functions
    • Trigonometric functions
    • Hyperbolic functions
    • Rounding
    • Sums, products, differences
    • Exponents and logarithms
    • Other special functions
    • Floating point routines
    • Arithmetic operations
    • Handling complex numbers
    • Miscellaneous

Previous topic

numpy.ma.where

Next topic

numpy.sin

Mathematical functions

Trigonometric functions

sin(x[, out]) | Trigonometric sine, element-wise.
cos(x[, out]) | Cosine element-wise.
tan(x[, out]) | Compute tangent element-wise.
arcsin(x[, out]) | Inverse sine, element-wise.
arccos(x[, out]) | Trigonometric inverse cosine, element-wise.
arctan(x[, out]) | Trigonometric inverse tangent, element-wise.
hypot(x1, x2[, out]) | Given the “legs” of a right triangle, return its hypotenuse.
arctan2(x1, x2[, out]) | Element-wise arc tangent of x1/x2 choosing the quadrant correctly.
degrees(x[, out]) | Convert angles from radians to degrees.
radians(x[, out]) | Convert angles from degrees to radians.
unwrap(p[, discont, axis]) | Unwrap by changing deltas between values to 2*pi complement.
deg2rad(x[, out]) | Convert angles from degrees to radians.
rad2deg(x[, out]) | Convert angles from radians to degrees.

Hyperbolic functions

sinh(x[, out]) | Hyperbolic sine, element-wise.
cosh(x[, out]) | Hyperbolic cosine, element-wise.
tanh(x[, out]) | Compute hyperbolic tangent element-wise.
arcsinh(x[, out]) | Inverse hyperbolic sine element-wise.
arccosh(x[, out]) | Inverse hyperbolic cosine, element-wise.
arctanh(x[, out]) | Inverse hyperbolic tangent element-wise.

Rounding

around(a[, decimals, out]) | Evenly round to the given number of decimals.
round_(a[, decimals, out]) | Round an array to the given number of decimals.
rint(x[, out]) | Round elements of the array to the nearest integer.
fix(x[, y]) | Round to nearest integer towards zero.
floor(x[, out]) | Return the floor of the input, element-wise.
ceil(x[, out]) | Return the ceiling of the input, element-wise.
trunc(x[, out]) | Return the truncated value of the input, element-wise.

Sums, products, differences

prod(a[, axis, dtype, out, keepdims]) | Return the product of array elements over a given axis.
sum(a[, axis, dtype, out, keepdims]) | Sum of array elements over a given axis.
nansum(a[, axis, dtype, out, keepdims]) | Return the sum of array elements over a given axis treating Not a Numbers (NaNs) as zero.
cumprod(a[, axis, dtype, out]) | Return the cumulative product of elements along a given axis.
cumsum(a[, axis, dtype, out]) | Return the cumulative sum of the elements along a given axis.
diff(a[, n, axis]) | Calculate the n-th order discrete difference along given axis.
ediff1d(ary[, to_end, to_begin]) | The differences between consecutive elements of an array.
gradient(f, *varargs) | Return the gradient of an N-dimensional array.
cross(a, b[, axisa, axisb, axisc, axis]) | Return the cross product of two (arrays of) vectors.
trapz(y[, x, dx, axis]) | Integrate along the given axis using the composite trapezoidal rule.

Exponents and logarithms

exp(x[, out]) | Calculate the exponential of all elements in the input array.
expm1(x[, out]) | Calculate exp(x) - 1 for all elements in the array.
exp2(x[, out]) | Calculate 2**p for all p in the input array.
log(x[, out]) | Natural logarithm, element-wise.
log10(x[, out]) | Return the base 10 logarithm of the input array, element-wise.
log2(x[, out]) | Base-2 logarithm of x.
log1p(x[, out]) | Return the natural logarithm of one plus the input array, element-wise.
logaddexp(x1, x2[, out]) | Logarithm of the sum of exponentiations of the inputs.
logaddexp2(x1, x2[, out]) | Logarithm of the sum of exponentiations of the inputs in base-2.

Other special functions

i0(x) | Modified Bessel function of the first kind, order 0.
sinc(x) | Return the sinc function.

Floating point routines

signbit(x[, out]) | Returns element-wise True where signbit is set (less than zero).
copysign(x1, x2[, out]) | Change the sign of x1 to that of x2, element-wise.
frexp(x[, out1, out2]) | Decompose the elements of x into mantissa and twos exponent.
ldexp(x1, x2[, out]) | Returns x1 * 2**x2, element-wise.

Arithmetic operations

add(x1, x2[, out]) | Add arguments element-wise.
reciprocal(x[, out]) | Return the reciprocal of the argument, element-wise.
negative(x[, out]) | Numerical negative, element-wise.
multiply(x1, x2[, out]) | Multiply arguments element-wise.
divide(x1, x2[, out]) | Divide arguments element-wise.
power(x1, x2[, out]) | First array elements raised to powers from second array, element-wise.
subtract(x1, x2[, out]) | Subtract arguments, element-wise.
true_divide(x1, x2[, out]) | Returns a true division of the inputs, element-wise.
floor_divide(x1, x2[, out]) | Return the largest integer smaller or equal to the division of the inputs.
fmod(x1, x2[, out]) | Return the element-wise remainder of division.
mod(x1, x2[, out]) | Return element-wise remainder of division.
modf(x[, out1, out2]) | Return the fractional and integral parts of an array, element-wise.
remainder(x1, x2[, out]) | Return element-wise remainder of division.

Handling complex numbers

angle(z[, deg]) | Return the angle of the complex argument.
real(val) | Return the real part of the elements of the array.
imag(val) | Return the imaginary part of the elements of the array.
conj(x[, out]) | Return the complex conjugate, element-wise.

Miscellaneous

convolve(a, v[, mode]) | Returns the discrete, linear convolution of two one-dimensional sequences.
clip(a, a_min, a_max[, out]) | Clip (limit) the values in an array.
sqrt(x[, out]) | Return the positive square-root of an array, element-wise.
square(x[, out]) | Return the element-wise square of the input.
absolute(x[, out]) | Calculate the absolute value element-wise.
fabs(x[, out]) | Compute the absolute values element-wise.
sign(x[, out]) | Returns an element-wise indication of the sign of a number.
maximum(x1, x2[, out]) | Element-wise maximum of array elements.
minimum(x1, x2[, out]) | Element-wise minimum of array elements.
fmax(x1, x2[, out]) | Element-wise maximum of array elements.
fmin(x1, x2[, out]) | Element-wise minimum of array elements.
nan_to_num(x) | Replace nan with zero and inf with finite numbers.
real_if_close(a[, tol]) | If complex input returns a real array if complex parts are close to zero.
interp(x, xp, fp[, left, right]) | One-dimensional linear interpolation.


numpy.sin

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.interp

Next topic

numpy.cos

numpy.sin

numpy.sin(x[, out]) = <ufunc 'sin'>

Trigonometric sine, element-wise.

Parameters:

x : array_like

Angle, in radians ( [image] rad equals 360 degrees).
Returns:

y : array_like

The sine of each element of x.

See also

arcsin, sinh, cos

Notes

The sine is one of the fundamental functions of trigonometry (the mathematical study of triangles). Consider a circle of radius 1 centered on the origin. A ray comes in from the +x axis, makes an angle at the origin (measured counter-clockwise from that axis), and departs from the origin. The y coordinate of the outgoing ray’s intersection with the unit circle is the sine of that angle. It ranges from -1 for [image] to +1 for [image] The function has zeroes where the angle is a multiple of [image]. Sines of angles between [image] and [image] are negative. The numerous properties of the sine and related functions are included in any standard trigonometry text.

Examples

Print sine of one angle:

>>> np.sin(np.pi/2.)
1.0

Print sines of an array of angles given in degrees:

>>> np.sin(np.array((0., 30., 45., 60., 90.)) * np.pi / 180. )
array([ 0.        ,  0.5       ,  0.70710678,  0.8660254 ,  1.        ])

Plot the sine function:

>>> import matplotlib.pylab as plt
>>> x = np.linspace(-np.pi, np.pi, 201)
>>> plt.plot(x, np.sin(x))
>>> plt.xlabel('Angle [rad]')
>>> plt.ylabel('sin(x)')
>>> plt.axis('tight')
>>> plt.show()

(Source code, png, pdf)


numpy.cos

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.sin

Next topic

numpy.tan

numpy.cos

numpy.cos(x[, out]) = <ufunc 'cos'>

Cosine element-wise.

Parameters:

x : array_like

Input array in radians.

out : ndarray, optional

Output array of same shape as x.
Returns:

y : ndarray

The corresponding cosine values.
Raises:

ValueError: invalid return array shape

if out is provided and out.shape != x.shape (See Examples)

Notes

If out is provided, the function writes the result into it, and returns a reference to out. (See Examples)

References

M. Abramowitz and I. A. Stegun, Handbook of Mathematical Functions. New York, NY: Dover, 1972.

Examples

>>> np.cos(np.array([0, np.pi/2, np.pi]))
array([  1.00000000e+00,   6.12303177e-17,  -1.00000000e+00])
>>>
>>> # Example of providing the optional output parameter
>>> out2 = np.cos([0.1], out1)
>>> out2 is out1
True
>>>
>>> # Example of ValueError due to provision of shape mis-matched `out`
>>> np.cos(np.zeros((3,3)),np.zeros((2,2)))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: invalid return array shape


numpy.tan

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.cos

Next topic

numpy.arcsin

numpy.tan

numpy.tan(x[, out]) = <ufunc 'tan'>

Compute tangent element-wise.

Equivalent to np.sin(x)/np.cos(x) element-wise.

Parameters:

x : array_like

Input array.

out : ndarray, optional

Output array of same shape as x.
Returns:

y : ndarray

The corresponding tangent values.
Raises:

ValueError: invalid return array shape

if out is provided and out.shape != x.shape (See Examples)

Notes

If out is provided, the function writes the result into it, and returns a reference to out. (See Examples)

References

M. Abramowitz and I. A. Stegun, Handbook of Mathematical Functions. New York, NY: Dover, 1972.

Examples

>>> from math import pi
>>> np.tan(np.array([-pi,pi/2,pi]))
array([  1.22460635e-16,   1.63317787e+16,  -1.22460635e-16])
>>>
>>> # Example of providing the optional output parameter illustrating
>>> # that what is returned is a reference to said parameter
>>> out2 = np.cos([0.1], out1)
>>> out2 is out1
True
>>>
>>> # Example of ValueError due to provision of shape mis-matched `out`
>>> np.cos(np.zeros((3,3)),np.zeros((2,2)))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: invalid return array shape


numpy.arcsin

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.tan

Next topic

numpy.arccos

numpy.arcsin

numpy.arcsin(x[, out]) = <ufunc 'arcsin'>

Inverse sine, element-wise.

Parameters:

x : array_like

y-coordinate on the unit circle.

out : ndarray, optional

Array of the same shape as x, in which to store the results. See doc.ufuncs (Section “Output arguments”) for more details.
Returns:

angle : ndarray

The inverse sine of each element in x, in radians and in the closed interval [-pi/2, pi/2]. If x is a scalar, a scalar is returned, otherwise an array.

See also

sin, cos, arccos, tan, arctan, arctan2, emath.arcsin

Notes

arcsin is a multivalued function: for each x there are infinitely many numbers z such that sin(z) = x. The convention is to return the angle z whose real part lies in [-pi/2, pi/2].

For real-valued input data types, arcsin always returns real output. For each value that cannot be expressed as a real number or infinity, it yields nan and sets the invalid floating point error flag.

For complex-valued input, arcsin is a complex analytic function that has, by convention, the branch cuts [-inf, -1] and [1, inf] and is continuous from above on the former and from below on the latter.

The inverse sine is also known as asin or sin^{-1}.

References

Abramowitz, M. and Stegun, I. A., Handbook of Mathematical Functions, 10th printing, New York: Dover, 1964, pp. 79ff. http://www.math.sfu.ca/~cbm/aands/

Examples

>>> np.arcsin(1)     # pi/2
1.5707963267948966
>>> np.arcsin(-1)    # -pi/2
-1.5707963267948966
>>> np.arcsin(0)
0.0


numpy.arccos

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.arcsin

Next topic

numpy.arctan

numpy.arccos

numpy.arccos(x[, out]) = <ufunc 'arccos'>

Trigonometric inverse cosine, element-wise.

The inverse of cos so that, if y = cos(x), then x = arccos(y).

Parameters:

x : array_like

x-coordinate on the unit circle. For real arguments, the domain is [-1, 1].

out : ndarray, optional

Array of the same shape as a, to store results in. See doc.ufuncs (Section “Output arguments”) for more details.
Returns:

angle : ndarray

The angle of the ray intersecting the unit circle at the given x-coordinate in radians [0, pi]. If x is a scalar then a scalar is returned, otherwise an array of the same shape as x is returned.

See also

cos, arctan, arcsin, emath.arccos

Notes

arccos is a multivalued function: for each x there are infinitely many numbers z such that cos(z) = x. The convention is to return the angle z whose real part lies in [0, pi].

For real-valued input data types, arccos always returns real output. For each value that cannot be expressed as a real number or infinity, it yields nan and sets the invalid floating point error flag.

For complex-valued input, arccos is a complex analytic function that has branch cuts [-inf, -1] and [1, inf] and is continuous from above on the former and from below on the latter.

The inverse cos is also known as acos or cos^-1.

References

M. Abramowitz and I.A. Stegun, “Handbook of Mathematical Functions”, 10th printing, 1964, pp. 79. http://www.math.sfu.ca/~cbm/aands/

Examples

We expect the arccos of 1 to be 0, and of -1 to be pi:

>>> np.arccos([1, -1])
array([ 0.        ,  3.14159265])

Plot arccos:

>>> import matplotlib.pyplot as plt
>>> x = np.linspace(-1, 1, num=100)
>>> plt.plot(x, np.arccos(x))
>>> plt.axis('tight')
>>> plt.show()

(Source code, png, pdf)


numpy.arctan

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.arccos

Next topic

numpy.hypot

numpy.arctan

numpy.arctan(x[, out]) = <ufunc 'arctan'>

Trigonometric inverse tangent, element-wise.

The inverse of tan, so that if y = tan(x) then x = arctan(y).

Parameters:

x : array_like

Input values. arctan is applied to each element of x.
Returns:

out : ndarray

Out has the same shape as x. Its real part is in [-pi/2, pi/2] (arctan(+/-inf) returns +/-pi/2). It is a scalar if x is a scalar.

See also

arctan2
The “four quadrant” arctan of the angle formed by (x, y) and the positive x-axis.
angle
Argument of complex values.

Notes

arctan is a multi-valued function: for each x there are infinitely many numbers z such that tan(z) = x. The convention is to return the angle z whose real part lies in [-pi/2, pi/2].

For real-valued input data types, arctan always returns real output. For each value that cannot be expressed as a real number or infinity, it yields nan and sets the invalid floating point error flag.

For complex-valued input, arctan is a complex analytic function that has [1j, infj] and [-1j, -infj] as branch cuts, and is continuous from the left on the former and from the right on the latter.

The inverse tangent is also known as atan or tan^{-1}.

References

Abramowitz, M. and Stegun, I. A., Handbook of Mathematical Functions, 10th printing, New York: Dover, 1964, pp. 79. http://www.math.sfu.ca/~cbm/aands/

Examples

We expect the arctan of 0 to be 0, and of 1 to be pi/4:

>>> np.arctan([0, 1])
array([ 0.        ,  0.78539816])

>>> np.pi/4
0.78539816339744828

Plot arctan:

>>> import matplotlib.pyplot as plt
>>> x = np.linspace(-10, 10)
>>> plt.plot(x, np.arctan(x))
>>> plt.axis('tight')
>>> plt.show()

(Source code, png, pdf)


numpy.hypot

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.arctan

Next topic

numpy.arctan2

numpy.hypot

numpy.hypot(x1, x2[, out]) = <ufunc 'hypot'>

Given the “legs” of a right triangle, return its hypotenuse.

Equivalent to sqrt(x1**2 + x2**2), element-wise. If x1 or x2 is scalar_like (i.e., unambiguously cast-able to a scalar type), it is broadcast for use with each element of the other argument. (See Examples)

Parameters:

x1, x2 : array_like

Leg of the triangle(s).

out : ndarray, optional

Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output. See doc.ufuncs.
Returns:

z : ndarray

The hypotenuse of the triangle(s).

Examples

>>> np.hypot(3*np.ones((3, 3)), 4*np.ones((3, 3)))
array([[ 5.,  5.,  5.],
       [ 5.,  5.,  5.],
       [ 5.,  5.,  5.]])

Example showing broadcast of scalar_like argument:

>>> np.hypot(3*np.ones((3, 3)), [4])
array([[ 5.,  5.,  5.],
       [ 5.,  5.,  5.],
       [ 5.,  5.,  5.]])


numpy.arctan2

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.hypot

Next topic

numpy.degrees

numpy.arctan2

numpy.arctan2(x1, x2[, out]) = <ufunc 'arctan2'>

Element-wise arc tangent of x1/x2 choosing the quadrant correctly.

The quadrant (i.e., branch) is chosen so that arctan2(x1, x2) is the signed angle in radians between the ray ending at the origin and passing through the point (1,0), and the ray ending at the origin and passing through the point (x2, x1). (Note the role reversal: the “y-coordinate” is the first function parameter, the “x-coordinate” is the second.) By IEEE convention, this function is defined for x2 = +/-0 and for either or both of x1 and x2 = +/-inf (see Notes for specific values).

This function is not defined for complex-valued arguments; for the so-called argument of complex values, use angle.

Parameters:

x1 : array_like, real-valued

y-coordinates.

x2 : array_like, real-valued

x-coordinates. x2 must be broadcastable to match the shape of x1 or vice versa.
Returns:

angle : ndarray

Array of angles in radians, in the range [-pi, pi].

See also

arctan, tan, angle

Notes

arctan2 is identical to the atan2 function of the underlying C library. The following special values are defined in the C standard: [R6]

x1 | x2 | arctan2(x1,x2)
+/- 0 | +0 | +/- 0
+/- 0 | -0 | +/- pi
> 0 | +/-inf | +0 / +pi
< 0 | +/-inf | -0 / -pi
+/-inf | +inf | +/- (pi/4)
+/-inf | -inf | +/- (3*pi/4)

Note that +0 and -0 are distinct floating point numbers, as are +inf and -inf.

References

[R6] (1, 2) ISO/IEC standard 9899:1999, “Programming language C.”

Examples

Consider four points in different quadrants:

>>> x = np.array([-1, +1, +1, -1])
>>> y = np.array([-1, -1, +1, +1])
>>> np.arctan2(y, x) * 180 / np.pi
array([-135.,  -45.,   45.,  135.])

Note the order of the parameters. arctan2 is defined also when x2 = 0 and at several other special points, obtaining values in the range [-pi, pi]:

>>> np.arctan2([1., -1.], [0., 0.])
array([ 1.57079633, -1.57079633])
>>> np.arctan2([0., 0., np.inf], [+0., -0., np.inf])
array([ 0.        ,  3.14159265,  0.78539816])


numpy.degrees

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.arctan2

Next topic

numpy.radians

numpy.degrees

numpy.degrees(x[, out]) = <ufunc 'degrees'>

Convert angles from radians to degrees.

Parameters:

x : array_like

Input array in radians.

out : ndarray, optional

Output array of same shape as x.
Returns:

y : ndarray of floats

The corresponding degree values; if out was supplied this is a reference to it.

See also

rad2deg
equivalent function

Examples

Convert a radian array to degrees

>>> rad = np.arange(12.)*np.pi/6
>>> np.degrees(rad)
array([   0.,   30.,   60.,   90.,  120.,  150.,  180.,  210.,  240.,
        270.,  300.,  330.])

>>> out = np.zeros((rad.shape))
>>> r = degrees(rad, out)
>>> np.all(r == out)
True


numpy.radians

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.degrees

Next topic

numpy.unwrap

numpy.radians

numpy.radians(x[, out]) = <ufunc 'radians'>

Convert angles from degrees to radians.

Parameters:

x : array_like

Input array in degrees.

out : ndarray, optional

Output array of same shape as x.
Returns:

y : ndarray

The corresponding radian values.

See also

deg2rad
equivalent function

Examples

Convert a degree array to radians

>>> deg = np.arange(12.) * 30.
>>> np.radians(deg)
array([ 0.        ,  0.52359878,  1.04719755,  1.57079633,  2.0943951 ,
        2.61799388,  3.14159265,  3.66519143,  4.1887902 ,  4.71238898,
        5.23598776,  5.75958653])

>>> out = np.zeros((deg.shape))
>>> ret = np.radians(deg, out)
>>> ret is out
True


numpy.unwrap

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.radians

Next topic

numpy.deg2rad

numpy.unwrap

numpy.unwrap(p, discont=3.141592653589793, axis=-1) [source]

Unwrap by changing deltas between values to 2*pi complement.

Unwrap radian phase p by changing absolute jumps greater than discont to their 2*pi complement along the given axis.

Parameters:

p : array_like

Input array.

discont : float, optional

Maximum discontinuity between values, default is pi.

axis : int, optional

Axis along which unwrap will operate, default is the last axis.
Returns:

out : ndarray

Output array.

See also

rad2deg, deg2rad

Notes

If the discontinuity in p is smaller than pi, but larger than discont, no unwrapping is done because taking the 2*pi complement would only make the discontinuity larger.

Examples

>>> phase = np.linspace(0, np.pi, num=5)
>>> phase[3:] += np.pi
>>> phase
array([ 0.        ,  0.78539816,  1.57079633,  5.49778714,  6.28318531])
>>> np.unwrap(phase)
array([ 0.        ,  0.78539816,  1.57079633, -0.78539816,  0.        ])


numpy.deg2rad

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.unwrap

Next topic

numpy.rad2deg

numpy.deg2rad

numpy.deg2rad(x[, out]) = <ufunc 'deg2rad'>

Convert angles from degrees to radians.

Parameters:

x : array_like

Angles in degrees.
Returns:

y : ndarray

The corresponding angle in radians.

See also

rad2deg
Convert angles from radians to degrees.
unwrap
Remove large jumps in angle by wrapping.

Notes

New in version 1.3.0.

deg2rad(x) is x * pi / 180.

Examples

>>> np.deg2rad(180)
3.1415926535897931


numpy.rad2deg

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.deg2rad

Next topic

numpy.sinh

numpy.rad2deg

numpy.rad2deg(x[, out]) = <ufunc 'rad2deg'>

Convert angles from radians to degrees.

Parameters:

x : array_like

Angle in radians.

out : ndarray, optional

Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output. See doc.ufuncs.
Returns:

y : ndarray

The corresponding angle in degrees.

See also

deg2rad
Convert angles from degrees to radians.
unwrap
Remove large jumps in angle by wrapping.

Notes

New in version 1.3.0.

rad2deg(x) is 180 * x / pi.

Examples

>>> np.rad2deg(np.pi/2)
90.0


numpy.sinh

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.rad2deg

Next topic

numpy.cosh

numpy.sinh

numpy.sinh(x[, out]) = <ufunc 'sinh'>

Hyperbolic sine, element-wise.

Equivalent to 1/2 * (np.exp(x) - np.exp(-x)) or -1j * np.sin(1j*x).

Parameters:

x : array_like

Input array.

out : ndarray, optional

Output array of same shape as x.
Returns:

y : ndarray

The corresponding hyperbolic sine values.
Raises:

ValueError: invalid return array shape

if out is provided and out.shape != x.shape (See Examples)

Notes

If out is provided, the function writes the result into it, and returns a reference to out. (See Examples)

References

M. Abramowitz and I. A. Stegun, Handbook of Mathematical Functions. New York, NY: Dover, 1972, pg. 83.

Examples

>>> np.sinh(0)
0.0
>>> np.sinh(np.pi*1j/2)
1j
>>> np.sinh(np.pi*1j) # (exact value is 0)
1.2246063538223773e-016j
>>> # Discrepancy due to vagaries of floating point arithmetic.

>>> # Example of providing the optional output parameter
>>> out2 = np.sinh([0.1], out1)
>>> out2 is out1
True

>>> # Example of ValueError due to provision of shape mis-matched `out`
>>> np.sinh(np.zeros((3,3)),np.zeros((2,2)))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: invalid return array shape


numpy.cosh

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.sinh

Next topic

numpy.tanh

numpy.cosh

numpy.cosh(x[, out]) = <ufunc 'cosh'>

Hyperbolic cosine, element-wise.

Equivalent to 1/2 * (np.exp(x) + np.exp(-x)) and np.cos(1j*x).

Parameters:

x : array_like

Input array.
Returns:

out : ndarray

Output array of same shape as x.

Examples

>>> np.cosh(0)
1.0

The hyperbolic cosine describes the shape of a hanging cable:

>>> import matplotlib.pyplot as plt
>>> x = np.linspace(-4, 4, 1000)
>>> plt.plot(x, np.cosh(x))
>>> plt.show()

(Source code, png, pdf)


numpy.tanh

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.cosh

Next topic

numpy.arcsinh

numpy.tanh

numpy.tanh(x[, out]) = <ufunc 'tanh'>

Compute hyperbolic tangent element-wise.

Equivalent to np.sinh(x)/np.cosh(x) or -1j * np.tan(1j*x).

Parameters:

x : array_like

Input array.

out : ndarray, optional

Output array of same shape as x.
Returns:

y : ndarray

The corresponding hyperbolic tangent values.
Raises:

ValueError: invalid return array shape

if out is provided and out.shape != x.shape (See Examples)

Notes

If out is provided, the function writes the result into it, and returns a reference to out. (See Examples)

References

[R248] M. Abramowitz and I. A. Stegun, Handbook of Mathematical Functions. New York, NY: Dover, 1972, pg. 83. http://www.math.sfu.ca/~cbm/aands/
[R249] Wikipedia, “Hyperbolic function”, http://en.wikipedia.org/wiki/Hyperbolic_function

Examples

>>> np.tanh((0, np.pi*1j, np.pi*1j/2))
array([ 0. +0.00000000e+00j,  0. -1.22460635e-16j,  0. +1.63317787e+16j])

>>> # Example of providing the optional output parameter illustrating
>>> # that what is returned is a reference to said parameter
>>> out2 = np.tanh([0.1], out1)
>>> out2 is out1
True

>>> # Example of ValueError due to provision of shape mis-matched `out`
>>> np.tanh(np.zeros((3,3)),np.zeros((2,2)))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: invalid return array shape


numpy.arcsinh

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.tanh

Next topic

numpy.arccosh

numpy.arcsinh

numpy.arcsinh(x[, out]) = <ufunc 'arcsinh'>

Inverse hyperbolic sine element-wise.

Parameters:

x : array_like

Input array.

out : ndarray, optional

Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output. See doc.ufuncs.
Returns:

out : ndarray

Array of of the same shape as x.

Notes

arcsinh is a multivalued function: for each x there are infinitely many numbers z such that sinh(z) = x. The convention is to return the z whose imaginary part lies in [-pi/2, pi/2].

For real-valued input data types, arcsinh always returns real output. For each value that cannot be expressed as a real number or infinity, it returns nan and sets the invalid floating point error flag.

For complex-valued input, arccos is a complex analytical function that has branch cuts [1j, infj] and [-1j, -infj] and is continuous from the right on the former and from the left on the latter.

The inverse hyperbolic sine is also known as asinh or sinh^-1.

References

[R4] M. Abramowitz and I.A. Stegun, “Handbook of Mathematical Functions”, 10th printing, 1964, pp. 86. http://www.math.sfu.ca/~cbm/aands/
[R5] Wikipedia, “Inverse hyperbolic function”, http://en.wikipedia.org/wiki/Arcsinh

Examples

>>> np.arcsinh(np.array([np.e, 10.0]))
array([ 1.72538256,  2.99822295])


numpy.arccosh

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.arcsinh

Next topic

numpy.arctanh

numpy.arccosh

numpy.arccosh(x[, out]) = <ufunc 'arccosh'>

Inverse hyperbolic cosine, element-wise.

Parameters:

x : array_like

Input array.

out : ndarray, optional

Array of the same shape as x, to store results in. See doc.ufuncs (Section “Output arguments”) for details.
Returns:

arccosh : ndarray

Array of the same shape as x.

See also

cosh, arcsinh, sinh, arctanh, tanh

Notes

arccosh is a multivalued function: for each x there are infinitely many numbers z such that cosh(z) = x. The convention is to return the z whose imaginary part lies in [-pi, pi] and the real part in [0, inf].

For real-valued input data types, arccosh always returns real output. For each value that cannot be expressed as a real number or infinity, it yields nan and sets the invalid floating point error flag.

For complex-valued input, arccosh is a complex analytical function that has a branch cut [-inf, 1] and is continuous from above on it.

References

[R2] M. Abramowitz and I.A. Stegun, “Handbook of Mathematical Functions”, 10th printing, 1964, pp. 86. http://www.math.sfu.ca/~cbm/aands/
[R3] Wikipedia, “Inverse hyperbolic function”, http://en.wikipedia.org/wiki/Arccosh

Examples

>>> np.arccosh([np.e, 10.0])
array([ 1.65745445,  2.99322285])
>>> np.arccosh(1)
0.0


numpy.arctanh

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.arccosh

Next topic

numpy.around

numpy.arctanh

numpy.arctanh(x[, out]) = <ufunc 'arctanh'>

Inverse hyperbolic tangent element-wise.

Parameters:

x : array_like

Input array.
Returns:

out : ndarray

Array of the same shape as x.

See also

emath.arctanh

Notes

arctanh is a multivalued function: for each x there are infinitely many numbers z such that tanh(z) = x. The convention is to return the z whose imaginary part lies in [-pi/2, pi/2].

For real-valued input data types, arctanh always returns real output. For each value that cannot be expressed as a real number or infinity, it yields nan and sets the invalid floating point error flag.

For complex-valued input, arctanh is a complex analytical function that has branch cuts [-1, -inf] and [1, inf] and is continuous from above on the former and from below on the latter.

The inverse hyperbolic tangent is also known as atanh or tanh^-1.

References

[R7] M. Abramowitz and I.A. Stegun, “Handbook of Mathematical Functions”, 10th printing, 1964, pp. 86. http://www.math.sfu.ca/~cbm/aands/
[R8] Wikipedia, “Inverse hyperbolic function”, http://en.wikipedia.org/wiki/Arctanh

Examples

>>> np.arctanh([0, -0.5])
array([ 0.        , -0.54930614])


numpy.around

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.arctanh

Next topic

numpy.round

numpy.around

numpy.around(a, decimals=0, out=None) [source]

Evenly round to the given number of decimals.

Parameters:

a : array_like

Input data.

decimals : int, optional

Number of decimal places to round to (default: 0). If decimals is negative, it specifies the number of positions to the left of the decimal point.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape as the expected output, but the type of the output values will be cast if necessary. See doc.ufuncs (Section “Output arguments”) for details.
Returns:

rounded_array : ndarray

An array of the same type as a, containing the rounded values. Unless out was specified, a new array is created. A reference to the result is returned.

The real and imaginary parts of complex numbers are rounded separately. The result of rounding a float is a float.

See also

ndarray.round
equivalent method

ceil, fix, floor, rint, trunc

Notes

For values exactly halfway between rounded decimal values, Numpy rounds to the nearest even value. Thus 1.5 and 2.5 round to 2.0, -0.5 and 0.5 round to 0.0, etc. Results may also be surprising due to the inexact representation of decimal fractions in the IEEE floating point standard [R9] and errors introduced when scaling by powers of ten.

References

[R9] (1, 2) “Lecture Notes on the Status of IEEE 754”, William Kahan, http://www.cs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF
[R10] “How Futile are Mindless Assessments of Roundoff in Floating-Point Computation?”, William Kahan, http://www.cs.berkeley.edu/~wkahan/Mindless.pdf

Examples

>>> np.around([0.37, 1.64])
array([ 0.,  2.])
>>> np.around([0.37, 1.64], decimals=1)
array([ 0.4,  1.6])
>>> np.around([.5, 1.5, 2.5, 3.5, 4.5]) # rounds to nearest even value
array([ 0.,  2.,  2.,  4.,  4.])
>>> np.around([1,2,3,11], decimals=1) # ndarray of ints is returned
array([ 1,  2,  3, 11])
>>> np.around([1,2,3,11], decimals=-1)
array([ 0,  0,  0, 10])


numpy.round

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.around

Next topic

numpy.rint

numpy.round

numpy.round_(a, decimals=0, out=None) [source]

Round an array to the given number of decimals.

Refer to around for full documentation.

See also

around
equivalent function


numpy.rint

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.round

Next topic

numpy.fix

numpy.rint

numpy.rint(x[, out]) = <ufunc 'rint'>

Round elements of the array to the nearest integer.

Parameters:

x : array_like

Input array.
Returns:

out : {ndarray, scalar}

Output array is same shape and type as x.

See also

ceil, floor, trunc

Examples

>>> a = np.array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0])
>>> np.rint(a)
array([-2., -2., -0.,  0.,  2.,  2.,  2.])


numpy.fix

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.rint

Next topic

numpy.floor

numpy.fix

numpy.fix(x, y=None) [source]

Round to nearest integer towards zero.

Round an array of floats element-wise to nearest integer towards zero. The rounded values are returned as floats.

Parameters:

x : array_like

An array of floats to be rounded

y : ndarray, optional

Output array
Returns:

out : ndarray of floats

The array of rounded numbers

See also

trunc, floor, ceil

around
Round to given number of decimals

Examples

>>> np.fix(3.14)
3.0
>>> np.fix(3)
3.0
>>> np.fix([2.1, 2.9, -2.1, -2.9])
array([ 2.,  2., -2., -2.])


numpy.floor

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.fix

Next topic

numpy.ceil

numpy.floor

numpy.floor(x[, out]) = <ufunc 'floor'>

Return the floor of the input, element-wise.

The floor of the scalar x is the largest integer i, such that i <= x. It is often denoted as [image].

Parameters:

x : array_like

Input data.
Returns:

y : {ndarray, scalar}

The floor of each element in x.

See also

ceil, trunc, rint

Notes

Some spreadsheet programs calculate the “floor-towards-zero”, in other words floor(-2.5) == -2. NumPy instead uses the definition of floor where floor(-2.5) == -3.

Examples

>>> a = np.array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0])
>>> np.floor(a)
array([-2., -2., -1.,  0.,  1.,  1.,  2.])


numpy.ceil

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.floor

Next topic

numpy.trunc

numpy.ceil

numpy.ceil(x[, out]) = <ufunc 'ceil'>

Return the ceiling of the input, element-wise.

The ceil of the scalar x is the smallest integer i, such that i >= x. It is often denoted as [image].

Parameters:

x : array_like

Input data.
Returns:

y : {ndarray, scalar}

The ceiling of each element in x, with float dtype.

See also

floor, trunc, rint

Examples

>>> a = np.array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0])
>>> np.ceil(a)
array([-1., -1., -0.,  1.,  2.,  2.,  2.])


numpy.trunc

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.ceil

Next topic

numpy.prod

numpy.trunc

numpy.trunc(x[, out]) = <ufunc 'trunc'>

Return the truncated value of the input, element-wise.

The truncated value of the scalar x is the nearest integer i which is closer to zero than x is. In short, the fractional part of the signed number x is discarded.

Parameters:

x : array_like

Input data.
Returns:

y : {ndarray, scalar}

The truncated value of each element in x.

See also

ceil, floor, rint

Notes

New in version 1.3.0.

Examples

>>> a = np.array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0])
>>> np.trunc(a)
array([-1., -1., -0.,  0.,  1.,  1.,  2.])


numpy.prod

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.trunc

Next topic

numpy.sum

numpy.prod

numpy.prod(a, axis=None, dtype=None, out=None, keepdims=False) [source]

Return the product of array elements over a given axis.

Parameters:

a : array_like

Input data.

axis : None or int or tuple of ints, optional

Axis or axes along which a product is performed. The default (axis = None) is perform a product over all the dimensions of the input array. axis may be negative, in which case it counts from the last to the first axis.

New in version 1.7.0.

If this is a tuple of ints, a product is performed on multiple axes, instead of a single axis or all the axes as before.

dtype : data-type, optional

The data-type of the returned array, as well as of the accumulator in which the elements are multiplied. By default, if a is of integer type, dtype is the default platform integer. (Note: if the type of a is unsigned, then so is dtype.) Otherwise, the dtype is the same as that of a.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape as the expected output, but the type of the output values will be cast if necessary.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

product_along_axis : ndarray, see dtype parameter above.

An array shaped as a but with the specified axis removed. Returns a reference to out if specified.

See also

ndarray.prod
equivalent method
numpy.doc.ufuncs
Section “Output arguments”

Notes

Arithmetic is modular when using integer types, and no error is raised on overflow. That means that, on a 32-bit platform:

>>> x = np.array([536870910, 536870910, 536870910, 536870910])
>>> np.prod(x) #random
16

Examples

By default, calculate the product of all elements:

>>> np.prod([1.,2.])
2.0

Even when the input array is two-dimensional:

>>> np.prod([[1.,2.],[3.,4.]])
24.0

But we can also specify the axis over which to multiply:

>>> np.prod([[1.,2.],[3.,4.]], axis=1)
array([  2.,  12.])

If the type of x is unsigned, then the output type is the unsigned platform integer:

>>> x = np.array([1, 2, 3], dtype=np.uint8)
>>> np.prod(x).dtype == np.uint
True

If x is of a signed integer type, then the output type is the default platform integer:

>>> x = np.array([1, 2, 3], dtype=np.int8)
>>> np.prod(x).dtype == np.int
True


numpy.sum

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.prod

Next topic

numpy.nansum

numpy.sum

numpy.sum(a, axis=None, dtype=None, out=None, keepdims=False) [source]

Sum of array elements over a given axis.

Parameters:

a : array_like

Elements to sum.

axis : None or int or tuple of ints, optional

Axis or axes along which a sum is performed. The default (axis = None) is perform a sum over all the dimensions of the input array. axis may be negative, in which case it counts from the last to the first axis.

New in version 1.7.0.

If this is a tuple of ints, a sum is performed on multiple axes, instead of a single axis or all the axes as before.

dtype : dtype, optional

The type of the returned array and of the accumulator in which the elements are summed. By default, the dtype of a is used. An exception is when a has an integer type with less precision than the default platform integer. In that case, the default platform integer is used instead.

out : ndarray, optional

Array into which the output is placed. By default, a new array is created. If out is given, it must be of the appropriate shape (the shape of a with axis removed, i.e., numpy.delete(a.shape, axis)). Its type is preserved. See doc.ufuncs (Section “Output arguments”) for more details.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

sum_along_axis : ndarray

An array with the same shape as a, with the specified axis removed. If a is a 0-d array, or if axis is None, a scalar is returned. If an output array is specified, a reference to out is returned.

See also

ndarray.sum
Equivalent method.
cumsum
Cumulative sum of array elements.
trapz
Integration of array values using the composite trapezoidal rule.

mean, average

Notes

Arithmetic is modular when using integer types, and no error is raised on overflow.

Examples

>>> np.sum([0.5, 1.5])
2.0
>>> np.sum([0.5, 0.7, 0.2, 1.5], dtype=np.int32)
1
>>> np.sum([[0, 1], [0, 5]])
6
>>> np.sum([[0, 1], [0, 5]], axis=0)
array([0, 6])
>>> np.sum([[0, 1], [0, 5]], axis=1)
array([1, 5])

If the accumulator is too small, overflow occurs:

>>> np.ones(128, dtype=np.int8).sum(dtype=np.int8)
-128


numpy.nansum

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.sum

Next topic

numpy.cumprod

numpy.nansum

numpy.nansum(a, axis=None, dtype=None, out=None, keepdims=0) [source]

Return the sum of array elements over a given axis treating Not a Numbers (NaNs) as zero.

In Numpy versions <= 1.8 Nan is returned for slices that are all-NaN or empty. In later versions zero is returned.

Parameters:

a : array_like

Array containing numbers whose sum is desired. If a is not an array, a conversion is attempted.

axis : int, optional

Axis along which the sum is computed. The default is to compute the sum of the flattened array.

dtype : data-type, optional

The type of the returned array and of the accumulator in which the elements are summed. By default, the dtype of a is used. An exception is when a has an integer type with less precision than the platform (u)intp. In that case, the default will be either (u)int32 or (u)int64 depending on whether the platform is 32 or 64 bits. For inexact inputs, dtype must be inexact.

New in version 1.8.0.

out : ndarray, optional

Alternate output array in which to place the result. The default is None. If provided, it must have the same shape as the expected output, but the type will be cast if necessary. See doc.ufuncs for details. The casting of NaN to integer can yield unexpected results.

New in version 1.8.0.

keepdims : bool, optional

If True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.

New in version 1.8.0.
Returns:

y : ndarray or numpy scalar

See also

numpy.sum
Sum across array propagating NaNs.
isnan
Show which elements are NaN.
isfinite
Show which elements are not NaN or +/-inf.

Notes

If both positive and negative infinity are present, the sum will be Not A Number (NaN).

Numpy integer arithmetic is modular. If the size of a sum exceeds the size of an integer accumulator, its value will wrap around and the result will be incorrect. Specifying dtype=double can alleviate that problem.

Examples

>>> np.nansum(1)
1
>>> np.nansum([1])
1
>>> np.nansum([1, np.nan])
1.0
>>> a = np.array([[1, 1], [1, np.nan]])
>>> np.nansum(a)
3.0
>>> np.nansum(a, axis=0)
array([ 2.,  1.])
>>> np.nansum([1, np.nan, np.inf])
inf
>>> np.nansum([1, np.nan, np.NINF])
-inf
>>> np.nansum([1, np.nan, np.inf, -np.inf]) # both +/- infinity present
nan


numpy.cumprod

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.nansum

Next topic

numpy.cumsum

numpy.cumprod

numpy.cumprod(a, axis=None, dtype=None, out=None) [source]

Return the cumulative product of elements along a given axis.

Parameters:

a : array_like

Input array.

axis : int, optional

Axis along which the cumulative product is computed. By default the input is flattened.

dtype : dtype, optional

Type of the returned array, as well as of the accumulator in which the elements are multiplied. If dtype is not specified, it defaults to the dtype of a, unless a has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used instead.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type of the resulting values will be cast if necessary.
Returns:

cumprod : ndarray

A new array holding the result is returned unless out is specified, in which case a reference to out is returned.

See also

numpy.doc.ufuncs
Section “Output arguments”

Notes

Arithmetic is modular when using integer types, and no error is raised on overflow.

Examples

>>> a = np.array([1,2,3])
>>> np.cumprod(a) # intermediate results 1, 1*2
...               # total product 1*2*3 = 6
array([1, 2, 6])
>>> a = np.array([[1, 2, 3], [4, 5, 6]])
>>> np.cumprod(a, dtype=float) # specify type of output
array([   1.,    2.,    6.,   24.,  120.,  720.])

The cumulative product for each column (i.e., over the rows) of a:

>>> np.cumprod(a, axis=0)
array([[ 1,  2,  3],
       [ 4, 10, 18]])

The cumulative product for each row (i.e. over the columns) of a:

>>> np.cumprod(a,axis=1)
array([[  1,   2,   6],
       [  4,  20, 120]])


numpy.cumsum

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.cumprod

Next topic

numpy.diff

numpy.cumsum

numpy.cumsum(a, axis=None, dtype=None, out=None) [source]

Return the cumulative sum of the elements along a given axis.

Parameters:

a : array_like

Input array.

axis : int, optional

Axis along which the cumulative sum is computed. The default (None) is to compute the cumsum over the flattened array.

dtype : dtype, optional

Type of the returned array and of the accumulator in which the elements are summed. If dtype is not specified, it defaults to the dtype of a, unless a has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary. See doc.ufuncs (Section “Output arguments”) for more details.
Returns:

cumsum_along_axis : ndarray.

A new array holding the result is returned unless out is specified, in which case a reference to out is returned. The result has the same size as a, and the same shape as a if axis is not None or a is a 1-d array.

See also

sum
Sum array elements.
trapz
Integration of array values using the composite trapezoidal rule.
diff
Calculate the n-th order discrete difference along given axis.

Notes

Arithmetic is modular when using integer types, and no error is raised on overflow.

Examples

>>> a = np.array([[1,2,3], [4,5,6]])
>>> a
array([[1, 2, 3],
       [4, 5, 6]])
>>> np.cumsum(a)
array([ 1,  3,  6, 10, 15, 21])
>>> np.cumsum(a, dtype=float)     # specifies type of output value(s)
array([  1.,   3.,   6.,  10.,  15.,  21.])

>>> np.cumsum(a,axis=0)      # sum over rows for each of the 3 columns
array([[1, 2, 3],
       [5, 7, 9]])
>>> np.cumsum(a,axis=1)      # sum over columns for each of the 2 rows
array([[ 1,  3,  6],
       [ 4,  9, 15]])


numpy.diff

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.cumsum

Next topic

numpy.ediff1d

numpy.diff

numpy.diff(a, n=1, axis=-1) [source]

Calculate the n-th order discrete difference along given axis.

The first order difference is given by out[n] = a[n+1] - a[n] along the given axis, higher order differences are calculated by using diff recursively.

Parameters:

a : array_like

Input array

n : int, optional

The number of times values are differenced.

axis : int, optional

The axis along which the difference is taken, default is the last axis.
Returns:

diff : ndarray

The n order differences. The shape of the output is the same as a except along axis where the dimension is smaller by n.

See also

gradient, ediff1d, cumsum

Examples

>>> x = np.array([1, 2, 4, 7, 0])
>>> np.diff(x)
array([ 1,  2,  3, -7])
>>> np.diff(x, n=2)
array([  1,   1, -10])

>>> x = np.array([[1, 3, 6, 10], [0, 5, 6, 8]])
>>> np.diff(x)
array([[2, 3, 4],
       [5, 1, 2]])
>>> np.diff(x, axis=0)
array([[-1,  2,  0, -2]])


numpy.ediff1d

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.diff

Next topic

numpy.gradient

numpy.ediff1d

numpy.ediff1d(ary, to_end=None, to_begin=None) [source]

The differences between consecutive elements of an array.

Parameters:

ary : array_like

If necessary, will be flattened before the differences are taken.

to_end : array_like, optional

Number(s) to append at the end of the returned differences.

to_begin : array_like, optional

Number(s) to prepend at the beginning of the returned differences.
Returns:

ediff1d : ndarray

The differences. Loosely, this is ary.flat[1:] - ary.flat[:-1].

See also

diff, gradient

Notes

When applied to masked arrays, this function drops the mask information if the to_begin and/or to_end parameters are used.

Examples

>>> x = np.array([1, 2, 4, 7, 0])
>>> np.ediff1d(x)
array([ 1,  2,  3, -7])

>>> np.ediff1d(x, to_begin=-99, to_end=np.array([88, 99]))
array([-99,   1,   2,   3,  -7,  88,  99])

The returned array is always 1D.

>>> y = [[1, 2, 4], [1, 6, 24]]
>>> np.ediff1d(y)
array([ 1,  2, -3,  5, 18])


numpy.gradient

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.ediff1d

Next topic

numpy.cross

numpy.gradient

numpy.gradient(f, *varargs) [source]

Return the gradient of an N-dimensional array.

The gradient is computed using second order accurate central differences in the interior and second order accurate one-sides (forward or backwards) differences at the boundaries. The returned gradient hence has the same shape as the input array.

Parameters:

f : array_like

An N-dimensional array containing samples of a scalar function.

`*varargs` : scalars

0, 1, or N scalars specifying the sample distances in each direction, that is: dx, dy, dz, ... The default distance is 1.
Returns:

gradient : ndarray

N arrays of the same shape as f giving the derivative of f with respect to each dimension.

Examples

>>> x = np.array([1, 2, 4, 7, 11, 16], dtype=np.float)
>>> np.gradient(x)
array([ 1. ,  1.5,  2.5,  3.5,  4.5,  5. ])
>>> np.gradient(x, 2)
array([ 0.5 ,  0.75,  1.25,  1.75,  2.25,  2.5 ])

>>> np.gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=np.float))
[array([[ 2.,  2., -1.],
       [ 2.,  2., -1.]]),
array([[ 1. ,  2.5,  4. ],
       [ 1. ,  1. ,  1. ]])]

>>> x = np.array([0,1,2,3,4])
>>> dx = gradient(x)
>>> y = x**2
>>> gradient(y,dx)
array([0.,  2.,  4.,  6.,  8.])


numpy.cross

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.gradient

Next topic

numpy.trapz

numpy.cross

numpy.cross(a, b, axisa=-1, axisb=-1, axisc=-1, axis=None) [source]

Return the cross product of two (arrays of) vectors.

The cross product of a and b in [image] is a vector perpendicular to both a and b. If a and b are arrays of vectors, the vectors are defined by the last axis of a and b by default, and these axes can have dimensions 2 or 3. Where the dimension of either a or b is 2, the third component of the input vector is assumed to be zero and the cross product calculated accordingly. In cases where both input vectors have dimension 2, the z-component of the cross product is returned.

Parameters:

a : array_like

Components of the first vector(s).

b : array_like

Components of the second vector(s).

axisa : int, optional

Axis of a that defines the vector(s). By default, the last axis.

axisb : int, optional

Axis of b that defines the vector(s). By default, the last axis.

axisc : int, optional

Axis of c containing the cross product vector(s). By default, the last axis.

axis : int, optional

If defined, the axis of a, b and c that defines the vector(s) and cross product(s). Overrides axisa, axisb and axisc.
Returns:

c : ndarray

Vector cross product(s).
Raises:

ValueError

When the dimension of the vector(s) in a and/or b does not equal 2 or 3.

See also

inner
Inner product
outer
Outer product.
ix_
Construct index arrays.

Notes

New in version 1.9.0.

Supports full broadcasting of the inputs.

Examples

Vector cross-product.

>>> x = [1, 2, 3]
>>> y = [4, 5, 6]
>>> np.cross(x, y)
array([-3,  6, -3])

One vector with dimension 2.

>>> x = [1, 2]
>>> y = [4, 5, 6]
>>> np.cross(x, y)
array([12, -6, -3])

Equivalently:

>>> x = [1, 2, 0]
>>> y = [4, 5, 6]
>>> np.cross(x, y)
array([12, -6, -3])

Both vectors with dimension 2.

>>> x = [1,2]
>>> y = [4,5]
>>> np.cross(x, y)
-3

Multiple vector cross-products. Note that the direction of the cross product vector is defined by the right-hand rule.

>>> x = np.array([[1,2,3], [4,5,6]])
>>> y = np.array([[4,5,6], [1,2,3]])
>>> np.cross(x, y)
array([[-3,  6, -3],
       [ 3, -6,  3]])

The orientation of c can be changed using the axisc keyword.

>>> np.cross(x, y, axisc=0)
array([[-3,  3],
       [ 6, -6],
       [-3,  3]])

Change the vector definition of x and y using axisa and axisb.

>>> x = np.array([[1,2,3], [4,5,6], [7, 8, 9]])
>>> y = np.array([[7, 8, 9], [4,5,6], [1,2,3]])
>>> np.cross(x, y)
array([[ -6,  12,  -6],
       [  0,   0,   0],
       [  6, -12,   6]])
>>> np.cross(x, y, axisa=0, axisb=0)
array([[-24,  48, -24],
       [-30,  60, -30],
       [-36,  72, -36]])


numpy.trapz

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.cross

Next topic

numpy.exp

numpy.trapz

numpy.trapz(y, x=None, dx=1.0, axis=-1) [source]

Integrate along the given axis using the composite trapezoidal rule.

Integrate y (x) along given axis.

Parameters:

y : array_like

Input array to integrate.

x : array_like, optional

If x is None, then spacing between all y elements is dx.

dx : scalar, optional

If x is None, spacing given by dx is assumed. Default is 1.

axis : int, optional

Specify the axis.
Returns:

trapz : float

Definite integral as approximated by trapezoidal rule.

See also

sum, cumsum

Notes

Image [R251] illustrates trapezoidal rule – y-axis locations of points will be taken from y array, by default x-axis distances between points will be 1.0, alternatively they can be provided with x array or with dx scalar. Return value will be equal to combined area under the red lines.

References

[R250] Wikipedia page: http://en.wikipedia.org/wiki/Trapezoidal_rule
[R251] (1, 2) Illustration image: http://en.wikipedia.org/wiki/File:Composite_trapezoidal_rule_illustration.png

Examples

>>> np.trapz([1,2,3])
4.0
>>> np.trapz([1,2,3], x=[4,6,8])
8.0
>>> np.trapz([1,2,3], dx=2)
8.0
>>> a = np.arange(6).reshape(2, 3)
>>> a
array([[0, 1, 2],
       [3, 4, 5]])
>>> np.trapz(a, axis=0)
array([ 1.5,  2.5,  3.5])
>>> np.trapz(a, axis=1)
array([ 2.,  8.])


numpy.exp

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.trapz

Next topic

numpy.expm1

numpy.exp

numpy.exp(x[, out]) = <ufunc 'exp'>

Calculate the exponential of all elements in the input array.

Parameters:

x : array_like

Input values.
Returns:

out : ndarray

Output array, element-wise exponential of x.

See also

expm1
Calculate exp(x) - 1 for all elements in the array.
exp2
Calculate 2**x for all elements in the array.

Notes

The irrational number e is also known as Euler’s number. It is approximately 2.718281, and is the base of the natural logarithm, ln (this means that, if [image], then e^x = y. For real input, exp(x) is always positive.

For complex arguments, x = a + ib, we can write e^x = e^a e^{ib}. The first term, [image], is already known (it is the real argument, described above). The second term, [image], is [image], a function with magnitude 1 and a periodic phase.

References

[R18] Wikipedia, “Exponential function”, http://en.wikipedia.org/wiki/Exponential_function
[R19] M. Abramovitz and I. A. Stegun, “Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables,” Dover, 1964, p. 69, http://www.math.sfu.ca/~cbm/aands/page_69.htm

Examples

Plot the magnitude and phase of exp(x) in the complex plane:

>>> import matplotlib.pyplot as plt

>>> x = np.linspace(-2*np.pi, 2*np.pi, 100)
>>> xx = x + 1j * x[:, np.newaxis] # a + ib over complex plane
>>> out = np.exp(xx)

>>> plt.subplot(121)
>>> plt.imshow(np.abs(out),
...            extent=[-2*np.pi, 2*np.pi, -2*np.pi, 2*np.pi])
>>> plt.title('Magnitude of exp(x)')

>>> plt.subplot(122)
>>> plt.imshow(np.angle(out),
...            extent=[-2*np.pi, 2*np.pi, -2*np.pi, 2*np.pi])
>>> plt.title('Phase (angle) of exp(x)')
>>> plt.show()

(Source code, png, pdf)


numpy.expm1

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.exp

Next topic

numpy.exp2

numpy.expm1

numpy.expm1(x[, out]) = <ufunc 'expm1'>

Calculate exp(x) - 1 for all elements in the array.

Parameters:

x : array_like

Input values.
Returns:

out : ndarray

Element-wise exponential minus one: out = exp(x) - 1.

See also

log1p
log(1 + x), the inverse of expm1.

Notes

This function provides greater precision than exp(x) - 1 for small values of x.

Examples

The true value of exp(1e-10) - 1 is 1.00000000005e-10 to about 32 significant digits. This example shows the superiority of expm1 in this case.

>>> np.expm1(1e-10)
1.00000000005e-10
>>> np.exp(1e-10) - 1
1.000000082740371e-10


numpy.exp2

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.expm1

Next topic

numpy.log

numpy.exp2

numpy.exp2(x[, out]) = <ufunc 'exp2'>

Calculate 2**p for all p in the input array.

Parameters:

x : array_like

Input values.

out : ndarray, optional

Array to insert results into.
Returns:

out : ndarray

Element-wise 2 to the power x.

See also

power

Notes

New in version 1.3.0.

Examples

>>> np.exp2([2, 3])
array([ 4.,  8.])


numpy.log

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.exp2

Next topic

numpy.log10

numpy.log

numpy.log(x[, out]) = <ufunc 'log'>

Natural logarithm, element-wise.

The natural logarithm log is the inverse of the exponential function, so that log(exp(x)) = x. The natural logarithm is logarithm in base e.

Parameters:

x : array_like

Input value.
Returns:

y : ndarray

The natural logarithm of x, element-wise.

See also

log10, log2, log1p, emath.log

Notes

Logarithm is a multivalued function: for each x there is an infinite number of z such that exp(z) = x. The convention is to return the z whose imaginary part lies in [-pi, pi].

For real-valued input data types, log always returns real output. For each value that cannot be expressed as a real number or infinity, it yields nan and sets the invalid floating point error flag.

For complex-valued input, log is a complex analytical function that has a branch cut [-inf, 0] and is continuous from above on it. log handles the floating-point negative zero as an infinitesimal negative number, conforming to the C99 standard.

References

[R44] M. Abramowitz and I.A. Stegun, “Handbook of Mathematical Functions”, 10th printing, 1964, pp. 67. http://www.math.sfu.ca/~cbm/aands/
[R45] Wikipedia, “Logarithm”. http://en.wikipedia.org/wiki/Logarithm

Examples

>>> np.log([1, np.e, np.e**2, 0])
array([  0.,   1.,   2., -Inf])


numpy.log10

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.log

Next topic

numpy.log2

numpy.log10

numpy.log10(x[, out]) = <ufunc 'log10'>

Return the base 10 logarithm of the input array, element-wise.

Parameters:

x : array_like

Input values.
Returns:

y : ndarray

The logarithm to the base 10 of x, element-wise. NaNs are returned where x is negative.

See also

emath.log10

Notes

Logarithm is a multivalued function: for each x there is an infinite number of z such that 10**z = x. The convention is to return the z whose imaginary part lies in [-pi, pi].

For real-valued input data types, log10 always returns real output. For each value that cannot be expressed as a real number or infinity, it yields nan and sets the invalid floating point error flag.

For complex-valued input, log10 is a complex analytical function that has a branch cut [-inf, 0] and is continuous from above on it. log10 handles the floating-point negative zero as an infinitesimal negative number, conforming to the C99 standard.

References

[R46] M. Abramowitz and I.A. Stegun, “Handbook of Mathematical Functions”, 10th printing, 1964, pp. 67. http://www.math.sfu.ca/~cbm/aands/
[R47] Wikipedia, “Logarithm”. http://en.wikipedia.org/wiki/Logarithm

Examples

>>> np.log10([1e-15, -3.])
array([-15.,  NaN])


numpy.log2

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.log10

Next topic

numpy.log1p

numpy.log2

numpy.log2(x[, out]) = <ufunc 'log2'>

Base-2 logarithm of x.

Parameters:

x : array_like

Input values.
Returns:

y : ndarray

Base-2 logarithm of x.

See also

log, log10, log1p, emath.log2

Notes

New in version 1.3.0.

Logarithm is a multivalued function: for each x there is an infinite number of z such that 2**z = x. The convention is to return the z whose imaginary part lies in [-pi, pi].

For real-valued input data types, log2 always returns real output. For each value that cannot be expressed as a real number or infinity, it yields nan and sets the invalid floating point error flag.

For complex-valued input, log2 is a complex analytical function that has a branch cut [-inf, 0] and is continuous from above on it. log2 handles the floating-point negative zero as an infinitesimal negative number, conforming to the C99 standard.

Examples

>>> x = np.array([0, 1, 2, 2**4])
>>> np.log2(x)
array([-Inf,   0.,   1.,   4.])

>>> xi = np.array([0+1.j, 1, 2+0.j, 4.j])
>>> np.log2(xi)
array([ 0.+2.26618007j,  0.+0.j        ,  1.+0.j        ,  2.+2.26618007j])


numpy.log1p

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.log2

Next topic

numpy.logaddexp

numpy.log1p

numpy.log1p(x[, out]) = <ufunc 'log1p'>

Return the natural logarithm of one plus the input array, element-wise.

Calculates log(1 + x).

Parameters:

x : array_like

Input values.
Returns:

y : ndarray

Natural logarithm of 1 + x, element-wise.

See also

expm1
exp(x) - 1, the inverse of log1p.

Notes

For real-valued input, log1p is accurate also for x so small that 1 + x == 1 in floating-point accuracy.

Logarithm is a multivalued function: for each x there is an infinite number of z such that exp(z) = 1 + x. The convention is to return the z whose imaginary part lies in [-pi, pi].

For real-valued input data types, log1p always returns real output. For each value that cannot be expressed as a real number or infinity, it yields nan and sets the invalid floating point error flag.

For complex-valued input, log1p is a complex analytical function that has a branch cut [-inf, -1] and is continuous from above on it. log1p handles the floating-point negative zero as an infinitesimal negative number, conforming to the C99 standard.

References

[R48] M. Abramowitz and I.A. Stegun, “Handbook of Mathematical Functions”, 10th printing, 1964, pp. 67. http://www.math.sfu.ca/~cbm/aands/
[R49] Wikipedia, “Logarithm”. http://en.wikipedia.org/wiki/Logarithm

Examples

>>> np.log1p(1e-99)
1e-99
>>> np.log(1 + 1e-99)
0.0


numpy.logaddexp

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.log1p

Next topic

numpy.logaddexp2

numpy.logaddexp

numpy.logaddexp(x1, x2[, out]) = <ufunc 'logaddexp'>

Logarithm of the sum of exponentiations of the inputs.

Calculates log(exp(x1) + exp(x2)). This function is useful in statistics where the calculated probabilities of events may be so small as to exceed the range of normal floating point numbers. In such cases the logarithm of the calculated probability is stored. This function allows adding probabilities stored in such a fashion.

Parameters:

x1, x2 : array_like

Input values.
Returns:

result : ndarray

Logarithm of exp(x1) + exp(x2).

See also

logaddexp2
Logarithm of the sum of exponentiations of inputs in base 2.

Notes

New in version 1.3.0.

Examples

>>> prob1 = np.log(1e-50)
>>> prob2 = np.log(2.5e-50)
>>> prob12 = np.logaddexp(prob1, prob2)
>>> prob12
-113.87649168120691
>>> np.exp(prob12)
3.5000000000000057e-50


numpy.logaddexp2

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.logaddexp

Next topic

numpy.i0

numpy.logaddexp2

numpy.logaddexp2(x1, x2[, out]) = <ufunc 'logaddexp2'>

Logarithm of the sum of exponentiations of the inputs in base-2.

Calculates log2(2**x1 + 2**x2). This function is useful in machine learning when the calculated probabilities of events may be so small as to exceed the range of normal floating point numbers. In such cases the base-2 logarithm of the calculated probability can be used instead. This function allows adding probabilities stored in such a fashion.

Parameters:

x1, x2 : array_like

Input values.

out : ndarray, optional

Array to store results in.
Returns:

result : ndarray

Base-2 logarithm of 2**x1 + 2**x2.

See also

logaddexp
Logarithm of the sum of exponentiations of the inputs.

Notes

New in version 1.3.0.

Examples

>>> prob1 = np.log2(1e-50)
>>> prob2 = np.log2(2.5e-50)
>>> prob12 = np.logaddexp2(prob1, prob2)
>>> prob1, prob2, prob12
(-166.09640474436813, -164.77447664948076, -164.28904982231052)
>>> 2**prob12
3.4999999999999914e-50


numpy.i0

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.logaddexp2

Next topic

numpy.sinc

numpy.i0

numpy.i0(x) [source]

Modified Bessel function of the first kind, order 0.

Usually denoted [image]. This function does broadcast, but will not “up-cast” int dtype arguments unless accompanied by at least one float or complex dtype argument (see Raises below).

Parameters:

x : array_like, dtype float or complex

Argument of the Bessel function.
Returns:

out : ndarray, shape = x.shape, dtype = x.dtype

The modified Bessel function evaluated at each of the elements of x.
Raises:

TypeError: array cannot be safely cast to required type

If argument consists exclusively of int dtypes.

See also

scipy.special.iv, scipy.special.ive

Notes

We use the algorithm published by Clenshaw [R29] and referenced by Abramowitz and Stegun [R30], for which the function domain is partitioned into the two intervals [0,8] and (8,inf), and Chebyshev polynomial expansions are employed in each interval. Relative error on the domain [0,30] using IEEE arithmetic is documented [R31] as having a peak of 5.8e-16 with an rms of 1.4e-16 (n = 30000).

References

[R29] (1, 2) C. W. Clenshaw, “Chebyshev series for mathematical functions”, in National Physical Laboratory Mathematical Tables, vol. 5, London: Her Majesty’s Stationery Office, 1962.
[R30] (1, 2) M. Abramowitz and I. A. Stegun, Handbook of Mathematical Functions, 10th printing, New York: Dover, 1964, pp. 379. http://www.math.sfu.ca/~cbm/aands/page_379.htm
[R31] (1, 2) http://kobesearch.cpan.org/htdocs/Math-Cephes/Math/Cephes.html

Examples

>>> np.i0([0.])
array(1.0)
>>> np.i0([0., 1. + 2j])
array([ 1.00000000+0.j        ,  0.18785373+0.64616944j])


numpy.sinc

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.i0

Next topic

numpy.signbit

numpy.sinc

numpy.sinc(x) [source]

Return the sinc function.

The sinc function is [image].

Parameters:

x : ndarray

Array (possibly multi-dimensional) of values for which to to calculate sinc(x).
Returns:

out : ndarray

sinc(x), which has the same shape as the input.

Notes

sinc(0) is the limit value 1.

The name sinc is short for “sine cardinal” or “sinus cardinalis”.

The sinc function is used in various signal processing applications, including in anti-aliasing, in the construction of a Lanczos resampling filter, and in interpolation.

For bandlimited interpolation of discrete-time signals, the ideal interpolation kernel is proportional to the sinc function.

References

[R246] Weisstein, Eric W. “Sinc Function.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/SincFunction.html
[R247] Wikipedia, “Sinc function”, http://en.wikipedia.org/wiki/Sinc_function

Examples

>>> x = np.linspace(-4, 4, 41)
>>> np.sinc(x)
array([ -3.89804309e-17,  -4.92362781e-02,  -8.40918587e-02,
        -8.90384387e-02,  -5.84680802e-02,   3.89804309e-17,
         6.68206631e-02,   1.16434881e-01,   1.26137788e-01,
         8.50444803e-02,  -3.89804309e-17,  -1.03943254e-01,
        -1.89206682e-01,  -2.16236208e-01,  -1.55914881e-01,
         3.89804309e-17,   2.33872321e-01,   5.04551152e-01,
         7.56826729e-01,   9.35489284e-01,   1.00000000e+00,
         9.35489284e-01,   7.56826729e-01,   5.04551152e-01,
         2.33872321e-01,   3.89804309e-17,  -1.55914881e-01,
        -2.16236208e-01,  -1.89206682e-01,  -1.03943254e-01,
        -3.89804309e-17,   8.50444803e-02,   1.26137788e-01,
         1.16434881e-01,   6.68206631e-02,   3.89804309e-17,
        -5.84680802e-02,  -8.90384387e-02,  -8.40918587e-02,
        -4.92362781e-02,  -3.89804309e-17])

>>> plt.plot(x, np.sinc(x))
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.title("Sinc Function")
<matplotlib.text.Text object at 0x...>
>>> plt.ylabel("Amplitude")
<matplotlib.text.Text object at 0x...>
>>> plt.xlabel("X")
<matplotlib.text.Text object at 0x...>
>>> plt.show()

It works in 2-D as well:

>>> x = np.linspace(-4, 4, 401)
>>> xx = np.outer(x, x)
>>> plt.imshow(np.sinc(xx))
<matplotlib.image.AxesImage object at 0x...>


numpy.signbit

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.sinc

Next topic

numpy.copysign

numpy.signbit

numpy.signbit(x[, out]) = <ufunc 'signbit'>

Returns element-wise True where signbit is set (less than zero).

Parameters:

x : array_like

The input value(s).

out : ndarray, optional

Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output. See doc.ufuncs.
Returns:

result : ndarray of bool

Output array, or reference to out if that was supplied.

Examples

>>> np.signbit(-1.2)
True
>>> np.signbit(np.array([1, -2.3, 2.1]))
array([False,  True, False], dtype=bool)


numpy.copysign

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.signbit

Next topic

numpy.frexp

numpy.copysign

numpy.copysign(x1, x2[, out]) = <ufunc 'copysign'>

Change the sign of x1 to that of x2, element-wise.

If both arguments are arrays or sequences, they have to be of the same length. If x2 is a scalar, its sign will be copied to all elements of x1.

Parameters:

x1 : array_like

Values to change the sign of.

x2 : array_like

The sign of x2 is copied to x1.

out : ndarray, optional

Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output. See doc.ufuncs.
Returns:

out : array_like

The values of x1 with the sign of x2.

Examples

>>> np.copysign(1.3, -1)
-1.3
>>> 1/np.copysign(0, 1)
inf
>>> 1/np.copysign(0, -1)
-inf

>>> np.copysign([-1, 0, 1], -1.1)
array([-1., -0., -1.])
>>> np.copysign([-1, 0, 1], np.arange(3)-1)
array([-1.,  0.,  1.])


numpy.frexp

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.copysign

Next topic

numpy.ldexp

numpy.frexp

numpy.frexp(x[, out1, out2]) = <ufunc 'frexp'>

Decompose the elements of x into mantissa and twos exponent.

Returns (mantissa, exponent), where x = mantissa * 2**exponent`. The mantissa is lies in the open interval(-1, 1), while the twos exponent is a signed integer.

Parameters:

x : array_like

Array of numbers to be decomposed.

out1: ndarray, optional

Output array for the mantissa. Must have the same shape as x.

out2: ndarray, optional

Output array for the exponent. Must have the same shape as x.
Returns:

(mantissa, exponent) : tuple of ndarrays, (float, int)

mantissa is a float array with values between -1 and 1. exponent is an int array which represents the exponent of 2.

See also

ldexp
Compute y = x1 * 2**x2, the inverse of frexp.

Notes

Complex dtypes are not supported, they will raise a TypeError.

Examples

>>> x = np.arange(9)
>>> y1, y2 = np.frexp(x)
>>> y1
array([ 0.   ,  0.5  ,  0.5  ,  0.75 ,  0.5  ,  0.625,  0.75 ,  0.875,
        0.5  ])
>>> y2
array([0, 1, 2, 2, 3, 3, 3, 3, 4])
>>> y1 * 2**y2
array([ 0.,  1.,  2.,  3.,  4.,  5.,  6.,  7.,  8.])


numpy.ldexp

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.frexp

Next topic

numpy.add

numpy.ldexp

numpy.ldexp(x1, x2[, out]) = <ufunc 'ldexp'>

Returns x1 * 2**x2, element-wise.

The mantissas x1 and twos exponents x2 are used to construct floating point numbers x1 * 2**x2.

Parameters:

x1 : array_like

Array of multipliers.

x2 : array_like, int

Array of twos exponents.

out : ndarray, optional

Output array for the result.
Returns:

y : ndarray or scalar

The result of x1 * 2**x2.

See also

frexp
Return (y1, y2) from x = y1 * 2**y2, inverse to ldexp.

Notes

Complex dtypes are not supported, they will raise a TypeError.

ldexp is useful as the inverse of frexp, if used by itself it is more clear to simply use the expression x1 * 2**x2.

Examples

>>> np.ldexp(5, np.arange(4))
array([  5.,  10.,  20.,  40.], dtype=float32)

>>> x = np.arange(6)
>>> np.ldexp(*np.frexp(x))
array([ 0.,  1.,  2.,  3.,  4.,  5.])


numpy.add

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.ldexp

Next topic

numpy.reciprocal

numpy.add

numpy.add(x1, x2[, out]) = <ufunc 'add'>

Add arguments element-wise.

Parameters:

x1, x2 : array_like

The arrays to be added. If x1.shape != x2.shape, they must be broadcastable to a common shape (which may be the shape of one or the other).
Returns:

add : ndarray or scalar

The sum of x1 and x2, element-wise. Returns a scalar if both x1 and x2 are scalars.

Notes

Equivalent to x1 + x2 in terms of array broadcasting.

Examples

>>> np.add(1.0, 4.0)
5.0
>>> x1 = np.arange(9.0).reshape((3, 3))
>>> x2 = np.arange(3.0)
>>> np.add(x1, x2)
array([[  0.,   2.,   4.],
       [  3.,   5.,   7.],
       [  6.,   8.,  10.]])


numpy.reciprocal

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.add

Next topic

numpy.negative

numpy.reciprocal

numpy.reciprocal(x[, out]) = <ufunc 'reciprocal'>

Return the reciprocal of the argument, element-wise.

Calculates 1/x.

Parameters:

x : array_like

Input array.
Returns:

y : ndarray

Return array.

Notes

Note

This function is not designed to work with integers.

For integer arguments with absolute value larger than 1 the result is always zero because of the way Python handles integer division. For integer zero the result is an overflow.

Examples

>>> np.reciprocal(2.)
0.5
>>> np.reciprocal([1, 2., 3.33])
array([ 1.       ,  0.5      ,  0.3003003])


numpy.negative

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.reciprocal

Next topic

numpy.multiply

numpy.negative

numpy.negative(x[, out]) = <ufunc 'negative'>

Numerical negative, element-wise.

Parameters:

x : array_like or scalar

Input array.
Returns:

y : ndarray or scalar

Returned array or scalar: y = -x.

Examples

>>> np.negative([1.,-1.])
array([-1.,  1.])


numpy.multiply

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.negative

Next topic

numpy.divide

numpy.multiply

numpy.multiply(x1, x2[, out]) = <ufunc 'multiply'>

Multiply arguments element-wise.

Parameters:

x1, x2 : array_like

Input arrays to be multiplied.
Returns:

y : ndarray

The product of x1 and x2, element-wise. Returns a scalar if both x1 and x2 are scalars.

Notes

Equivalent to x1 * x2 in terms of array broadcasting.

Examples

>>> np.multiply(2.0, 4.0)
8.0

>>> x1 = np.arange(9.0).reshape((3, 3))
>>> x2 = np.arange(3.0)
>>> np.multiply(x1, x2)
array([[  0.,   1.,   4.],
       [  0.,   4.,  10.],
       [  0.,   7.,  16.]])


numpy.divide

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.multiply

Next topic

numpy.power

numpy.divide

numpy.divide(x1, x2[, out]) = <ufunc 'divide'>

Divide arguments element-wise.

Parameters:

x1 : array_like

Dividend array.

x2 : array_like

Divisor array.

out : ndarray, optional

Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output. See doc.ufuncs.
Returns:

y : {ndarray, scalar}

The quotient x1/x2, element-wise. Returns a scalar if both x1 and x2 are scalars.

See also

seterr
Set whether to raise or warn on overflow, underflow and division by zero.

Notes

Equivalent to x1 / x2 in terms of array-broadcasting.

Behavior on division by zero can be changed using seterr.

When both x1 and x2 are of an integer type, divide will return integers and throw away the fractional part. Moreover, division by zero always yields zero in integer arithmetic.

Examples

>>> np.divide(2.0, 4.0)
0.5
>>> x1 = np.arange(9.0).reshape((3, 3))
>>> x2 = np.arange(3.0)
>>> np.divide(x1, x2)
array([[ NaN,  1. ,  1. ],
       [ Inf,  4. ,  2.5],
       [ Inf,  7. ,  4. ]])

Note the behavior with integer types:

>>> np.divide(2, 4)
0
>>> np.divide(2, 4.)
0.5

Division by zero always yields zero in integer arithmetic, and does not raise an exception or a warning:

>>> np.divide(np.array([0, 1], dtype=int), np.array([0, 0], dtype=int))
array([0, 0])

Division by zero can, however, be caught using seterr:

>>> old_err_state = np.seterr(divide='raise')
>>> np.divide(1, 0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
FloatingPointError: divide by zero encountered in divide

>>> ignored_states = np.seterr(**old_err_state)
>>> np.divide(1, 0)
0


numpy.power

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.divide

Next topic

numpy.subtract

numpy.power

numpy.power(x1, x2[, out]) = <ufunc 'power'>

First array elements raised to powers from second array, element-wise.

Raise each base in x1 to the positionally-corresponding power in x2. x1 and x2 must be broadcastable to the same shape.

Parameters:

x1 : array_like

The bases.

x2 : array_like

The exponents.
Returns:

y : ndarray

The bases in x1 raised to the exponents in x2.

Examples

Cube each element in a list.

>>> x1 = range(6)
>>> x1
[0, 1, 2, 3, 4, 5]
>>> np.power(x1, 3)
array([  0,   1,   8,  27,  64, 125])

Raise the bases to different exponents.

>>> x2 = [1.0, 2.0, 3.0, 3.0, 2.0, 1.0]
>>> np.power(x1, x2)
array([  0.,   1.,   8.,  27.,  16.,   5.])

The effect of broadcasting.

>>> x2 = np.array([[1, 2, 3, 3, 2, 1], [1, 2, 3, 3, 2, 1]])
>>> x2
array([[1, 2, 3, 3, 2, 1],
       [1, 2, 3, 3, 2, 1]])
>>> np.power(x1, x2)
array([[ 0,  1,  8, 27, 16,  5],
       [ 0,  1,  8, 27, 16,  5]])


numpy.subtract

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.power

Next topic

numpy.true_divide

numpy.subtract

numpy.subtract(x1, x2[, out]) = <ufunc 'subtract'>

Subtract arguments, element-wise.

Parameters:

x1, x2 : array_like

The arrays to be subtracted from each other.
Returns:

y : ndarray

The difference of x1 and x2, element-wise. Returns a scalar if both x1 and x2 are scalars.

Notes

Equivalent to x1 - x2 in terms of array broadcasting.

Examples

>>> np.subtract(1.0, 4.0)
-3.0

>>> x1 = np.arange(9.0).reshape((3, 3))
>>> x2 = np.arange(3.0)
>>> np.subtract(x1, x2)
array([[ 0.,  0.,  0.],
       [ 3.,  3.,  3.],
       [ 6.,  6.,  6.]])


numpy.true_divide

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.subtract

Next topic

numpy.floor_divide

numpy.true_divide

numpy.true_divide(x1, x2[, out]) = <ufunc 'true_divide'>

Returns a true division of the inputs, element-wise.

Instead of the Python traditional ‘floor division’, this returns a true division. True division adjusts the output type to present the best answer, regardless of input types.

Parameters:

x1 : array_like

Dividend array.

x2 : array_like

Divisor array.
Returns:

out : ndarray

Result is scalar if both inputs are scalar, ndarray otherwise.

Notes

The floor division operator // was added in Python 2.2 making // and / equivalent operators. The default floor division operation of / can be replaced by true division with from __future__ import division.

In Python 3.0, // is the floor division operator and / the true division operator. The true_divide(x1, x2) function is equivalent to true division in Python.

Examples

>>> x = np.arange(5)
>>> np.true_divide(x, 4)
array([ 0.  ,  0.25,  0.5 ,  0.75,  1.  ])

>>> x/4
array([0, 0, 0, 0, 1])
>>> x//4
array([0, 0, 0, 0, 1])

>>> from __future__ import division
>>> x/4
array([ 0.  ,  0.25,  0.5 ,  0.75,  1.  ])
>>> x//4
array([0, 0, 0, 0, 1])


numpy.floor_divide

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.true_divide

Next topic

numpy.fmod

numpy.floor_divide

numpy.floor_divide(x1, x2[, out]) = <ufunc 'floor_divide'>

Return the largest integer smaller or equal to the division of the inputs.

Parameters:

x1 : array_like

Numerator.

x2 : array_like

Denominator.
Returns:

y : ndarray

y = floor(x1/x2)

See also

divide
Standard division.
floor
Round a number to the nearest integer toward minus infinity.
ceil
Round a number to the nearest integer toward infinity.

Examples

>>> np.floor_divide(7,3)
2
>>> np.floor_divide([1., 2., 3., 4.], 2.5)
array([ 0.,  0.,  1.,  1.])


numpy.fmod

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.floor_divide

Next topic

numpy.mod

numpy.fmod

numpy.fmod(x1, x2[, out]) = <ufunc 'fmod'>

Return the element-wise remainder of division.

This is the NumPy implementation of the C library function fmod, the remainder has the same sign as the dividend x1. It is equivalent to the Matlab(TM) rem function and should not be confused with the Python modulus operator x1 % x2.

Parameters:

x1 : array_like

Dividend.

x2 : array_like

Divisor.
Returns:

y : array_like

The remainder of the division of x1 by x2.

See also

remainder
Equivalent to the Python % operator.

divide

Notes

The result of the modulo operation for negative dividend and divisors is bound by conventions. For fmod, the sign of result is the sign of the dividend, while for remainder the sign of the result is the sign of the divisor. The fmod function is equivalent to the Matlab(TM) rem function.

Examples

>>> np.fmod([-3, -2, -1, 1, 2, 3], 2)
array([-1,  0, -1,  1,  0,  1])
>>> np.remainder([-3, -2, -1, 1, 2, 3], 2)
array([1, 0, 1, 1, 0, 1])

>>> np.fmod([5, 3], [2, 2.])
array([ 1.,  1.])
>>> a = np.arange(-3, 3).reshape(3, 2)
>>> a
array([[-3, -2],
       [-1,  0],
       [ 1,  2]])
>>> np.fmod(a, [2,2])
array([[-1,  0],
       [-1,  0],
       [ 1,  0]])


numpy.mod

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.fmod

Next topic

numpy.modf

numpy.mod

numpy.mod(x1, x2[, out]) = <ufunc 'remainder'>

Return element-wise remainder of division.

Computes x1 - floor(x1 / x2) * x2, the result has the same sign as the divisor x2. It is equivalent to the Python modulus operator x1 % x2 and should not be confused with the Matlab(TM) rem function.

Parameters:

x1 : array_like

Dividend array.

x2 : array_like

Divisor array.

out : ndarray, optional

Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output. See doc.ufuncs.
Returns:

y : ndarray

The remainder of the quotient x1/x2, element-wise. Returns a scalar if both x1 and x2 are scalars.

See also

fmod
Equivalent of the Matlab(TM) rem function.

divide, floor

Notes

Returns 0 when x2 is 0 and both x1 and x2 are (arrays of) integers.

Examples

>>> np.remainder([4, 7], [2, 3])
array([0, 1])
>>> np.remainder(np.arange(7), 5)
array([0, 1, 2, 3, 4, 0, 1])


numpy.modf

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.mod

Next topic

numpy.remainder

numpy.modf

numpy.modf(x[, out1, out2]) = <ufunc 'modf'>

Return the fractional and integral parts of an array, element-wise.

The fractional and integral parts are negative if the given number is negative.

Parameters:

x : array_like

Input array.
Returns:

y1 : ndarray

Fractional part of x.

y2 : ndarray

Integral part of x.

Notes

For integer input the return values are floats.

Examples

>>> np.modf([0, 3.5])
(array([ 0. ,  0.5]), array([ 0.,  3.]))
>>> np.modf(-0.5)
(-0.5, -0)


numpy.remainder

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.modf

Next topic

numpy.angle

numpy.remainder

numpy.remainder(x1, x2[, out]) = <ufunc 'remainder'>

Return element-wise remainder of division.

Computes x1 - floor(x1 / x2) * x2, the result has the same sign as the divisor x2. It is equivalent to the Python modulus operator x1 % x2 and should not be confused with the Matlab(TM) rem function.

Parameters:

x1 : array_like

Dividend array.

x2 : array_like

Divisor array.

out : ndarray, optional

Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output. See doc.ufuncs.
Returns:

y : ndarray

The remainder of the quotient x1/x2, element-wise. Returns a scalar if both x1 and x2 are scalars.

See also

fmod
Equivalent of the Matlab(TM) rem function.

divide, floor

Notes

Returns 0 when x2 is 0 and both x1 and x2 are (arrays of) integers.

Examples

>>> np.remainder([4, 7], [2, 3])
array([0, 1])
>>> np.remainder(np.arange(7), 5)
array([0, 1, 2, 3, 4, 0, 1])


numpy.angle

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.remainder

Next topic

numpy.real

numpy.angle

numpy.angle(z, deg=0) [source]

Return the angle of the complex argument.

Parameters:

z : array_like

A complex number or sequence of complex numbers.

deg : bool, optional

Return angle in degrees if True, radians if False (default).
Returns:

angle : {ndarray, scalar}

The counterclockwise angle from the positive real axis on the complex plane, with dtype as numpy.float64.

See also

arctan2, absolute

Examples

>>> np.angle([1.0, 1.0j, 1+1j])               # in radians
array([ 0.        ,  1.57079633,  0.78539816])
>>> np.angle(1+1j, deg=True)                  # in degrees
45.0


numpy.real

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.angle

Next topic

numpy.imag

numpy.real

numpy.real(val) [source]

Return the real part of the elements of the array.

Parameters:

val : array_like

Input array.
Returns:

out : ndarray

Output array. If val is real, the type of val is used for the output. If val has complex elements, the returned type is float.

See also

real_if_close, imag, angle

Examples

>>> a = np.array([1+2j, 3+4j, 5+6j])
>>> a.real
array([ 1.,  3.,  5.])
>>> a.real = 9
>>> a
array([ 9.+2.j,  9.+4.j,  9.+6.j])
>>> a.real = np.array([9, 8, 7])
>>> a
array([ 9.+2.j,  8.+4.j,  7.+6.j])


numpy.imag

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.real

Next topic

numpy.conj

numpy.imag

numpy.imag(val) [source]

Return the imaginary part of the elements of the array.

Parameters:

val : array_like

Input array.
Returns:

out : ndarray

Output array. If val is real, the type of val is used for the output. If val has complex elements, the returned type is float.

See also

real, angle, real_if_close

Examples

>>> a = np.array([1+2j, 3+4j, 5+6j])
>>> a.imag
array([ 2.,  4.,  6.])
>>> a.imag = np.array([8, 10, 12])
>>> a
array([ 1. +8.j,  3.+10.j,  5.+12.j])


numpy.conj

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.imag

Next topic

numpy.convolve

numpy.conj

numpy.conj(x[, out]) = <ufunc 'conjugate'>

Return the complex conjugate, element-wise.

The complex conjugate of a complex number is obtained by changing the sign of its imaginary part.

Parameters:

x : array_like

Input value.
Returns:

y : ndarray

The complex conjugate of x, with same dtype as y.

Examples

>>> np.conjugate(1+2j)
(1-2j)

>>> x = np.eye(2) + 1j * np.eye(2)
>>> np.conjugate(x)
array([[ 1.-1.j,  0.-0.j],
       [ 0.-0.j,  1.-1.j]])


numpy.convolve

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.conj

Next topic

numpy.clip

numpy.convolve

numpy.convolve(a, v, mode='full') [source]

Returns the discrete, linear convolution of two one-dimensional sequences.

The convolution operator is often seen in signal processing, where it models the effect of a linear time-invariant system on a signal [R17]. In probability theory, the sum of two independent random variables is distributed according to the convolution of their individual distributions.

If v is longer than a, the arrays are swapped before computation.

Parameters:

a : (N,) array_like

First one-dimensional input array.

v : (M,) array_like

Second one-dimensional input array.

mode : {‘full’, ‘valid’, ‘same’}, optional

‘full’:

By default, mode is ‘full’. This returns the convolution at each point of overlap, with an output shape of (N+M-1,). At the end-points of the convolution, the signals do not overlap completely, and boundary effects may be seen.

‘same’:

Mode same returns output of length max(M, N). Boundary effects are still visible.

‘valid’:

Mode valid returns output of length max(M, N) - min(M, N) + 1. The convolution product is only given for points where the signals overlap completely. Values outside the signal boundary have no effect.
Returns:

out : ndarray

Discrete, linear convolution of a and v.

See also

scipy.signal.fftconvolve
Convolve two arrays using the Fast Fourier Transform.
scipy.linalg.toeplitz
Used to construct the convolution operator.
polymul
Polynomial multiplication. Same output as convolve, but also accepts poly1d objects as input.

Notes

The discrete convolution operation is defined as

It can be shown that a convolution x(t) * y(t) in time/space is equivalent to the multiplication X(f) Y(f) in the Fourier domain, after appropriate padding (padding is necessary to prevent circular convolution). Since multiplication is more efficient (faster) than convolution, the function scipy.signal.fftconvolve exploits the FFT to calculate the convolution of large data-sets.

References

[R17] (1, 2) Wikipedia, “Convolution”, http://en.wikipedia.org/wiki/Convolution.

Examples

Note how the convolution operator flips the second array before “sliding” the two across one another:

>>> np.convolve([1, 2, 3], [0, 1, 0.5])
array([ 0. ,  1. ,  2.5,  4. ,  1.5])

Only return the middle values of the convolution. Contains boundary effects, where zeros are taken into account:

>>> np.convolve([1,2,3],[0,1,0.5], 'same')
array([ 1. ,  2.5,  4. ])

The two arrays are of the same length, so there is only one position where they completely overlap:

>>> np.convolve([1,2,3],[0,1,0.5], 'valid')
array([ 2.5])


numpy.clip

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.convolve

Next topic

numpy.sqrt

numpy.clip

numpy.clip(a, a_min, a_max, out=None) [source]

Clip (limit) the values in an array.

Given an interval, values outside the interval are clipped to the interval edges. For example, if an interval of [0, 1] is specified, values smaller than 0 become 0, and values larger than 1 become 1.

Parameters:

a : array_like

Array containing elements to clip.

a_min : scalar or array_like

Minimum value.

a_max : scalar or array_like

Maximum value. If a_min or a_max are array_like, then they will be broadcasted to the shape of a.

out : ndarray, optional

The results will be placed in this array. It may be the input array for in-place clipping. out must be of the right shape to hold the output. Its type is preserved.
Returns:

clipped_array : ndarray

An array with the elements of a, but where values < a_min are replaced with a_min, and those > a_max with a_max.

See also

numpy.doc.ufuncs
Section “Output arguments”

Examples

>>> a = np.arange(10)
>>> np.clip(a, 1, 8)
array([1, 1, 2, 3, 4, 5, 6, 7, 8, 8])
>>> a
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
>>> np.clip(a, 3, 6, out=a)
array([3, 3, 3, 3, 4, 5, 6, 6, 6, 6])
>>> a = np.arange(10)
>>> a
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
>>> np.clip(a, [3,4,1,1,1,4,4,4,4,4], 8)
array([3, 4, 2, 3, 4, 5, 6, 7, 8, 8])


numpy.sqrt

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.clip

Next topic

numpy.square

numpy.sqrt

numpy.sqrt(x[, out]) = <ufunc 'sqrt'>

Return the positive square-root of an array, element-wise.

Parameters:

x : array_like

The values whose square-roots are required.

out : ndarray, optional

Alternate array object in which to put the result; if provided, it must have the same shape as x
Returns:

y : ndarray

An array of the same shape as x, containing the positive square-root of each element in x. If any element in x is complex, a complex array is returned (and the square-roots of negative reals are calculated). If all of the elements in x are real, so is y, with negative elements returning nan. If out was provided, y is a reference to it.

See also

lib.scimath.sqrt
A version which returns complex numbers when given negative reals.

Notes

sqrt has–consistent with common convention–as its branch cut the real “interval” [-inf, 0), and is continuous from above on it. A branch cut is a curve in the complex plane across which a given complex function fails to be continuous.

Examples

>>> np.sqrt([1,4,9])
array([ 1.,  2.,  3.])

>>> np.sqrt([4, -1, -3+4J])
array([ 2.+0.j,  0.+1.j,  1.+2.j])

>>> np.sqrt([4, -1, numpy.inf])
array([  2.,  NaN,  Inf])


numpy.square

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.sqrt

Next topic

numpy.absolute

numpy.square

numpy.square(x[, out]) = <ufunc 'square'>

Return the element-wise square of the input.

Parameters:

x : array_like

Input data.
Returns:

out : ndarray

Element-wise x*x, of the same shape and dtype as x. Returns scalar if x is a scalar.

See also

numpy.linalg.matrix_power, sqrt, power

Examples

>>> np.square([-1j, 1])
array([-1.-0.j,  1.+0.j])


numpy.absolute

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.square

Next topic

numpy.fabs

numpy.absolute

numpy.absolute(x[, out]) = <ufunc 'absolute'>

Calculate the absolute value element-wise.

Parameters:

x : array_like

Input array.
Returns:

absolute : ndarray

An ndarray containing the absolute value of each element in x. For complex input, a + ib, the absolute value is [image].

Examples

>>> x = np.array([-1.2, 1.2])
>>> np.absolute(x)
array([ 1.2,  1.2])
>>> np.absolute(1.2 + 1j)
1.5620499351813308

Plot the function over [-10, 10]:

>>> import matplotlib.pyplot as plt

>>> x = np.linspace(start=-10, stop=10, num=101)
>>> plt.plot(x, np.absolute(x))
>>> plt.show()

(Source code, png, pdf)

Plot the function over the complex plane:

>>> xx = x + 1j * x[:, np.newaxis]
>>> plt.imshow(np.abs(xx), extent=[-10, 10, -10, 10])
>>> plt.show()

(png, pdf)


numpy.fabs

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.absolute

Next topic

numpy.sign

numpy.fabs

numpy.fabs(x[, out]) = <ufunc 'fabs'>

Compute the absolute values element-wise.

This function returns the absolute values (positive magnitude) of the data in x. Complex values are not handled, use absolute to find the absolute values of complex data.

Parameters:

x : array_like

The array of numbers for which the absolute values are required. If x is a scalar, the result y will also be a scalar.

out : ndarray, optional

Array into which the output is placed. Its type is preserved and it must be of the right shape to hold the output. See doc.ufuncs.
Returns:

y : {ndarray, scalar}

The absolute values of x, the returned values are always floats.

See also

absolute
Absolute values including complex types.

Examples

>>> np.fabs(-1)
1.0
>>> np.fabs([-1.2, 1.2])
array([ 1.2,  1.2])


numpy.sign

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.fabs

Next topic

numpy.maximum

numpy.sign

numpy.sign(x[, out]) = <ufunc 'sign'>

Returns an element-wise indication of the sign of a number.

The sign function returns -1 if x < 0, 0 if x==0, 1 if x > 0.

Parameters:

x : array_like

Input values.
Returns:

y : ndarray

The sign of x.

Examples

>>> np.sign([-5., 4.5])
array([-1.,  1.])
>>> np.sign(0)
0


numpy.maximum

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.sign

Next topic

numpy.minimum

numpy.maximum

numpy.maximum(x1, x2[, out]) = <ufunc 'maximum'>

Element-wise maximum of array elements.

Compare two arrays and returns a new array containing the element-wise maxima. If one of the elements being compared is a NaN, then that element is returned. If both elements are NaNs then the first is returned. The latter distinction is important for complex NaNs, which are defined as at least one of the real or imaginary parts being a NaN. The net effect is that NaNs are propagated.

Parameters:

x1, x2 : array_like

The arrays holding the elements to be compared. They must have the same shape, or shapes that can be broadcast to a single shape.
Returns:

y : {ndarray, scalar}

The maximum of x1 and x2, element-wise. Returns scalar if both x1 and x2 are scalars.

See also

minimum
Element-wise minimum of two arrays, propagates NaNs.
fmax
Element-wise maximum of two arrays, ignores NaNs.
amax
The maximum value of an array along a given axis, propagates NaNs.
nanmax
The maximum value of an array along a given axis, ignores NaNs.

fmin, amin, nanmin

Notes

The maximum is equivalent to np.where(x1 >= x2, x1, x2) when neither x1 nor x2 are nans, but it is faster and does proper broadcasting.

Examples

>>> np.maximum([2, 3, 4], [1, 5, 2])
array([2, 5, 4])

>>> np.maximum(np.eye(2), [0.5, 2]) # broadcasting
array([[ 1. ,  2. ],
       [ 0.5,  2. ]])

>>> np.maximum([np.nan, 0, np.nan], [0, np.nan, np.nan])
array([ NaN,  NaN,  NaN])
>>> np.maximum(np.Inf, 1)
inf


numpy.minimum

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.maximum

Next topic

numpy.fmax

numpy.minimum

numpy.minimum(x1, x2[, out]) = <ufunc 'minimum'>

Element-wise minimum of array elements.

Compare two arrays and returns a new array containing the element-wise minima. If one of the elements being compared is a NaN, then that element is returned. If both elements are NaNs then the first is returned. The latter distinction is important for complex NaNs, which are defined as at least one of the real or imaginary parts being a NaN. The net effect is that NaNs are propagated.

Parameters:

x1, x2 : array_like

The arrays holding the elements to be compared. They must have the same shape, or shapes that can be broadcast to a single shape.
Returns:

y : {ndarray, scalar}

The minimum of x1 and x2, element-wise. Returns scalar if both x1 and x2 are scalars.

See also

maximum
Element-wise maximum of two arrays, propagates NaNs.
fmin
Element-wise minimum of two arrays, ignores NaNs.
amin
The minimum value of an array along a given axis, propagates NaNs.
nanmin
The minimum value of an array along a given axis, ignores NaNs.

fmax, amax, nanmax

Notes

The minimum is equivalent to np.where(x1 <= x2, x1, x2) when neither x1 nor x2 are NaNs, but it is faster and does proper broadcasting.

Examples

>>> np.minimum([2, 3, 4], [1, 5, 2])
array([1, 3, 2])

>>> np.minimum(np.eye(2), [0.5, 2]) # broadcasting
array([[ 0.5,  0. ],
       [ 0. ,  1. ]])

>>> np.minimum([np.nan, 0, np.nan],[0, np.nan, np.nan])
array([ NaN,  NaN,  NaN])
>>> np.minimum(-np.Inf, 1)
-inf


numpy.fmax

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.minimum

Next topic

numpy.fmin

numpy.fmax

numpy.fmax(x1, x2[, out]) = <ufunc 'fmax'>

Element-wise maximum of array elements.

Compare two arrays and returns a new array containing the element-wise maxima. If one of the elements being compared is a NaN, then the non-nan element is returned. If both elements are NaNs then the first is returned. The latter distinction is important for complex NaNs, which are defined as at least one of the real or imaginary parts being a NaN. The net effect is that NaNs are ignored when possible.

Parameters:

x1, x2 : array_like

The arrays holding the elements to be compared. They must have the same shape.
Returns:

y : {ndarray, scalar}

The minimum of x1 and x2, element-wise. Returns scalar if both x1 and x2 are scalars.

See also

fmin
Element-wise minimum of two arrays, ignores NaNs.
maximum
Element-wise maximum of two arrays, propagates NaNs.
amax
The maximum value of an array along a given axis, propagates NaNs.
nanmax
The maximum value of an array along a given axis, ignores NaNs.

minimum, amin, nanmin

Notes

New in version 1.3.0.

The fmax is equivalent to np.where(x1 >= x2, x1, x2) when neither x1 nor x2 are NaNs, but it is faster and does proper broadcasting.

Examples

>>> np.fmax([2, 3, 4], [1, 5, 2])
array([ 2.,  5.,  4.])

>>> np.fmax(np.eye(2), [0.5, 2])
array([[ 1. ,  2. ],
       [ 0.5,  2. ]])

>>> np.fmax([np.nan, 0, np.nan],[0, np.nan, np.nan])
array([  0.,   0.,  NaN])


numpy.fmin

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.fmax

Next topic

numpy.nan_to_num

numpy.fmin

numpy.fmin(x1, x2[, out]) = <ufunc 'fmin'>

Element-wise minimum of array elements.

Compare two arrays and returns a new array containing the element-wise minima. If one of the elements being compared is a NaN, then the non-nan element is returned. If both elements are NaNs then the first is returned. The latter distinction is important for complex NaNs, which are defined as at least one of the real or imaginary parts being a NaN. The net effect is that NaNs are ignored when possible.

Parameters:

x1, x2 : array_like

The arrays holding the elements to be compared. They must have the same shape.
Returns:

y : {ndarray, scalar}

The minimum of x1 and x2, element-wise. Returns scalar if both x1 and x2 are scalars.

See also

fmax
Element-wise maximum of two arrays, ignores NaNs.
minimum
Element-wise minimum of two arrays, propagates NaNs.
amin
The minimum value of an array along a given axis, propagates NaNs.
nanmin
The minimum value of an array along a given axis, ignores NaNs.

maximum, amax, nanmax

Notes

New in version 1.3.0.

The fmin is equivalent to np.where(x1 <= x2, x1, x2) when neither x1 nor x2 are NaNs, but it is faster and does proper broadcasting.

Examples

>>> np.fmin([2, 3, 4], [1, 5, 2])
array([2, 5, 4])

>>> np.fmin(np.eye(2), [0.5, 2])
array([[ 1. ,  2. ],
       [ 0.5,  2. ]])

>>> np.fmin([np.nan, 0, np.nan],[0, np.nan, np.nan])
array([  0.,   0.,  NaN])


numpy.nan_to_num

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.fmin

Next topic

numpy.real_if_close

numpy.nan_to_num

numpy.nan_to_num(x) [source]

Replace nan with zero and inf with finite numbers.

Returns an array or scalar replacing Not a Number (NaN) with zero, (positive) infinity with a very large number and negative infinity with a very small (or negative) number.

Parameters:

x : array_like

Input data.
Returns:

out : ndarray, float

Array with the same shape as x and dtype of the element in x with the greatest precision. NaN is replaced by zero, and infinity (-infinity) is replaced by the largest (smallest or most negative) floating point value that fits in the output dtype. All finite numbers are upcast to the output dtype (default float64).

See also

isinf
Shows which elements are negative or negative infinity.
isneginf
Shows which elements are negative infinity.
isposinf
Shows which elements are positive infinity.
isnan
Shows which elements are Not a Number (NaN).
isfinite
Shows which elements are finite (not NaN, not infinity)

Notes

Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). This means that Not a Number is not equivalent to infinity.

Examples

>>> np.set_printoptions(precision=8)
>>> x = np.array([np.inf, -np.inf, np.nan, -128, 128])
>>> np.nan_to_num(x)
array([  1.79769313e+308,  -1.79769313e+308,   0.00000000e+000,
        -1.28000000e+002,   1.28000000e+002])


numpy.real_if_close

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.nan_to_num

Next topic

numpy.interp

numpy.real_if_close

numpy.real_if_close(a, tol=100) [source]

If complex input returns a real array if complex parts are close to zero.

“Close to zero” is defined as tol * (machine epsilon of the type for a).

Parameters:

a : array_like

Input array.

tol : float

Tolerance in machine epsilons for the complex part of the elements in the array.
Returns:

out : ndarray

If a is real, the type of a is used for the output. If a has complex elements, the returned type is float.

See also

real, imag, angle

Notes

Machine epsilon varies from machine to machine and between data types but Python floats on most platforms have a machine epsilon equal to 2.2204460492503131e-16. You can use ‘np.finfo(np.float).eps’ to print out the machine epsilon for floats.

Examples

>>> np.finfo(np.float).eps
2.2204460492503131e-16

>>> np.real_if_close([2.1 + 4e-14j], tol=1000)
array([ 2.1])
>>> np.real_if_close([2.1 + 4e-13j], tol=1000)
array([ 2.1 +4.00000000e-13j])


numpy.interp

  • Mathematical functions
  • next
  • previous

Previous topic

numpy.real_if_close

Next topic

Matrix library (numpy.matlib)

numpy.interp

numpy.interp(x, xp, fp, left=None, right=None) [source]

One-dimensional linear interpolation.

Returns the one-dimensional piecewise linear interpolant to a function with given values at discrete data-points.

Parameters:

x : array_like

The x-coordinates of the interpolated values.

xp : 1-D sequence of floats

The x-coordinates of the data points, must be increasing.

fp : 1-D sequence of floats

The y-coordinates of the data points, same length as xp.

left : float, optional

Value to return for x < xp[0], default is fp[0].

right : float, optional

Value to return for x > xp[-1], default is fp[-1].
Returns:

y : {float, ndarray}

The interpolated values, same shape as x.
Raises:

ValueError

If xp and fp have different length

Notes

Does not check that the x-coordinate sequence xp is increasing. If xp is not increasing, the results are nonsense. A simple check for increasing is:

np.all(np.diff(xp) > 0)

Examples

>>> xp = [1, 2, 3]
>>> fp = [3, 2, 0]
>>> np.interp(2.5, xp, fp)
1.0
>>> np.interp([0, 1, 1.5, 2.72, 3.14], xp, fp)
array([ 3. ,  3. ,  2.5 ,  0.56,  0. ])
>>> UNDEF = -99.0
>>> np.interp(3.14, xp, fp, right=UNDEF)
-99.0

Plot an interpolant to the sine function:

>>> x = np.linspace(0, 2*np.pi, 10)
>>> y = np.sin(x)
>>> xvals = np.linspace(0, 2*np.pi, 50)
>>> yinterp = np.interp(xvals, x, y)
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, y, 'o')
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.plot(xvals, yinterp, '-x')
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.show()

(Source code, png, pdf)


Matrix library (numpy.matlib)

  • next
  • previous

Previous topic

numpy.interp

Next topic

numpy.matlib.empty

Matrix library (numpy.matlib)

This module contains all functions in the numpy namespace, with the following replacement functions that return matrices instead of ndarrays.

Functions that are also in the numpy namespace and return matrices

mat(data[, dtype]) | Interpret the input as a matrix.
matrix | Returns a matrix from an array-like object, or from a string of data.
asmatrix(data[, dtype]) | Interpret the input as a matrix.
bmat(obj[, ldict, gdict]) | Build a matrix object from a string, nested sequence, or array.

Replacement functions in matlib

empty(shape[, dtype, order]) | Return a new matrix of given shape and type, without initializing entries.
zeros(shape[, dtype, order]) | Return a matrix of given shape and type, filled with zeros.
ones(shape[, dtype, order]) | Matrix of ones.
eye(n[, M, k, dtype]) | Return a matrix with ones on the diagonal and zeros elsewhere.
identity(n[, dtype]) | Returns the square identity matrix of given size.
repmat(a, m, n) | Repeat a 0-D to 2-D array or matrix MxN times.
rand(*args) | Return a matrix of random values with given shape.
randn(*args) | Return a random matrix with data from the “standard normal” distribution.


numpy.matlib.empty

  • Matrix library (numpy.matlib)
  • index
  • next
  • previous

Previous topic

numpy.matlib.randn

Next topic

numpy.matlib.zeros

numpy.matlib.empty

numpy.matlib.empty(shape, dtype=None, order='C') [source]

Return a new matrix of given shape and type, without initializing entries.

Parameters:

shape : int or tuple of int

Shape of the empty matrix.

dtype : data-type, optional

Desired output data-type.

order : {‘C’, ‘F’}, optional

Whether to store multi-dimensional data in C (row-major) or Fortran (column-major) order in memory.

See also

empty_like, zeros

Notes

empty, unlike zeros, does not set the matrix values to zero, and may therefore be marginally faster. On the other hand, it requires the user to manually set all the values in the array, and should be used with caution.

Examples

>>> import numpy.matlib
>>> np.matlib.empty((2, 2))    # filled with random data
matrix([[  6.76425276e-320,   9.79033856e-307],
        [  7.39337286e-309,   3.22135945e-309]])        #random
>>> np.matlib.empty((2, 2), dtype=int)
matrix([[ 6600475,        0],
        [ 6586976, 22740995]])                          #random


numpy.matlib.zeros

  • Matrix library (numpy.matlib)
  • index
  • next
  • previous

Previous topic

numpy.matlib.empty

Next topic

numpy.matlib.ones

numpy.matlib.zeros

numpy.matlib.zeros(shape, dtype=None, order='C') [source]

Return a matrix of given shape and type, filled with zeros.

Parameters:

shape : int or sequence of ints

Shape of the matrix

dtype : data-type, optional

The desired data-type for the matrix, default is float.

order : {‘C’, ‘F’}, optional

Whether to store the result in C- or Fortran-contiguous order, default is ‘C’.
Returns:

out : matrix

Zero matrix of given shape, dtype, and order.

See also

numpy.zeros
Equivalent array function.
matlib.ones
Return a matrix of ones.

Notes

If shape has length one i.e. (N,), or is a scalar N, out becomes a single row matrix of shape (1,N).

Examples

>>> import numpy.matlib
>>> np.matlib.zeros((2, 3))
matrix([[ 0.,  0.,  0.],
        [ 0.,  0.,  0.]])

>>> np.matlib.zeros(2)
matrix([[ 0.,  0.]])


numpy.matlib.ones

  • Matrix library (numpy.matlib)
  • index
  • next
  • previous

Previous topic

numpy.matlib.zeros

Next topic

numpy.matlib.eye

numpy.matlib.ones

numpy.matlib.ones(shape, dtype=None, order='C') [source]

Matrix of ones.

Return a matrix of given shape and type, filled with ones.

Parameters:

shape : {sequence of ints, int}

Shape of the matrix

dtype : data-type, optional

The desired data-type for the matrix, default is np.float64.

order : {‘C’, ‘F’}, optional

Whether to store matrix in C- or Fortran-contiguous order, default is ‘C’.
Returns:

out : matrix

Matrix of ones of given shape, dtype, and order.

See also

ones
Array of ones.
matlib.zeros
Zero matrix.

Notes

If shape has length one i.e. (N,), or is a scalar N, out becomes a single row matrix of shape (1,N).

Examples

>>> np.matlib.ones((2,3))
matrix([[ 1.,  1.,  1.],
        [ 1.,  1.,  1.]])

>>> np.matlib.ones(2)
matrix([[ 1.,  1.]])


numpy.matlib.eye

  • Matrix library (numpy.matlib)
  • index
  • next
  • previous

Previous topic

numpy.matlib.ones

Next topic

numpy.matlib.identity

numpy.matlib.eye

numpy.matlib.eye(n, M=None, k=0, dtype=<type 'float'>) [source]

Return a matrix with ones on the diagonal and zeros elsewhere.

Parameters:

n : int

Number of rows in the output.

M : int, optional

Number of columns in the output, defaults to n.

k : int, optional

Index of the diagonal: 0 refers to the main diagonal, a positive value refers to an upper diagonal, and a negative value to a lower diagonal.

dtype : dtype, optional

Data-type of the returned matrix.
Returns:

I : matrix

A n x M matrix where all elements are equal to zero, except for the k-th diagonal, whose values are equal to one.

See also

numpy.eye
Equivalent array function.
identity
Square identity matrix.

Examples

>>> import numpy.matlib
>>> np.matlib.eye(3, k=1, dtype=float)
matrix([[ 0.,  1.,  0.],
        [ 0.,  0.,  1.],
        [ 0.,  0.,  0.]])


numpy.matlib.identity

  • Matrix library (numpy.matlib)
  • index
  • next
  • previous

Previous topic

numpy.matlib.eye

Next topic

numpy.matlib.repmat

numpy.matlib.identity

numpy.matlib.identity(n, dtype=None) [source]

Returns the square identity matrix of given size.

Parameters:

n : int

Size of the returned identity matrix.

dtype : data-type, optional

Data-type of the output. Defaults to float.
Returns:

out : matrix

n x n matrix with its main diagonal set to one, and all other elements zero.

See also

numpy.identity
Equivalent array function.
matlib.eye
More general matrix identity function.

Examples

>>> import numpy.matlib
>>> np.matlib.identity(3, dtype=int)
matrix([[1, 0, 0],
        [0, 1, 0],
        [0, 0, 1]])


numpy.matlib.repmat

  • Matrix library (numpy.matlib)
  • index
  • next
  • previous

Previous topic

numpy.matlib.identity

Next topic

numpy.matlib.rand

numpy.matlib.repmat

numpy.matlib.repmat(a, m, n) [source]

Repeat a 0-D to 2-D array or matrix MxN times.

Parameters:

a : array_like

The array or matrix to be repeated.

m, n : int

The number of times a is repeated along the first and second axes.
Returns:

out : ndarray

The result of repeating a.

Examples

>>> import numpy.matlib
>>> a0 = np.array(1)
>>> np.matlib.repmat(a0, 2, 3)
array([[1, 1, 1],
       [1, 1, 1]])

>>> a1 = np.arange(4)
>>> np.matlib.repmat(a1, 2, 2)
array([[0, 1, 2, 3, 0, 1, 2, 3],
       [0, 1, 2, 3, 0, 1, 2, 3]])

>>> a2 = np.asmatrix(np.arange(6).reshape(2, 3))
>>> np.matlib.repmat(a2, 2, 3)
matrix([[0, 1, 2, 0, 1, 2, 0, 1, 2],
        [3, 4, 5, 3, 4, 5, 3, 4, 5],
        [0, 1, 2, 0, 1, 2, 0, 1, 2],
        [3, 4, 5, 3, 4, 5, 3, 4, 5]])


numpy.matlib.rand

  • Matrix library (numpy.matlib)
  • index
  • next
  • previous

Previous topic

numpy.matlib.repmat

Next topic

numpy.matlib.randn

numpy.matlib.rand

numpy.matlib.rand(*args) [source]

Return a matrix of random values with given shape.

Create a matrix of the given shape and propagate it with random samples from a uniform distribution over [0, 1).

Parameters:

*args : Arguments

Shape of the output. If given as N integers, each integer specifies the size of one dimension. If given as a tuple, this tuple gives the complete shape.
Returns:

out : ndarray

The matrix of random values with shape given by *args.

See also

randn, numpy.random.rand

Examples

>>> import numpy.matlib
>>> np.matlib.rand(2, 3)
matrix([[ 0.68340382,  0.67926887,  0.83271405],
        [ 0.00793551,  0.20468222,  0.95253525]])       #random
>>> np.matlib.rand((2, 3))
matrix([[ 0.84682055,  0.73626594,  0.11308016],
        [ 0.85429008,  0.3294825 ,  0.89139555]])       #random

If the first argument is a tuple, other arguments are ignored:

>>> np.matlib.rand((2, 3), 4)
matrix([[ 0.46898646,  0.15163588,  0.95188261],
        [ 0.59208621,  0.09561818,  0.00583606]])       #random


numpy.matlib.randn

  • Matrix library (numpy.matlib)
  • index
  • next
  • previous

Previous topic

numpy.matlib.rand

Next topic

Miscellaneous routines

numpy.matlib.randn

numpy.matlib.randn(*args) [source]

Return a random matrix with data from the “standard normal” distribution.

randn generates a matrix filled with random floats sampled from a univariate “normal” (Gaussian) distribution of mean 0 and variance 1.

Parameters:

*args : Arguments

Shape of the output. If given as N integers, each integer specifies the size of one dimension. If given as a tuple, this tuple gives the complete shape.
Returns:

Z : matrix of floats

A matrix of floating-point samples drawn from the standard normal distribution.

See also

rand, random.randn

Notes

For random samples from [image], use:

sigma * np.matlib.randn(...) + mu

Examples

>>> import numpy.matlib
>>> np.matlib.randn(1)
matrix([[-0.09542833]])                                 #random
>>> np.matlib.randn(1, 2, 3)
matrix([[ 0.16198284,  0.0194571 ,  0.18312985],
        [-0.7509172 ,  1.61055   ,  0.45298599]])       #random

Two-by-four matrix of samples from N(3, 6.25):

>>> 2.5 * np.matlib.randn((2, 4)) + 3
matrix([[ 4.74085004,  8.89381862,  4.09042411,  4.83721922],
        [ 7.52373709,  5.07933944, -2.64043543,  0.45610557]])  #random


Miscellaneous routines

  • next
  • previous

Table Of Contents

  • Miscellaneous routines
    • Buffer objects
    • Performance tuning

Previous topic

numpy.matlib.randn

Next topic

numpy.getbuffer

Miscellaneous routines

Buffer objects

getbuffer(obj [,offset[, size]]) | Create a buffer object from the given object referencing a slice of length size starting at offset.
newbuffer(size) | Return a new uninitialized buffer object.

Performance tuning

alterdot | Change dot, vdot, and inner to use accelerated BLAS functions.
restoredot | Restore dot, vdot, and innerproduct to the default non-BLAS implementations.
setbufsize(size) | Set the size of the buffer used in ufuncs.
getbufsize() | Return the size of the buffer used in ufuncs.


numpy.getbuffer

  • Miscellaneous routines
  • next
  • previous

Previous topic

numpy.getbufsize

Next topic

numpy.newbuffer

numpy.getbuffer

numpy.getbuffer(obj[, offset[, size]])

Create a buffer object from the given object referencing a slice of length size starting at offset.

Default is the entire buffer. A read-write buffer is attempted followed by a read-only buffer.

Parameters:

obj : object

offset : int, optional

size : int, optional
Returns:

buffer_obj : buffer

Examples

>>> buf = np.getbuffer(np.ones(5), 1, 3)
>>> len(buf)
3
>>> buf[0]
'\x00'
>>> buf
<read-write buffer for 0x8af1e70, size 3, offset 1 at 0x8ba4ec0>


numpy.newbuffer

  • Miscellaneous routines
  • next
  • previous

Previous topic

numpy.getbuffer

Next topic

numpy.alterdot

numpy.newbuffer

numpy.newbuffer(size)

Return a new uninitialized buffer object.

Parameters:

size : int

Size in bytes of returned buffer object.
Returns:

newbuffer : buffer object

Returned, uninitialized buffer object of size bytes.


numpy.alterdot

  • Miscellaneous routines
  • next
  • previous

Previous topic

numpy.newbuffer

Next topic

numpy.restoredot

numpy.alterdot

numpy.alterdot()

Change dot, vdot, and inner to use accelerated BLAS functions.

Typically, as a user of Numpy, you do not explicitly call this function. If Numpy is built with an accelerated BLAS, this function is automatically called when Numpy is imported.

When Numpy is built with an accelerated BLAS like ATLAS, these functions are replaced to make use of the faster implementations. The faster implementations only affect float32, float64, complex64, and complex128 arrays. Furthermore, the BLAS API only includes matrix-matrix, matrix-vector, and vector-vector products. Products of arrays with larger dimensionalities use the built in functions and are not accelerated.

See also

restoredot
restoredot undoes the effects of alterdot.


numpy.restoredot

  • Miscellaneous routines
  • next
  • previous

Previous topic

numpy.alterdot

Next topic

numpy.setbufsize

numpy.restoredot

numpy.restoredot()

Restore dot, vdot, and innerproduct to the default non-BLAS implementations.

Typically, the user will only need to call this when troubleshooting and installation problem, reproducing the conditions of a build without an accelerated BLAS, or when being very careful about benchmarking linear algebra operations.

See also

alterdot
restoredot undoes the effects of alterdot.


numpy.getbufsize

  • Miscellaneous routines
  • next
  • previous

Previous topic

numpy.setbufsize

Next topic

Padding Arrays

numpy.getbufsize

numpy.getbufsize() [source]

Return the size of the buffer used in ufuncs.

Returns:

getbufsize : int

Size of ufunc buffer in bytes.


Padding Arrays

  • next
  • previous

Previous topic

numpy.getbufsize

Next topic

numpy.pad

Padding Arrays

pad(array, pad_width[, mode]) Pads an array.


numpy.pad

  • Padding Arrays
  • next
  • previous

Previous topic

numpy.pad

Next topic

Polynomials

numpy.pad

numpy.pad(array, pad_width, mode=None, **kwargs) [source]

Pads an array.

Parameters:

array : array_like of rank N

Input array

pad_width : {sequence, int}

Number of values padded to the edges of each axis. ((before_1, after_1), ... (before_N, after_N)) unique pad widths for each axis. ((before, after),) yields same before and after pad for each axis. (pad,) or int is a shortcut for before = after = pad width for all axes.

mode : {str, function}

One of the following string values or a user supplied function.

‘constant’

Pads with a constant value.

‘edge’

Pads with the edge values of array.

‘linear_ramp’

Pads with the linear ramp between end_value and the array edge value.

‘maximum’

Pads with the maximum value of all or part of the vector along each axis.

‘mean’

Pads with the mean value of all or part of the vector along each axis.

‘median’

Pads with the median value of all or part of the vector along each axis.

‘minimum’

Pads with the minimum value of all or part of the vector along each axis.

‘reflect’

Pads with the reflection of the vector mirrored on the first and last values of the vector along each axis.

‘symmetric’

Pads with the reflection of the vector mirrored along the edge of the array.

‘wrap’

Pads with the wrap of the vector along the axis. The first values are used to pad the end and the end values are used to pad the beginning.

<function>

Padding function, see Notes.

stat_length : {sequence, int}, optional

Used in ‘maximum’, ‘mean’, ‘median’, and ‘minimum’. Number of values at edge of each axis used to calculate the statistic value.

((before_1, after_1), ... (before_N, after_N)) unique statistic lengths for each axis.

((before, after),) yields same before and after statistic lengths for each axis.

(stat_length,) or int is a shortcut for before = after = statistic length for all axes.

Default is None, to use the entire axis.

constant_values : {sequence, int}, optional

Used in ‘constant’. The values to set the padded values for each axis.

((before_1, after_1), ... (before_N, after_N)) unique pad constants for each axis.

((before, after),) yields same before and after constants for each axis.

(constant,) or int is a shortcut for before = after = constant for all axes.

Default is 0.

end_values : {sequence, int}, optional

Used in ‘linear_ramp’. The values used for the ending value of the linear_ramp and that will form the edge of the padded array.

((before_1, after_1), ... (before_N, after_N)) unique end values for each axis.

((before, after),) yields same before and after end values for each axis.

(constant,) or int is a shortcut for before = after = end value for all axes.

Default is 0.

reflect_type : str {‘even’, ‘odd’}, optional

Used in ‘reflect’, and ‘symmetric’. The ‘even’ style is the default with an unaltered reflection around the edge value. For the ‘odd’ style, the extented part of the array is created by subtracting the reflected values from two times the edge value.
Returns:

pad : ndarray

Padded array of rank equal to array with shape increased according to pad_width.

Notes

New in version 1.7.0.

For an array with rank greater than 1, some of the padding of later axes is calculated from padding of previous axes. This is easiest to think about with a rank 2 array where the corners of the padded array are calculated by using padded values from the first axis.

The padding function, if used, should return a rank 1 array equal in length to the vector argument with padded values replaced. It has the following signature:

padding_func(vector, iaxis_pad_width, iaxis, **kwargs)

where

vector : ndarray
A rank 1 array already padded with zeros. Padded values are vector[:pad_tuple[0]] and vector[-pad_tuple[1]:].
iaxis_pad_width : tuple
A 2-tuple of ints, iaxis_pad_width[0] represents the number of values padded at the beginning of vector where iaxis_pad_width[1] represents the number of values padded at the end of vector.
iaxis : int
The axis currently being calculated.
kwargs : misc
Any keyword arguments the function requires.

Examples

>>> a = [1, 2, 3, 4, 5]
>>> np.lib.pad(a, (2,3), 'constant', constant_values=(4,6))
array([4, 4, 1, 2, 3, 4, 5, 6, 6, 6])

>>> np.lib.pad(a, (2,3), 'edge')
array([1, 1, 1, 2, 3, 4, 5, 5, 5, 5])

>>> np.lib.pad(a, (2,3), 'linear_ramp', end_values=(5,-4))
array([ 5,  3,  1,  2,  3,  4,  5,  2, -1, -4])

>>> np.lib.pad(a, (2,), 'maximum')
array([5, 5, 1, 2, 3, 4, 5, 5, 5])

>>> np.lib.pad(a, (2,), 'mean')
array([3, 3, 1, 2, 3, 4, 5, 3, 3])

>>> np.lib.pad(a, (2,), 'median')
array([3, 3, 1, 2, 3, 4, 5, 3, 3])

>>> a = [[1,2], [3,4]]
>>> np.lib.pad(a, ((3, 2), (2, 3)), 'minimum')
array([[1, 1, 1, 2, 1, 1, 1],
       [1, 1, 1, 2, 1, 1, 1],
       [1, 1, 1, 2, 1, 1, 1],
       [1, 1, 1, 2, 1, 1, 1],
       [3, 3, 3, 4, 3, 3, 3],
       [1, 1, 1, 2, 1, 1, 1],
       [1, 1, 1, 2, 1, 1, 1]])

>>> a = [1, 2, 3, 4, 5]
>>> np.lib.pad(a, (2,3), 'reflect')
array([3, 2, 1, 2, 3, 4, 5, 4, 3, 2])

>>> np.lib.pad(a, (2,3), 'reflect', reflect_type='odd')
array([-1,  0,  1,  2,  3,  4,  5,  6,  7,  8])

>>> np.lib.pad(a, (2,3), 'symmetric')
array([2, 1, 1, 2, 3, 4, 5, 5, 4, 3])

>>> np.lib.pad(a, (2,3), 'symmetric', reflect_type='odd')
array([0, 1, 1, 2, 3, 4, 5, 5, 6, 7])

>>> np.lib.pad(a, (2,3), 'wrap')
array([4, 5, 1, 2, 3, 4, 5, 1, 2, 3])

>>> def padwithtens(vector, pad_width, iaxis, kwargs):
...     vector[:pad_width[0]] = 10
...     vector[-pad_width[1]:] = 10
...     return vector

>>> a = np.arange(6)
>>> a = a.reshape((2,3))

>>> np.lib.pad(a, 2, padwithtens)
array([[10, 10, 10, 10, 10, 10, 10],
       [10, 10, 10, 10, 10, 10, 10],
       [10, 10,  0,  1,  2, 10, 10],
       [10, 10,  3,  4,  5, 10, 10],
       [10, 10, 10, 10, 10, 10, 10],
       [10, 10, 10, 10, 10, 10, 10]])


Polynomials

  • next
  • previous

Table Of Contents

  • Polynomials
    • Transition notice

Previous topic

numpy.pad

Next topic

Polynomial Package

Polynomials

Polynomials in NumPy can be created, manipulated, and even fitted using the Using the Convenience Classes of the numpy.polynomial package, introduced in NumPy 1.4.

Prior to NumPy 1.4, numpy.poly1d was the class of choice and it is still available in order to maintain backward compatibility. However, the newer Polynomial package is more complete than numpy.poly1d and its convenience classes are better behaved in the numpy environment. Therefore Polynomial is recommended for new coding.

Transition notice

The various routines in the Polynomial package all deal with series whose coefficients go from degree zero upward, which is the reverse order of the Poly1d convention. The easy way to remember this is that indexes correspond to degree, i.e., coef[i] is the coefficient of the term of degree i.

  • Polynomial Package
    • Using the Convenience Classes
    • Polynomial Module (numpy.polynomial.polynomial)
    • Chebyshev Module (numpy.polynomial.chebyshev)
    • Legendre Module (numpy.polynomial.legendre)
    • Laguerre Module (numpy.polynomial.laguerre)
    • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
    • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • Poly1d
    • Basics
    • Fitting
    • Calculus
    • Arithmetic
    • Warnings


Polynomial Package

  • Polynomials
  • next
  • previous

Previous topic

Polynomials

Next topic

Using the Convenience Classes

Polynomial Package

New in version 1.4.0.

  • Using the Convenience Classes
    • Basics
    • Calculus
    • Other Polynomial Constructors
    • Fitting
  • Polynomial Module (numpy.polynomial.polynomial)
    • Polynomial Class
    • Basics
    • Fitting
    • Calculus
    • Algebra
    • Miscellaneous
  • Chebyshev Module (numpy.polynomial.chebyshev)
    • Chebyshev Class
    • Basics
    • Fitting
    • Calculus
    • Algebra
    • Quadrature
    • Miscellaneous
  • Legendre Module (numpy.polynomial.legendre)
    • Legendre Class
    • Basics
    • Fitting
    • Calculus
    • Algebra
    • Quadrature
    • Miscellaneous
  • Laguerre Module (numpy.polynomial.laguerre)
    • Laguerre Class
    • Basics
    • Fitting
    • Calculus
    • Algebra
    • Quadrature
    • Miscellaneous
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
    • Hermite Class
    • Basics
    • Fitting
    • Calculus
    • Algebra
    • Quadrature
    • Miscellaneous
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
    • HermiteE Class
    • Basics
    • Fitting
    • Calculus
    • Algebra
    • Quadrature
    • Miscellaneous


Using the Convenience Classes

  • Polynomials
  • Polynomial Package
  • index
  • next
  • previous

Table Of Contents

  • Using the Convenience Classes
    • Basics
    • Calculus
    • Other Polynomial Constructors
    • Fitting

Previous topic

Polynomial Package

Next topic

Polynomial Module (numpy.polynomial.polynomial)

Using the Convenience Classes

The convenience classes provided by the polynomial package are:

Name | Provides
Polynomial | Power series
Chebyshev | Chebyshev series
Legendre | Legendre series
Laguerre | Laguerre series
Hermite | Hermite series
HermiteE | HermiteE series

The series in this context are finite sums of the corresponding polynomial basis functions multiplied by coefficients. For instance, a power series looks like

p(x) = 1 + 2x + 3x^2

and has coefficients [1, 2, 3]. The Chebyshev series with the same coefficients looks like

p(x) = 1 T_0(x) + 2 T_1(x) + 3 T_2(x)

and more generally

where in this case the [image] are the Chebyshev functions of degree n, but could just as easily be the basis functions of any of the other classes. The convention for all the classes is that the coefficient c[i] goes with the basis function of degree i.

All of the classes have the same methods, and especially they implement the Python numeric operators +, -, *, //, %, divmod, **, ==, and !=. The last two can be a bit problematic due to floating point roundoff errors. We now give a quick demonstration of the various operations using Numpy version 1.7.0.

Basics

First we need a polynomial class and a polynomial instance to play with. The classes can be imported directly from the polynomial package or from the module of the relevant type. Here we import from the package and use the conventional Polynomial class because of its familiarity:

>>> from numpy.polynomial import Polynomial as P
>>> p = P([1,2,3])
>>> p
Polynomial([ 1.,  2.,  3.], [-1.,  1.], [-1.,  1.])

Note that there are three parts to the long version of the printout. The first is the coefficients, the second is the domain, and the third is the window:

>>> p.coef
array([ 1.,  2.,  3.])
>>> p.domain
array([-1.,  1.])
>>> p.window
array([-1.,  1.])

Printing a polynomial yields a shorter form without the domain and window:

>>> print p
poly([ 1.  2.  3.])

We will deal with the domain and window when we get to fitting, for the moment we ignore them and run through the basic algebraic and arithmetic operations.

Addition and Subtraction:

>>> p + p
Polynomial([ 2.,  4.,  6.], [-1.,  1.], [-1.,  1.])
>>> p - p
Polynomial([ 0.], [-1.,  1.], [-1.,  1.])

Multiplication:

>>> p * p
Polynomial([  1.,   4.,  10.,  12.,   9.], [-1.,  1.], [-1.,  1.])

Powers:

>>> p**2
Polynomial([  1.,   4.,  10.,  12.,   9.], [-1.,  1.], [-1.,  1.])

Division:

Floor division, ‘//’, is the division operator for the polynomial classes, polynomials are treated like integers in this regard. For Python versions < 3.x the ‘/’ operator maps to ‘//’, as it does for Python, for later versions the ‘/’ will only work for division by scalars. At some point it will be deprecated:

>>> p // P([-1, 1])
Polynomial([ 5.,  3.], [-1.,  1.], [-1.,  1.])

Remainder:

>>> p % P([-1, 1])
Polynomial([ 6.], [-1.,  1.], [-1.,  1.])

Divmod:

>>> quo, rem = divmod(p, P([-1, 1]))
>>> quo
Polynomial([ 5.,  3.], [-1.,  1.], [-1.,  1.])
>>> rem
Polynomial([ 6.], [-1.,  1.], [-1.,  1.])

Evaluation:

>>> x = np.arange(5)
>>> p(x)
array([  1.,   6.,  17.,  34.,  57.])
>>> x = np.arange(6).reshape(3,2)
>>> p(x)
array([[  1.,   6.],
       [ 17.,  34.],
       [ 57.,  86.]])

Substitution:

Substitute a polynomial for x and expand the result. Here we substitute p in itself leading to a new polynomial of degree 4 after expansion. If the polynomials are regarded as functions this is composition of functions:

>>> p(p)
Polynomial([  6.,  16.,  36.,  36.,  27.], [-1.,  1.], [-1.,  1.])

Roots:

>>> p.roots()
array([-0.33333333-0.47140452j, -0.33333333+0.47140452j])

It isn’t always convenient to explicitly use Polynomial instances, so tuples, lists, arrays, and scalars are automatically cast in the arithmetic operations:

>>> p + [1, 2, 3]
Polynomial([ 2.,  4.,  6.], [-1.,  1.], [-1.,  1.])
>>> [1, 2, 3] * p
Polynomial([  1.,   4.,  10.,  12.,   9.], [-1.,  1.], [-1.,  1.])
>>> p / 2
Polynomial([ 0.5,  1. ,  1.5], [-1.,  1.], [-1.,  1.])

Polynomials that differ in domain, window, or class can’t be mixed in arithmetic:

>>> from numpy.polynomial import Chebyshev as T
>>> p + P([1], domain=[0,1])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 213, in __add__
TypeError: Domains differ
>>> p + P([1], window=[0,1])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 215, in __add__
TypeError: Windows differ
>>> p + T([1])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 211, in __add__
TypeError: Polynomial types differ

But different types can be used for substitution. In fact, this is how conversion of Polynomial classes among themselves is done for type, domain, and window casting:

>>> p(T([0, 1]))
Chebyshev([ 2.5,  2. ,  1.5], [-1.,  1.], [-1.,  1.])

Which gives the polynomial p in Chebyshev form. This works because T_1(x) = x and substituting x for x doesn’t change the original polynomial. However, all the multiplications and divisions will be done using Chebyshev series, hence the type of the result.

Calculus

Polynomial instances can be integrated and differentiated.:

>>> from numpy.polynomial import Polynomial as P
>>> p = P([2, 6])
>>> p.integ()
Polynomial([ 0.,  2.,  3.], [-1.,  1.], [-1.,  1.])
>>> p.integ(2)
Polynomial([ 0.,  0.,  1.,  1.], [-1.,  1.], [-1.,  1.])

The first example integrates p once, the second example integrates it twice. By default, the lower bound of the integration and the integration constant are 0, but both can be specified.:

>>> p.integ(lbnd=-1)
Polynomial([-1.,  2.,  3.], [-1.,  1.], [-1.,  1.])
>>> p.integ(lbnd=-1, k=1)
Polynomial([ 0.,  2.,  3.], [-1.,  1.], [-1.,  1.])

In the first case the lower bound of the integration is set to -1 and the integration constant is 0. In the second the constant of integration is set to 1 as well. Differentiation is simpler since the only option is the number of times the polynomial is differentiated:

>>> p = P([1, 2, 3])
>>> p.deriv(1)
Polynomial([ 2.,  6.], [-1.,  1.], [-1.,  1.])
>>> p.deriv(2)
Polynomial([ 6.], [-1.,  1.], [-1.,  1.])

Other Polynomial Constructors

Constructing polynomials by specifying coefficients is just one way of obtaining a polynomial instance, they may also be created by specifying their roots, by conversion from other polynomial types, and by least squares fits. Fitting is discussed in its own section, the other methods are demonstrated below:

>>> from numpy.polynomial import Polynomial as P
>>> from numpy.polynomial import Chebyshev as T
>>> p = P.fromroots([1, 2, 3])
>>> p
Polynomial([ -6.,  11.,  -6.,   1.], [-1.,  1.], [-1.,  1.])
>>> p.convert(kind=T)
Chebyshev([ -9.  ,  11.75,  -3.  ,   0.25], [-1.,  1.], [-1.,  1.])

The convert method can also convert domain and window:

>>> p.convert(kind=T, domain=[0, 1])
Chebyshev([-2.4375 ,  2.96875, -0.5625 ,  0.03125], [ 0.,  1.], [-1.,  1.])
>>> p.convert(kind=P, domain=[0, 1])
Polynomial([-1.875,  2.875, -1.125,  0.125], [ 0.,  1.], [-1.,  1.])

In numpy versions >= 1.7.0 the basis and cast class methods are also available. The cast method works like the convert method while the basis method returns the basis polynomial of given degree:

>>> P.basis(3)
Polynomial([ 0.,  0.,  0.,  1.], [-1.,  1.], [-1.,  1.])
>>> T.cast(p)
Chebyshev([ -9.  ,  11.75,  -3.  ,   0.25], [-1.,  1.], [-1.,  1.])

Conversions between types can be useful, but it is not recommended for routine use. The loss of numerical precision in passing from a Chebyshev series of degree 50 to a Polynomial series of the same degree can make the results of numerical evaluation essentially random.

Fitting

Fitting is the reason that the domain and window attributes are part of the convenience classes. To illustrate the problem, the values of the Chebyshev polynomials up to degree 5 are plotted below.

>>> import matplotlib.pyplot as plt
>>> from numpy.polynomial import Chebyshev as T
>>> x = np.linspace(-1, 1, 100)
>>> for i in range(6): ax = plt.plot(x, T.basis(i)(x), lw=2, label="$T_%d$"%i)
...
>>> plt.legend(loc="upper left")
<matplotlib.legend.Legend object at 0x3b3ee10>
>>> plt.show()

(Source code, png, pdf)

In the range -1 <= x <= 1 they are nice, equiripple functions lying between +/- 1. The same plots over the range -2 <= x <= 2 look very different:

>>> import matplotlib.pyplot as plt
>>> from numpy.polynomial import Chebyshev as T
>>> x = np.linspace(-2, 2, 100)
>>> for i in range(6): ax = plt.plot(x, T.basis(i)(x), lw=2, label="$T_%d$"%i)
...
>>> plt.legend(loc="lower right")
<matplotlib.legend.Legend object at 0x3b3ee10>
>>> plt.show()

(Source code, png, pdf)

As can be seen, the “good” parts have shrunk to insignificance. In using Chebyshev polynomials for fitting we want to use the region where x is between -1 and 1 and that is what the window specifies. However, it is unlikely that the data to be fit has all its data points in that interval, so we use domain to specify the interval where the data points lie. When the fit is done, the domain is first mapped to the window by a linear transformation and the usual least squares fit is done using the mapped data points. The window and domain of the fit are part of the returned series and are automatically used when computing values, derivatives, and such. If they aren’t specified in the call the fitting routine will use the default window and the smallest domain that holds all the data points. This is illustrated below for a fit to a noisy sine curve.

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from numpy.polynomial import Chebyshev as T
>>> np.random.seed(11)
>>> x = np.linspace(0, 2*np.pi, 20)
>>> y = np.sin(x) + np.random.normal(scale=.1, size=x.shape)
>>> p = T.fit(x, y, 5)
>>> plt.plot(x, y, 'o')
[<matplotlib.lines.Line2D object at 0x2136c10>]
>>> xx, yy = p.linspace()
>>> plt.plot(xx, yy, lw=2)
[<matplotlib.lines.Line2D object at 0x1cf2890>]
>>> p.domain
array([ 0.        ,  6.28318531])
>>> p.window
array([-1.,  1.])
>>> plt.show()

(Source code, png, pdf)


Polynomial Module (numpy.polynomial.polynomial)

  • Polynomials
  • Polynomial Package
  • index
  • next
  • previous

Table Of Contents

  • Polynomial Module (numpy.polynomial.polynomial)
    • Polynomial Class
    • Basics
    • Fitting
    • Calculus
    • Algebra
    • Miscellaneous

Previous topic

Using the Convenience Classes

Next topic

numpy.polynomial.polynomial.Polynomial

Polynomial Module (numpy.polynomial.polynomial)

New in version 1.4.0.

This module provides a number of objects (mostly functions) useful for dealing with Polynomial series, including a Polynomial class that encapsulates the usual arithmetic operations. (General information on how this module represents and works with such polynomials is in the docstring for its “parent” sub-package, numpy.polynomial).

Polynomial Class

Polynomial(coef[, domain, window]) A power series class.

Basics

polyval(x, c[, tensor]) | Evaluate a polynomial at points x.
polyval2d(x, y, c) | Evaluate a 2-D polynomial at points (x, y).
polyval3d(x, y, z, c) | Evaluate a 3-D polynomial at points (x, y, z).
polygrid2d(x, y, c) | Evaluate a 2-D polynomial on the Cartesian product of x and y.
polygrid3d(x, y, z, c) | Evaluate a 3-D polynomial on the Cartesian product of x, y and z.
polyroots(c) | Compute the roots of a polynomial.
polyfromroots(roots) | Generate a monic polynomial with given roots.

Fitting

polyfit(x, y, deg[, rcond, full, w]) | Least-squares fit of a polynomial to data.
polyvander(x, deg) | Vandermonde matrix of given degree.
polyvander2d(x, y, deg) | Pseudo-Vandermonde matrix of given degrees.
polyvander3d(x, y, z, deg) | Pseudo-Vandermonde matrix of given degrees.

Calculus

polyder(c[, m, scl, axis]) | Differentiate a polynomial.
polyint(c[, m, k, lbnd, scl, axis]) | Integrate a polynomial.

Algebra

polyadd(c1, c2) | Add one polynomial to another.
polysub(c1, c2) | Subtract one polynomial from another.
polymul(c1, c2) | Multiply one polynomial by another.
polymulx(c) | Multiply a polynomial by x.
polydiv(c1, c2) | Divide one polynomial by another.
polypow(c, pow[, maxpower]) | Raise a polynomial to a power.

Miscellaneous

polycompanion(c) | Return the companion matrix of c.
polydomain |
polyzero |
polyone |
polyx |
polytrim(c[, tol]) | Remove “small” “trailing” coefficients from a polynomial.
polyline(off, scl) | Returns an array representing a linear polynomial.


numpy.polynomial.polynomial.Polynomial

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyline

Next topic

numpy.polynomial.polynomial.Polynomial.__call__

numpy.polynomial.polynomial.Polynomial

class numpy.polynomial.polynomial.Polynomial(coef, domain=None, window=None) [source]

A power series class.

The Polynomial class provides the standard Python numerical methods ‘+’, ‘-‘, ‘*’, ‘//’, ‘%’, ‘divmod’, ‘**’, and ‘()’ as well as the attributes and methods listed in the ABCPolyBase documentation.

Parameters:

coef : array_like

Polynomial coefficients in order of increasing degree, i.e., (1, 2, 3) give 1 + 2*x + 3*x**2.

domain : (2,) array_like, optional

Domain to use. The interval [domain[0], domain[1]] is mapped to the interval [window[0], window[1]] by shifting and scaling. The default value is [-1, 1].

window : (2,) array_like, optional

Window, see domain for its use. The default value is [-1, 1].

New in version 1.6.0.

Methods

__call__(arg)
basis(deg[, domain, window]) | Series basis polynomial of degree deg.
cast(series[, domain, window]) | Convert series to series of this class.
convert([domain, kind, window]) | Convert series to a different kind and/or domain and/or window.
copy() | Return a copy.
cutdeg(deg) | Truncate series to the given degree.
degree() | The degree of the series.
deriv([m]) | Differentiate.
fit(x, y, deg[, domain, rcond, full, w, window]) | Least squares fit to data.
fromroots(roots[, domain, window]) | Return series instance that has the specified roots.
has_samecoef(other) | Check if coefficients match.
has_samedomain(other) | Check if domains match.
has_sametype(other) | Check if types match.
has_samewindow(other) | Check if windows match.
identity([domain, window]) | Identity function.
integ([m, k, lbnd]) | Integrate.
linspace([n, domain]) | Return x, y values at equally spaced points in domain.
mapparms() | Return the mapping parameters.
roots() | Return the roots of the series polynomial.
trim([tol]) | Remove trailing coefficients
truncate(size) | Truncate series to length size.


numpy.polynomial.polynomial.Polynomial.__call__

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial

Next topic

numpy.polynomial.polynomial.Polynomial.basis

numpy.polynomial.polynomial.Polynomial.__call__

Polynomial.__call__(arg) [source]


numpy.polynomial.polynomial.Polynomial.basis

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.__call__

Next topic

numpy.polynomial.polynomial.Polynomial.cast

numpy.polynomial.polynomial.Polynomial.basis

classmethod Polynomial.basis(deg, domain=None, window=None) [source]

Series basis polynomial of degree deg.

Returns the series representing the basis polynomial of degree deg.

New in version 1.7.0.

Parameters:

deg : int

Degree of the basis polynomial for the series. Must be >= 0.

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

A series with the coefficient of the deg term set to one and all others zero.


numpy.polynomial.polynomial.Polynomial.cast

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.basis

Next topic

numpy.polynomial.polynomial.Polynomial.convert

numpy.polynomial.polynomial.Polynomial.cast

classmethod Polynomial.cast(series, domain=None, window=None) [source]

Convert series to series of this class.

The series is expected to be an instance of some polynomial series of one of the types supported by by the numpy.polynomial module, but could be some other class that supports the convert method.

New in version 1.7.0.

Parameters:

series : series

The series instance to be converted.

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

A series of the same kind as the calling class and equal to series when evaluated.

See also

convert
similar instance method


numpy.polynomial.polynomial.Polynomial.convert

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.cast

Next topic

numpy.polynomial.polynomial.Polynomial.copy

numpy.polynomial.polynomial.Polynomial.convert

Polynomial.convert(domain=None, kind=None, window=None) [source]

Convert series to a different kind and/or domain and/or window.

Parameters:

domain : array_like, optional

The domain of the converted series. If the value is None, the default domain of kind is used.

kind : class, optional

The polynomial series type class to which the current instance should be converted. If kind is None, then the class of the current instance is used.

window : array_like, optional

The window of the converted series. If the value is None, the default window of kind is used.
Returns:

new_series : series

The returned class can be of different type than the current instance and/or have a different domain and/or different window.

Notes

Conversion between domains and class types can result in numerically ill defined series.


numpy.polynomial.polynomial.Polynomial.copy

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.convert

Next topic

numpy.polynomial.polynomial.Polynomial.cutdeg

numpy.polynomial.polynomial.Polynomial.copy

Polynomial.copy() [source]

Return a copy.

Returns:

new_series : series

Copy of self.


numpy.polynomial.polynomial.Polynomial.cutdeg

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.copy

Next topic

numpy.polynomial.polynomial.Polynomial.degree

numpy.polynomial.polynomial.Polynomial.cutdeg

Polynomial.cutdeg(deg) [source]

Truncate series to the given degree.

Reduce the degree of the series to deg by discarding the high order terms. If deg is greater than the current degree a copy of the current series is returned. This can be useful in least squares where the coefficients of the high degree terms may be very small.

New in version 1.5.0.

Parameters:

deg : non-negative int

The series is reduced to degree deg by discarding the high order terms. The value of deg must be a non-negative integer.
Returns:

new_series : series

New instance of series with reduced degree.


numpy.polynomial.polynomial.Polynomial.degree

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.cutdeg

Next topic

numpy.polynomial.polynomial.Polynomial.deriv

numpy.polynomial.polynomial.Polynomial.degree

Polynomial.degree() [source]

The degree of the series.

New in version 1.5.0.

Returns:

degree : int

Degree of the series, one less than the number of coefficients.


numpy.polynomial.polynomial.Polynomial.deriv

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.degree

Next topic

numpy.polynomial.polynomial.Polynomial.fit

numpy.polynomial.polynomial.Polynomial.deriv

Polynomial.deriv(m=1) [source]

Differentiate.

Return a series instance of that is the derivative of the current series.

Parameters:

m : non-negative int

The number of integrations to perform.
Returns:

new_series : series

A new series representing the derivative. The domain is the same as the domain of the differentiated series.


numpy.polynomial.polynomial.Polynomial.fit

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.deriv

Next topic

numpy.polynomial.polynomial.Polynomial.fromroots

numpy.polynomial.polynomial.Polynomial.fit

classmethod Polynomial.fit(x, y, deg, domain=None, rcond=None, full=False, w=None, window=None) [source]

Least squares fit to data.

Return a series instance that is the least squares fit to the data y sampled at x. The domain of the returned instance can be specified and this will often result in a superior fit with less chance of ill conditioning.

Parameters:

x : array_like, shape (M,)

x-coordinates of the M sample points (x[i], y[i]).

y : array_like, shape (M,) or (M, K)

y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column.

deg : int

Degree of the fitting polynomial.

domain : {None, [beg, end], []}, optional

Domain to use for the returned series. If None, then a minimal domain that covers the points x is chosen. If [] the class domain is used. The default value was the class domain in NumPy 1.4 and None in later versions. The [] option was added in numpy 1.5.0.

rcond : float, optional

Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)*eps, where eps is the relative precision of the float type, about 2e-16 in most cases.

full : bool, optional

Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned.

w : array_like, shape (M,), optional

Weights. If not None the contribution of each point (x[i],y[i]) to the fit is weighted by w[i]. Ideally the weights are chosen so that the errors of the products w[i]*y[i] all have the same variance. The default value is None.

New in version 1.5.0.

window : {[beg, end]}, optional

Window to use for the returned series. The default value is the default class domain

New in version 1.6.0.
Returns:

new_series : series

A series that represents the least squares fit to the data and has the domain specified in the call.

[resid, rank, sv, rcond] : list

These values are only returned if full = True

resid – sum of squared residuals of the least squares fit rank – the numerical rank of the scaled Vandermonde matrix sv – singular values of the scaled Vandermonde matrix rcond – value of rcond.

For more details, see linalg.lstsq.


numpy.polynomial.polynomial.Polynomial.fromroots

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.fit

Next topic

numpy.polynomial.polynomial.Polynomial.has_samecoef

numpy.polynomial.polynomial.Polynomial.fromroots

classmethod Polynomial.fromroots(roots, domain=[], window=None) [source]

Return series instance that has the specified roots.

Returns a series representing the product (x - r[0])*(x - r[1])*...*(x - r[n-1]), where r is a list of roots.

Parameters:

roots : array_like

List of roots.

domain : {[], None, array_like}, optional

Domain for the resulting series. If None the domain is the interval from the smallest root to the largest. If [] the domain is the class domain. The default is [].

window : {None, array_like}, optional

Window for the returned series. If None the class window is used. The default is None.
Returns:

new_series : series

Series with the specified roots.


numpy.polynomial.polynomial.Polynomial.has_samecoef

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.fromroots

Next topic

numpy.polynomial.polynomial.Polynomial.has_samedomain

numpy.polynomial.polynomial.Polynomial.has_samecoef

Polynomial.has_samecoef(other) [source]

Check if coefficients match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the coef attribute.
Returns:

bool : boolean

True if the coefficients are the same, False otherwise.


numpy.polynomial.polynomial.Polynomial.has_samedomain

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.has_samecoef

Next topic

numpy.polynomial.polynomial.Polynomial.has_sametype

numpy.polynomial.polynomial.Polynomial.has_samedomain

Polynomial.has_samedomain(other) [source]

Check if domains match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the domain attribute.
Returns:

bool : boolean

True if the domains are the same, False otherwise.


numpy.polynomial.polynomial.Polynomial.has_sametype

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.has_samedomain

Next topic

numpy.polynomial.polynomial.Polynomial.has_samewindow

numpy.polynomial.polynomial.Polynomial.has_sametype

Polynomial.has_sametype(other) [source]

Check if types match.

New in version 1.7.0.

Parameters:

other : object

Class instance.
Returns:

bool : boolean

True if other is same class as self


numpy.polynomial.polynomial.Polynomial.has_samewindow

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.has_sametype

Next topic

numpy.polynomial.polynomial.Polynomial.identity

numpy.polynomial.polynomial.Polynomial.has_samewindow

Polynomial.has_samewindow(other) [source]

Check if windows match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the window attribute.
Returns:

bool : boolean

True if the windows are the same, False otherwise.


numpy.polynomial.polynomial.Polynomial.identity

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.has_samewindow

Next topic

numpy.polynomial.polynomial.Polynomial.integ

numpy.polynomial.polynomial.Polynomial.identity

classmethod Polynomial.identity(domain=None, window=None) [source]

Identity function.

If p is the returned series, then p(x) == x for all values of x.

Parameters:

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

Series of representing the identity.


numpy.polynomial.polynomial.Polynomial.integ

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.identity

Next topic

numpy.polynomial.polynomial.Polynomial.linspace

numpy.polynomial.polynomial.Polynomial.integ

Polynomial.integ(m=1, k=[], lbnd=None) [source]

Integrate.

Return a series instance that is the definite integral of the current series.

Parameters:

m : non-negative int

The number of integrations to perform.

k : array_like

Integration constants. The first constant is applied to the first integration, the second to the second, and so on. The list of values must less than or equal to m in length and any missing values are set to zero.

lbnd : Scalar

The lower bound of the definite integral.
Returns:

new_series : series

A new series representing the integral. The domain is the same as the domain of the integrated series.


numpy.polynomial.polynomial.Polynomial.linspace

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.integ

Next topic

numpy.polynomial.polynomial.Polynomial.mapparms

numpy.polynomial.polynomial.Polynomial.linspace

Polynomial.linspace(n=100, domain=None) [source]

Return x, y values at equally spaced points in domain.

Returns the x, y values at n linearly spaced points across the domain. Here y is the value of the polynomial at the points x. By default the domain is the same as that of the series instance. This method is intended mostly as a plotting aid.

New in version 1.5.0.

Parameters:

n : int, optional

Number of point pairs to return. The default value is 100.

domain : {None, array_like}, optional

If not None, the specified domain is used instead of that of the calling instance. It should be of the form [beg,end]. The default is None which case the class domain is used.
Returns:

x, y : ndarray

x is equal to linspace(self.domain[0], self.domain[1], n) and y is the series evaluated at element of x.


numpy.polynomial.polynomial.Polynomial.mapparms

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.linspace

Next topic

numpy.polynomial.polynomial.Polynomial.roots

numpy.polynomial.polynomial.Polynomial.mapparms

Polynomial.mapparms() [source]

Return the mapping parameters.

The returned values define a linear map off + scl*x that is applied to the input arguments before the series is evaluated. The map depends on the domain and window; if the current domain is equal to the window the resulting map is the identity. If the coefficients of the series instance are to be used by themselves outside this class, then the linear function must be substituted for the x in the standard representation of the base polynomials.

Returns:

off, scl : float or complex

The mapping function is defined by off + scl*x.

Notes

If the current domain is the interval [l1, r1] and the window is [l2, r2], then the linear mapping function L is defined by the equations:

L(l1) = l2
L(r1) = r2


numpy.polynomial.polynomial.Polynomial.roots

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.mapparms

Next topic

numpy.polynomial.polynomial.Polynomial.trim

numpy.polynomial.polynomial.Polynomial.roots

Polynomial.roots() [source]

Return the roots of the series polynomial.

Compute the roots for the series. Note that the accuracy of the roots decrease the further outside the domain they lie.

Returns:

roots : ndarray

Array containing the roots of the series.


numpy.polynomial.polynomial.Polynomial.trim

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.roots

Next topic

numpy.polynomial.polynomial.Polynomial.truncate

numpy.polynomial.polynomial.Polynomial.trim

Polynomial.trim(tol=0) [source]

Remove trailing coefficients

Remove trailing coefficients until a coefficient is reached whose absolute value greater than tol or the beginning of the series is reached. If all the coefficients would be removed the series is set to [0]. A new series instance is returned with the new coefficients. The current instance remains unchanged.

Parameters:

tol : non-negative number.

All trailing coefficients less than tol will be removed.
Returns:

new_series : series

Contains the new set of coefficients.


numpy.polynomial.polynomial.Polynomial.truncate

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • numpy.polynomial.polynomial.Polynomial
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.trim

Next topic

numpy.polynomial.polynomial.polyval

numpy.polynomial.polynomial.Polynomial.truncate

Polynomial.truncate(size) [source]

Truncate series to length size.

Reduce the series to length size by discarding the high degree terms. The value of size must be a positive integer. This can be useful in least squares where the coefficients of the high degree terms may be very small.

Parameters:

size : positive int

The series is reduced to length size by discarding the high degree terms. The value of size must be a positive integer.
Returns:

new_series : series

New instance of series with truncated coefficients.


numpy.polynomial.polynomial.polyval

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.Polynomial.truncate

Next topic

numpy.polynomial.polynomial.polyval2d

numpy.polynomial.polynomial.polyval

numpy.polynomial.polynomial.polyval(x, c, tensor=True) [source]

Evaluate a polynomial at points x.

If c is of length n + 1, this function returns the value

p(x) = c_0 + c_1 * x + ... + c_n * x^n

The parameter x is converted to an array only if it is a tuple or a list, otherwise it is treated as a scalar. In either case, either x or its elements must support multiplication and addition both with themselves and with the elements of c.

If c is a 1-D array, then p(x) will have the same shape as x. If c is multidimensional, then the shape of the result depends on the value of tensor. If tensor is true the shape will be c.shape[1:] + x.shape. If tensor is false the shape will be c.shape[1:]. Note that scalars have shape (,).

Trailing zeros in the coefficients will be used in the evaluation, so they should be avoided if efficiency is a concern.

Parameters:

x : array_like, compatible object

If x is a list or tuple, it is converted to an ndarray, otherwise it is left unchanged and treated as a scalar. In either case, x or its elements must support addition and multiplication with with themselves and with the elements of c.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree n are contained in c[n]. If c is multidimensional the remaining indices enumerate multiple polynomials. In the two dimensional case the coefficients may be thought of as stored in the columns of c.

tensor : boolean, optional

If True, the shape of the coefficient array is extended with ones on the right, one for each dimension of x. Scalars have dimension 0 for this action. The result is that every column of coefficients in c is evaluated for every element of x. If False, x is broadcast over the columns of c for the evaluation. This keyword is useful when c is multidimensional. The default value is True.

New in version 1.7.0.
Returns:

values : ndarray, compatible object

The shape of the returned array is described above.

See also

polyval2d, polygrid2d, polyval3d, polygrid3d

Notes

The evaluation uses Horner’s method.

Examples

>>> from numpy.polynomial.polynomial import polyval
>>> polyval(1, [1,2,3])
6.0
>>> a = np.arange(4).reshape(2,2)
>>> a
array([[0, 1],
       [2, 3]])
>>> polyval(a, [1,2,3])
array([[  1.,   6.],
       [ 17.,  34.]])
>>> coef = np.arange(4).reshape(2,2) # multidimensional coefficients
>>> coef
array([[0, 1],
       [2, 3]])
>>> polyval([1,2], coef, tensor=True)
array([[ 2.,  4.],
       [ 4.,  7.]])
>>> polyval([1,2], coef, tensor=False)
array([ 2.,  7.])


numpy.polynomial.polynomial.polyval2d

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyval

Next topic

numpy.polynomial.polynomial.polyval3d

numpy.polynomial.polynomial.polyval2d

numpy.polynomial.polynomial.polyval2d(x, y, c) [source]

Evaluate a 2-D polynomial at points (x, y).

This function returns the value

The parameters x and y are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars and they must have the same shape after conversion. In either case, either x and y or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than two dimensions, ones are implicitly appended to its shape to make it 2-D. The shape of the result will be c.shape[2:] + x.shape.

Parameters:

x, y : array_like, compatible objects

The two dimensional series is evaluated at the points (x, y), where x and y must have the same shape. If x or y is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and, if it isn’t an ndarray, it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j is contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional polynomial at points formed with pairs of corresponding values from x and y.

See also

polyval, polygrid2d, polyval3d, polygrid3d

Notes

New in version 1.7.0.


numpy.polynomial.polynomial.polyval3d

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyval2d

Next topic

numpy.polynomial.polynomial.polygrid2d

numpy.polynomial.polynomial.polyval3d

numpy.polynomial.polynomial.polyval3d(x, y, z, c) [source]

Evaluate a 3-D polynomial at points (x, y, z).

This function returns the values:

The parameters x, y, and z are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars and they must have the same shape after conversion. In either case, either x, y, and z or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than 3 dimensions, ones are implicitly appended to its shape to make it 3-D. The shape of the result will be c.shape[3:] + x.shape.

Parameters:

x, y, z : array_like, compatible object

The three dimensional series is evaluated at the points (x, y, z), where x, y, and z must have the same shape. If any of x, y, or z is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and if it isn’t an ndarray it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j,k is contained in c[i,j,k]. If c has dimension greater than 3 the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the multidimensional polynomial on points formed with triples of corresponding values from x, y, and z.

See also

polyval, polyval2d, polygrid2d, polygrid3d

Notes

New in version 1.7.0.


numpy.polynomial.polynomial.polygrid2d

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyval3d

Next topic

numpy.polynomial.polynomial.polygrid3d

numpy.polynomial.polynomial.polygrid2d

numpy.polynomial.polynomial.polygrid2d(x, y, c) [source]

Evaluate a 2-D polynomial on the Cartesian product of x and y.

This function returns the values:

where the points (a, b) consist of all pairs formed by taking a from x and b from y. The resulting points form a grid with x in the first dimension and y in the second.

The parameters x and y are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars. In either case, either x and y or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than two dimensions, ones are implicitly appended to its shape to make it 2-D. The shape of the result will be c.shape[2:] + x.shape + y.shape.

Parameters:

x, y : array_like, compatible objects

The two dimensional series is evaluated at the points in the Cartesian product of x and y. If x or y is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and, if it isn’t an ndarray, it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree i,j are contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional polynomial at points in the Cartesian product of x and y.

See also

polyval, polyval2d, polyval3d, polygrid3d

Notes

New in version 1.7.0.


numpy.polynomial.polynomial.polygrid3d

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polygrid2d

Next topic

numpy.polynomial.polynomial.polyroots

numpy.polynomial.polynomial.polygrid3d

numpy.polynomial.polynomial.polygrid3d(x, y, z, c) [source]

Evaluate a 3-D polynomial on the Cartesian product of x, y and z.

This function returns the values:

where the points (a, b, c) consist of all triples formed by taking a from x, b from y, and c from z. The resulting points form a grid with x in the first dimension, y in the second, and z in the third.

The parameters x, y, and z are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars. In either case, either x, y, and z or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than three dimensions, ones are implicitly appended to its shape to make it 3-D. The shape of the result will be c.shape[3:] + x.shape + y.shape + z.shape.

Parameters:

x, y, z : array_like, compatible objects

The three dimensional series is evaluated at the points in the Cartesian product of x, y, and z. If x,`y`, or z is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and, if it isn’t an ndarray, it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree i,j are contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional polynomial at points in the Cartesian product of x and y.

See also

polyval, polyval2d, polygrid2d, polyval3d

Notes

New in version 1.7.0.


numpy.polynomial.polynomial.polyroots

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polygrid3d

Next topic

numpy.polynomial.polynomial.polyfromroots

numpy.polynomial.polynomial.polyroots

numpy.polynomial.polynomial.polyroots(c) [source]

Compute the roots of a polynomial.

Return the roots (a.k.a. “zeros”) of the polynomial

Parameters:

c : 1-D array_like

1-D array of polynomial coefficients.
Returns:

out : ndarray

Array of the roots of the polynomial. If all the roots are real, then out is also real, otherwise it is complex.

See also

chebroots

Notes

The root estimates are obtained as the eigenvalues of the companion matrix, Roots far from the origin of the complex plane may have large errors due to the numerical instability of the power series for such values. Roots with multiplicity greater than 1 will also show larger errors as the value of the series near such points is relatively insensitive to errors in the roots. Isolated roots near the origin can be improved by a few iterations of Newton’s method.

Examples

>>> import numpy.polynomial.polynomial as poly
>>> poly.polyroots(poly.polyfromroots((-1,0,1)))
array([-1.,  0.,  1.])
>>> poly.polyroots(poly.polyfromroots((-1,0,1))).dtype
dtype('float64')
>>> j = complex(0,1)
>>> poly.polyroots(poly.polyfromroots((-j,0,j)))
array([  0.00000000e+00+0.j,   0.00000000e+00+1.j,   2.77555756e-17-1.j])


numpy.polynomial.polynomial.polyfromroots

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyroots

Next topic

numpy.polynomial.polynomial.polyfit

numpy.polynomial.polynomial.polyfromroots

numpy.polynomial.polynomial.polyfromroots(roots) [source]

Generate a monic polynomial with given roots.

Return the coefficients of the polynomial

p(x) = (x - r_0) * (x - r_1) * ... * (x - r_n),

where the r_n are the roots specified in roots. If a zero has multiplicity n, then it must appear in roots n times. For instance, if 2 is a root of multiplicity three and 3 is a root of multiplicity 2, then roots looks something like [2, 2, 2, 3, 3]. The roots can appear in any order.

If the returned coefficients are c, then

p(x) = c_0 + c_1 * x + ... + x^n

The coefficient of the last term is 1 for monic polynomials in this form.

Parameters:

roots : array_like

Sequence containing the roots.
Returns:

out : ndarray

1-D array of the polynomial’s coefficients If all the roots are real, then out is also real, otherwise it is complex. (see Examples below).

See also

chebfromroots, legfromroots, lagfromroots, hermfromroots, hermefromroots

Notes

The coefficients are determined by multiplying together linear factors of the form (x - r_i), i.e.

p(x) = (x - r_0) (x - r_1) ... (x - r_n)

where n == len(roots) - 1; note that this implies that 1 is always returned for [image].

Examples

>>> from numpy.polynomial import polynomial as P
>>> P.polyfromroots((-1,0,1)) # x(x - 1)(x + 1) = x^3 - x
array([ 0., -1.,  0.,  1.])
>>> j = complex(0,1)
>>> P.polyfromroots((-j,j)) # complex returned, though values are real
array([ 1.+0.j,  0.+0.j,  1.+0.j])


numpy.polynomial.polynomial.polyfit

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyfromroots

Next topic

numpy.polynomial.polynomial.polyvander

numpy.polynomial.polynomial.polyfit

numpy.polynomial.polynomial.polyfit(x, y, deg, rcond=None, full=False, w=None) [source]

Least-squares fit of a polynomial to data.

Return the coefficients of a polynomial of degree deg that is the least squares fit to the data values y given at points x. If y is 1-D the returned coefficients will also be 1-D. If y is 2-D multiple fits are done, one for each column of y, and the resulting coefficients are stored in the corresponding columns of a 2-D return. The fitted polynomial(s) are in the form

p(x) = c_0 + c_1 * x + ... + c_n * x^n,

where n is deg.

Parameters:

x : array_like, shape (M,)

x-coordinates of the M sample (data) points (x[i], y[i]).

y : array_like, shape (M,) or (M, K)

y-coordinates of the sample points. Several sets of sample points sharing the same x-coordinates can be (independently) fit with one call to polyfit by passing in for y a 2-D array that contains one data set per column.

deg : int

Degree of the polynomial(s) to be fit.

rcond : float, optional

Relative condition number of the fit. Singular values smaller than rcond, relative to the largest singular value, will be ignored. The default value is len(x)*eps, where eps is the relative precision of the platform’s float type, about 2e-16 in most cases.

full : bool, optional

Switch determining the nature of the return value. When False (the default) just the coefficients are returned; when True, diagnostic information from the singular value decomposition (used to solve the fit’s matrix equation) is also returned.

w : array_like, shape (M,), optional

Weights. If not None, the contribution of each point (x[i],y[i]) to the fit is weighted by w[i]. Ideally the weights are chosen so that the errors of the products w[i]*y[i] all have the same variance. The default value is None.

New in version 1.5.0.
Returns:

coef : ndarray, shape (deg + 1,) or (deg + 1, K)

Polynomial coefficients ordered from low to high. If y was 2-D, the coefficients in column k of coef represent the polynomial fit to the data in y‘s k-th column.

[residuals, rank, singular_values, rcond] : list

These values are only returned if full = True

resid – sum of squared residuals of the least squares fit rank – the numerical rank of the scaled Vandermonde matrix sv – singular values of the scaled Vandermonde matrix rcond – value of rcond.

For more details, see linalg.lstsq.
Raises:

RankWarning

Raised if the matrix in the least-squares fit is rank deficient. The warning is only raised if full == False. The warnings can be turned off by:

>>> import warnings
>>> warnings.simplefilter('ignore', RankWarning)

See also

chebfit, legfit, lagfit, hermfit, hermefit

polyval
Evaluates a polynomial.
polyvander
Vandermonde matrix for powers.
linalg.lstsq
Computes a least-squares fit from the matrix.
scipy.interpolate.UnivariateSpline
Computes spline fits.

Notes

The solution is the coefficients of the polynomial p that minimizes the sum of the weighted squared errors

where the [image] are the weights. This problem is solved by setting up the (typically) over-determined matrix equation:

V(x) * c = w * y,

where V is the weighted pseudo Vandermonde matrix of x, c are the coefficients to be solved for, w are the weights, and y are the observed values. This equation is then solved using the singular value decomposition of V.

If some of the singular values of V are so small that they are neglected (and full == False), a RankWarning will be raised. This means that the coefficient values may be poorly determined. Fitting to a lower order polynomial will usually get rid of the warning (but may not be what you want, of course; if you have independent reason(s) for choosing the degree which isn’t working, you may have to: a) reconsider those reasons, and/or b) reconsider the quality of your data). The rcond parameter can also be set to a value smaller than its default, but the resulting fit may be spurious and have large contributions from roundoff error.

Polynomial fits using double precision tend to “fail” at about (polynomial) degree 20. Fits using Chebyshev or Legendre series are generally better conditioned, but much can still depend on the distribution of the sample points and the smoothness of the data. If the quality of the fit is inadequate, splines may be a good alternative.

Examples

>>> from numpy.polynomial import polynomial as P
>>> x = np.linspace(-1,1,51) # x "data": [-1, -0.96, ..., 0.96, 1]
>>> y = x**3 - x + np.random.randn(len(x)) # x^3 - x + N(0,1) "noise"
>>> c, stats = P.polyfit(x,y,3,full=True)
>>> c # c[0], c[2] should be approx. 0, c[1] approx. -1, c[3] approx. 1
array([ 0.01909725, -1.30598256, -0.00577963,  1.02644286])
>>> stats # note the large SSR, explaining the rather poor results
[array([ 38.06116253]), 4, array([ 1.38446749,  1.32119158,  0.50443316,
0.28853036]), 1.1324274851176597e-014]

Same thing without the added noise

>>> y = x**3 - x
>>> c, stats = P.polyfit(x,y,3,full=True)
>>> c # c[0], c[2] should be "very close to 0", c[1] ~= -1, c[3] ~= 1
array([ -1.73362882e-17,  -1.00000000e+00,  -2.67471909e-16,
         1.00000000e+00])
>>> stats # note the minuscule SSR
[array([  7.46346754e-31]), 4, array([ 1.38446749,  1.32119158,
0.50443316,  0.28853036]), 1.1324274851176597e-014]


numpy.polynomial.polynomial.polyvander

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyfit

Next topic

numpy.polynomial.polynomial.polyvander2d

numpy.polynomial.polynomial.polyvander

numpy.polynomial.polynomial.polyvander(x, deg) [source]

Vandermonde matrix of given degree.

Returns the Vandermonde matrix of degree deg and sample points x. The Vandermonde matrix is defined by

V[..., i] = x^i,

where 0 <= i <= deg. The leading indices of V index the elements of x and the last index is the power of x.

If c is a 1-D array of coefficients of length n + 1 and V is the matrix V = polyvander(x, n), then np.dot(V, c) and polyval(x, c) are the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of polynomials of the same degree and sample points.

Parameters:

x : array_like

Array of points. The dtype is converted to float64 or complex128 depending on whether any of the elements are complex. If x is scalar it is converted to a 1-D array.

deg : int

Degree of the resulting matrix.
Returns:

vander : ndarray.

The Vandermonde matrix. The shape of the returned matrix is x.shape + (deg + 1,), where the last index is the power of x. The dtype will be the same as the converted x.

See also

polyvander2d, polyvander3d


numpy.polynomial.polynomial.polyvander2d

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyvander

Next topic

numpy.polynomial.polynomial.polyvander3d

numpy.polynomial.polynomial.polyvander2d

numpy.polynomial.polynomial.polyvander2d(x, y, deg) [source]

Pseudo-Vandermonde matrix of given degrees.

Returns the pseudo-Vandermonde matrix of degrees deg and sample points (x, y). The pseudo-Vandermonde matrix is defined by

V[..., deg[1]*i + j] = x^i * y^j,

where 0 <= i <= deg[0] and 0 <= j <= deg[1]. The leading indices of V index the points (x, y) and the last index encodes the powers of x and y.

If V = polyvander2d(x, y, [xdeg, ydeg]), then the columns of V correspond to the elements of a 2-D coefficient array c of shape (xdeg + 1, ydeg + 1) in the order

c_{00}, c_{01}, c_{02} ... , c_{10}, c_{11}, c_{12} ...

and np.dot(V, c.flat) and polyval2d(x, y, c) will be the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of 2-D polynomials of the same degrees and sample points.

Parameters:

x, y : array_like

Arrays of point coordinates, all of the same shape. The dtypes will be converted to either float64 or complex128 depending on whether any of the elements are complex. Scalars are converted to 1-D arrays.

deg : list of ints

List of maximum degrees of the form [x_deg, y_deg].
Returns:

vander2d : ndarray

The shape of the returned matrix is x.shape + (order,), where order = (deg[0]+1)*(deg([1]+1). The dtype will be the same as the converted x and y.

See also

polyvander, polyvander3d., polyval3d


numpy.polynomial.polynomial.polyvander3d

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyvander2d

Next topic

numpy.polynomial.polynomial.polyder

numpy.polynomial.polynomial.polyvander3d

numpy.polynomial.polynomial.polyvander3d(x, y, z, deg) [source]

Pseudo-Vandermonde matrix of given degrees.

Returns the pseudo-Vandermonde matrix of degrees deg and sample points (x, y, z). If l, m, n are the given degrees in x, y, z, then The pseudo-Vandermonde matrix is defined by

V[..., (m+1)(n+1)i + (n+1)j + k] = x^i * y^j * z^k,

where 0 <= i <= l, 0 <= j <= m, and 0 <= j <= n. The leading indices of V index the points (x, y, z) and the last index encodes the powers of x, y, and z.

If V = polyvander3d(x, y, z, [xdeg, ydeg, zdeg]), then the columns of V correspond to the elements of a 3-D coefficient array c of shape (xdeg + 1, ydeg + 1, zdeg + 1) in the order

c_{000}, c_{001}, c_{002},... , c_{010}, c_{011}, c_{012},...

and np.dot(V, c.flat) and polyval3d(x, y, z, c) will be the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of 3-D polynomials of the same degrees and sample points.

Parameters:

x, y, z : array_like

Arrays of point coordinates, all of the same shape. The dtypes will be converted to either float64 or complex128 depending on whether any of the elements are complex. Scalars are converted to 1-D arrays.

deg : list of ints

List of maximum degrees of the form [x_deg, y_deg, z_deg].
Returns:

vander3d : ndarray

The shape of the returned matrix is x.shape + (order,), where order = (deg[0]+1)*(deg([1]+1)*(deg[2]+1). The dtype will be the same as the converted x, y, and z.

See also

polyvander, polyvander3d., polyval3d

Notes

New in version 1.7.0.


numpy.polynomial.polynomial.polyder

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyvander3d

Next topic

numpy.polynomial.polynomial.polyint

numpy.polynomial.polynomial.polyder

numpy.polynomial.polynomial.polyder(c, m=1, scl=1, axis=0) [source]

Differentiate a polynomial.

Returns the polynomial coefficients c differentiated m times along axis. At each iteration the result is multiplied by scl (the scaling factor is for use in a linear change of variable). The argument c is an array of coefficients from low to high degree along each axis, e.g., [1,2,3] represents the polynomial 1 + 2*x + 3*x**2 while [[1,2],[1,2]] represents 1 + 1*x + 2*y + 2*x*y if axis=0 is x and axis=1 is y.

Parameters:

c : array_like

Array of polynomial coefficients. If c is multidimensional the different axis correspond to different variables with the degree in each axis given by the corresponding index.

m : int, optional

Number of derivatives taken, must be non-negative. (Default: 1)

scl : scalar, optional

Each differentiation is multiplied by scl. The end result is multiplication by scl**m. This is for use in a linear change of variable. (Default: 1)

axis : int, optional

Axis over which the derivative is taken. (Default: 0).

New in version 1.7.0.
Returns:

der : ndarray

Polynomial coefficients of the derivative.

See also

polyint

Examples

>>> from numpy.polynomial import polynomial as P
>>> c = (1,2,3,4) # 1 + 2x + 3x**2 + 4x**3
>>> P.polyder(c) # (d/dx)(c) = 2 + 6x + 12x**2
array([  2.,   6.,  12.])
>>> P.polyder(c,3) # (d**3/dx**3)(c) = 24
array([ 24.])
>>> P.polyder(c,scl=-1) # (d/d(-x))(c) = -2 - 6x - 12x**2
array([ -2.,  -6., -12.])
>>> P.polyder(c,2,-1) # (d**2/d(-x)**2)(c) = 6 + 24x
array([  6.,  24.])


numpy.polynomial.polynomial.polyint

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyder

Next topic

numpy.polynomial.polynomial.polyadd

numpy.polynomial.polynomial.polyint

numpy.polynomial.polynomial.polyint(c, m=1, k=[], lbnd=0, scl=1, axis=0) [source]

Integrate a polynomial.

Returns the polynomial coefficients c integrated m times from lbnd along axis. At each iteration the resulting series is multiplied by scl and an integration constant, k, is added. The scaling factor is for use in a linear change of variable. (“Buyer beware”: note that, depending on what one is doing, one may want scl to be the reciprocal of what one might expect; for more information, see the Notes section below.) The argument c is an array of coefficients, from low to high degree along each axis, e.g., [1,2,3] represents the polynomial 1 + 2*x + 3*x**2 while [[1,2],[1,2]] represents 1 + 1*x + 2*y + 2*x*y if axis=0 is x and axis=1 is y.

Parameters:

c : array_like

1-D array of polynomial coefficients, ordered from low to high.

m : int, optional

Order of integration, must be positive. (Default: 1)

k : {[], list, scalar}, optional

Integration constant(s). The value of the first integral at zero is the first value in the list, the value of the second integral at zero is the second value, etc. If k == [] (the default), all constants are set to zero. If m == 1, a single scalar can be given instead of a list.

lbnd : scalar, optional

The lower bound of the integral. (Default: 0)

scl : scalar, optional

Following each integration the result is multiplied by scl before the integration constant is added. (Default: 1)

axis : int, optional

Axis over which the integral is taken. (Default: 0).

New in version 1.7.0.
Returns:

S : ndarray

Coefficient array of the integral.
Raises:

ValueError

If m < 1, len(k) > m.

See also

polyder

Notes

Note that the result of each integration is multiplied by scl. Why is this important to note? Say one is making a linear change of variable u = ax + b in an integral relative to x. Then .. math::dx = du/a, so one will need to set scl equal to 1/a - perhaps not what one would have first thought.

Examples

>>> from numpy.polynomial import polynomial as P
>>> c = (1,2,3)
>>> P.polyint(c) # should return array([0, 1, 1, 1])
array([ 0.,  1.,  1.,  1.])
>>> P.polyint(c,3) # should return array([0, 0, 0, 1/6, 1/12, 1/20])
array([ 0.        ,  0.        ,  0.        ,  0.16666667,  0.08333333,
        0.05      ])
>>> P.polyint(c,k=3) # should return array([3, 1, 1, 1])
array([ 3.,  1.,  1.,  1.])
>>> P.polyint(c,lbnd=-2) # should return array([6, 1, 1, 1])
array([ 6.,  1.,  1.,  1.])
>>> P.polyint(c,scl=-2) # should return array([0, -2, -2, -2])
array([ 0., -2., -2., -2.])


numpy.polynomial.polynomial.polyadd

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyint

Next topic

numpy.polynomial.polynomial.polysub

numpy.polynomial.polynomial.polyadd

numpy.polynomial.polynomial.polyadd(c1, c2) [source]

Add one polynomial to another.

Returns the sum of two polynomials c1 + c2. The arguments are sequences of coefficients from lowest order term to highest, i.e., [1,2,3] represents the polynomial 1 + 2*x + 3*x**2.

Parameters:

c1, c2 : array_like

1-D arrays of polynomial coefficients ordered from low to high.
Returns:

out : ndarray

The coefficient array representing their sum.

See also

polysub, polymul, polydiv, polypow

Examples

>>> from numpy.polynomial import polynomial as P
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
>>> sum = P.polyadd(c1,c2); sum
array([ 4.,  4.,  4.])
>>> P.polyval(2, sum) # 4 + 4(2) + 4(2**2)
28.0


numpy.polynomial.polynomial.polysub

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyadd

Next topic

numpy.polynomial.polynomial.polymul

numpy.polynomial.polynomial.polysub

numpy.polynomial.polynomial.polysub(c1, c2) [source]

Subtract one polynomial from another.

Returns the difference of two polynomials c1 - c2. The arguments are sequences of coefficients from lowest order term to highest, i.e., [1,2,3] represents the polynomial 1 + 2*x + 3*x**2.

Parameters:

c1, c2 : array_like

1-D arrays of polynomial coefficients ordered from low to high.
Returns:

out : ndarray

Of coefficients representing their difference.

See also

polyadd, polymul, polydiv, polypow

Examples

>>> from numpy.polynomial import polynomial as P
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
>>> P.polysub(c1,c2)
array([-2.,  0.,  2.])
>>> P.polysub(c2,c1) # -P.polysub(c1,c2)
array([ 2.,  0., -2.])


numpy.polynomial.polynomial.polymul

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polysub

Next topic

numpy.polynomial.polynomial.polymulx

numpy.polynomial.polynomial.polymul

numpy.polynomial.polynomial.polymul(c1, c2) [source]

Multiply one polynomial by another.

Returns the product of two polynomials c1 * c2. The arguments are sequences of coefficients, from lowest order term to highest, e.g., [1,2,3] represents the polynomial 1 + 2*x + 3*x**2.

Parameters:

c1, c2 : array_like

1-D arrays of coefficients representing a polynomial, relative to the “standard” basis, and ordered from lowest order term to highest.
Returns:

out : ndarray

Of the coefficients of their product.

See also

polyadd, polysub, polydiv, polypow

Examples

>>> from numpy.polynomial import polynomial as P
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
>>> P.polymul(c1,c2)
array([  3.,   8.,  14.,   8.,   3.])


numpy.polynomial.polynomial.polymulx

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polymul

Next topic

numpy.polynomial.polynomial.polydiv

numpy.polynomial.polynomial.polymulx

numpy.polynomial.polynomial.polymulx(c) [source]

Multiply a polynomial by x.

Multiply the polynomial c by x, where x is the independent variable.

Parameters:

c : array_like

1-D array of polynomial coefficients ordered from low to high.
Returns:

out : ndarray

Array representing the result of the multiplication.

Notes

New in version 1.5.0.


numpy.polynomial.polynomial.polydiv

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polymulx

Next topic

numpy.polynomial.polynomial.polypow

numpy.polynomial.polynomial.polydiv

numpy.polynomial.polynomial.polydiv(c1, c2) [source]

Divide one polynomial by another.

Returns the quotient-with-remainder of two polynomials c1 / c2. The arguments are sequences of coefficients, from lowest order term to highest, e.g., [1,2,3] represents 1 + 2*x + 3*x**2.

Parameters:

c1, c2 : array_like

1-D arrays of polynomial coefficients ordered from low to high.
Returns:

[quo, rem] : ndarrays

Of coefficient series representing the quotient and remainder.

See also

polyadd, polysub, polymul, polypow

Examples

>>> from numpy.polynomial import polynomial as P
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
>>> P.polydiv(c1,c2)
(array([ 3.]), array([-8., -4.]))
>>> P.polydiv(c2,c1)
(array([ 0.33333333]), array([ 2.66666667,  1.33333333]))


numpy.polynomial.polynomial.polypow

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polydiv

Next topic

numpy.polynomial.polynomial.polycompanion

numpy.polynomial.polynomial.polypow

numpy.polynomial.polynomial.polypow(c, pow, maxpower=None) [source]

Raise a polynomial to a power.

Returns the polynomial c raised to the power pow. The argument c is a sequence of coefficients ordered from low to high. i.e., [1,2,3] is the series 1 + 2*x + 3*x**2.

Parameters:

c : array_like

1-D array of array of series coefficients ordered from low to high degree.

pow : integer

Power to which the series will be raised

maxpower : integer, optional

Maximum power allowed. This is mainly to limit growth of the series to unmanageable size. Default is 16
Returns:

coef : ndarray

Power series of power.

See also

polyadd, polysub, polymul, polydiv


numpy.polynomial.polynomial.polycompanion

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polypow

Next topic

numpy.polynomial.polynomial.polydomain

numpy.polynomial.polynomial.polycompanion

numpy.polynomial.polynomial.polycompanion(c) [source]

Return the companion matrix of c.

The companion matrix for power series cannot be made symmetric by scaling the basis, so this function differs from those for the orthogonal polynomials.

Parameters:

c : array_like

1-D array of polynomial coefficients ordered from low to high degree.
Returns:

mat : ndarray

Companion matrix of dimensions (deg, deg).

Notes

New in version 1.7.0.


numpy.polynomial.polynomial.polydomain

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polycompanion

Next topic

numpy.polynomial.polynomial.polyzero

numpy.polynomial.polynomial.polydomain

numpy.polynomial.polynomial.polydomain = array([-1, 1])


numpy.polynomial.polynomial.polyzero

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polydomain

Next topic

numpy.polynomial.polynomial.polyone

numpy.polynomial.polynomial.polyzero

numpy.polynomial.polynomial.polyzero = array([0])


numpy.polynomial.polynomial.polyone

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyzero

Next topic

numpy.polynomial.polynomial.polyx

numpy.polynomial.polynomial.polyone

numpy.polynomial.polynomial.polyone = array([1])


numpy.polynomial.polynomial.polyx

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyone

Next topic

numpy.polynomial.polynomial.polytrim

numpy.polynomial.polynomial.polyx

numpy.polynomial.polynomial.polyx = array([0, 1])


numpy.polynomial.polynomial.polytrim

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polyx

Next topic

numpy.polynomial.polynomial.polyline

numpy.polynomial.polynomial.polytrim

numpy.polynomial.polynomial.polytrim(c, tol=0) [source]

Remove “small” “trailing” coefficients from a polynomial.

“Small” means “small in absolute value” and is controlled by the parameter tol; “trailing” means highest order coefficient(s), e.g., in [0, 1, 1, 0, 0] (which represents 0 + x + x**2 + 0*x**3 + 0*x**4) both the 3-rd and 4-th order coefficients would be “trimmed.”

Parameters:

c : array_like

1-d array of coefficients, ordered from lowest order to highest.

tol : number, optional

Trailing (i.e., highest order) elements with absolute value less than or equal to tol (default value is zero) are removed.
Returns:

trimmed : ndarray

1-d array with trailing zeros removed. If the resulting series would be empty, a series containing a single zero is returned.
Raises:

ValueError

If tol < 0

See also

trimseq

Examples

>>> from numpy import polynomial as P
>>> P.trimcoef((0,0,3,0,5,0,0))
array([ 0.,  0.,  3.,  0.,  5.])
>>> P.trimcoef((0,0,1e-3,0,1e-5,0,0),1e-3) # item == tol is trimmed
array([ 0.])
>>> i = complex(0,1) # works for complex
>>> P.trimcoef((3e-4,1e-3*(1-i),5e-4,2e-5*(1+i)), 1e-3)
array([ 0.0003+0.j   ,  0.0010-0.001j])


numpy.polynomial.polynomial.polyline

  • Polynomials
  • Polynomial Package
  • Polynomial Module (numpy.polynomial.polynomial)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.polynomial.polytrim

Next topic

Chebyshev Module (numpy.polynomial.chebyshev)

numpy.polynomial.polynomial.polyline

numpy.polynomial.polynomial.polyline(off, scl) [source]

Returns an array representing a linear polynomial.

Parameters:

off, scl : scalars

The “y-intercept” and “slope” of the line, respectively.
Returns:

y : ndarray

This module’s representation of the linear polynomial off + scl*x.

See also

chebline

Examples

>>> from numpy.polynomial import polynomial as P
>>> P.polyline(1,-1)
array([ 1, -1])
>>> P.polyval(1, P.polyline(1,-1)) # should be 0
0.0


Chebyshev Module (numpy.polynomial.chebyshev)

  • Polynomials
  • Polynomial Package
  • index
  • next
  • previous

Table Of Contents

  • Chebyshev Module (numpy.polynomial.chebyshev)
    • Chebyshev Class
    • Basics
    • Fitting
    • Calculus
    • Algebra
    • Quadrature
    • Miscellaneous

Previous topic

numpy.polynomial.polynomial.polyline

Next topic

numpy.polynomial.chebyshev.Chebyshev

Chebyshev Module (numpy.polynomial.chebyshev)

New in version 1.4.0.

This module provides a number of objects (mostly functions) useful for dealing with Chebyshev series, including a Chebyshev class that encapsulates the usual arithmetic operations. (General information on how this module represents and works with such polynomials is in the docstring for its “parent” sub-package, numpy.polynomial).

Chebyshev Class

Chebyshev(coef[, domain, window]) A Chebyshev series class.

Basics

chebval(x, c[, tensor]) | Evaluate a Chebyshev series at points x.
chebval2d(x, y, c) | Evaluate a 2-D Chebyshev series at points (x, y).
chebval3d(x, y, z, c) | Evaluate a 3-D Chebyshev series at points (x, y, z).
chebgrid2d(x, y, c) | Evaluate a 2-D Chebyshev series on the Cartesian product of x and y.
chebgrid3d(x, y, z, c) | Evaluate a 3-D Chebyshev series on the Cartesian product of x, y, and z.
chebroots(c) | Compute the roots of a Chebyshev series.
chebfromroots(roots) | Generate a Chebyshev series with given roots.

Fitting

chebfit(x, y, deg[, rcond, full, w]) | Least squares fit of Chebyshev series to data.
chebvander(x, deg) | Pseudo-Vandermonde matrix of given degree.
chebvander2d(x, y, deg) | Pseudo-Vandermonde matrix of given degrees.
chebvander3d(x, y, z, deg) | Pseudo-Vandermonde matrix of given degrees.

Calculus

chebder(c[, m, scl, axis]) | Differentiate a Chebyshev series.
chebint(c[, m, k, lbnd, scl, axis]) | Integrate a Chebyshev series.

Algebra

chebadd(c1, c2) | Add one Chebyshev series to another.
chebsub(c1, c2) | Subtract one Chebyshev series from another.
chebmul(c1, c2) | Multiply one Chebyshev series by another.
chebmulx(c) | Multiply a Chebyshev series by x.
chebdiv(c1, c2) | Divide one Chebyshev series by another.
chebpow(c, pow[, maxpower]) | Raise a Chebyshev series to a power.

Quadrature

chebgauss(deg) | Gauss-Chebyshev quadrature.
chebweight(x) | The weight function of the Chebyshev polynomials.

Miscellaneous

chebcompanion(c) | Return the scaled companion matrix of c.
chebdomain |
chebzero |
chebone |
chebx |
chebtrim(c[, tol]) | Remove “small” “trailing” coefficients from a polynomial.
chebline(off, scl) | Chebyshev series whose graph is a straight line.
cheb2poly(c) | Convert a Chebyshev series to a polynomial.
poly2cheb(pol) | Convert a polynomial to a Chebyshev series.


numpy.polynomial.chebyshev.Chebyshev

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.poly2cheb

Next topic

numpy.polynomial.chebyshev.Chebyshev.__call__

numpy.polynomial.chebyshev.Chebyshev

class numpy.polynomial.chebyshev.Chebyshev(coef, domain=None, window=None) [source]

A Chebyshev series class.

The Chebyshev class provides the standard Python numerical methods ‘+’, ‘-‘, ‘*’, ‘//’, ‘%’, ‘divmod’, ‘**’, and ‘()’ as well as the methods listed below.

Parameters:

coef : array_like

Chebyshev coefficients in order of increasing degree, i.e., (1, 2, 3) gives 1*T_0(x) + 2*T_1(x) + 3*T_2(x).

domain : (2,) array_like, optional

Domain to use. The interval [domain[0], domain[1]] is mapped to the interval [window[0], window[1]] by shifting and scaling. The default value is [-1, 1].

window : (2,) array_like, optional

Window, see domain for its use. The default value is [-1, 1].

New in version 1.6.0.

Methods

__call__(arg)
basis(deg[, domain, window]) | Series basis polynomial of degree deg.
cast(series[, domain, window]) | Convert series to series of this class.
convert([domain, kind, window]) | Convert series to a different kind and/or domain and/or window.
copy() | Return a copy.
cutdeg(deg) | Truncate series to the given degree.
degree() | The degree of the series.
deriv([m]) | Differentiate.
fit(x, y, deg[, domain, rcond, full, w, window]) | Least squares fit to data.
fromroots(roots[, domain, window]) | Return series instance that has the specified roots.
has_samecoef(other) | Check if coefficients match.
has_samedomain(other) | Check if domains match.
has_sametype(other) | Check if types match.
has_samewindow(other) | Check if windows match.
identity([domain, window]) | Identity function.
integ([m, k, lbnd]) | Integrate.
linspace([n, domain]) | Return x, y values at equally spaced points in domain.
mapparms() | Return the mapping parameters.
roots() | Return the roots of the series polynomial.
trim([tol]) | Remove trailing coefficients
truncate(size) | Truncate series to length size.


numpy.polynomial.chebyshev.Chebyshev.__call__

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev

Next topic

numpy.polynomial.chebyshev.Chebyshev.basis

numpy.polynomial.chebyshev.Chebyshev.__call__

Chebyshev.__call__(arg) [source]


numpy.polynomial.chebyshev.Chebyshev.basis

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.__call__

Next topic

numpy.polynomial.chebyshev.Chebyshev.cast

numpy.polynomial.chebyshev.Chebyshev.basis

classmethod Chebyshev.basis(deg, domain=None, window=None) [source]

Series basis polynomial of degree deg.

Returns the series representing the basis polynomial of degree deg.

New in version 1.7.0.

Parameters:

deg : int

Degree of the basis polynomial for the series. Must be >= 0.

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

A series with the coefficient of the deg term set to one and all others zero.


numpy.polynomial.chebyshev.Chebyshev.cast

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.basis

Next topic

numpy.polynomial.chebyshev.Chebyshev.convert

numpy.polynomial.chebyshev.Chebyshev.cast

classmethod Chebyshev.cast(series, domain=None, window=None) [source]

Convert series to series of this class.

The series is expected to be an instance of some polynomial series of one of the types supported by by the numpy.polynomial module, but could be some other class that supports the convert method.

New in version 1.7.0.

Parameters:

series : series

The series instance to be converted.

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

A series of the same kind as the calling class and equal to series when evaluated.

See also

convert
similar instance method


numpy.polynomial.chebyshev.Chebyshev.convert

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.cast

Next topic

numpy.polynomial.chebyshev.Chebyshev.copy

numpy.polynomial.chebyshev.Chebyshev.convert

Chebyshev.convert(domain=None, kind=None, window=None) [source]

Convert series to a different kind and/or domain and/or window.

Parameters:

domain : array_like, optional

The domain of the converted series. If the value is None, the default domain of kind is used.

kind : class, optional

The polynomial series type class to which the current instance should be converted. If kind is None, then the class of the current instance is used.

window : array_like, optional

The window of the converted series. If the value is None, the default window of kind is used.
Returns:

new_series : series

The returned class can be of different type than the current instance and/or have a different domain and/or different window.

Notes

Conversion between domains and class types can result in numerically ill defined series.


numpy.polynomial.chebyshev.Chebyshev.copy

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.convert

Next topic

numpy.polynomial.chebyshev.Chebyshev.cutdeg

numpy.polynomial.chebyshev.Chebyshev.copy

Chebyshev.copy() [source]

Return a copy.

Returns:

new_series : series

Copy of self.


numpy.polynomial.chebyshev.Chebyshev.cutdeg

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.copy

Next topic

numpy.polynomial.chebyshev.Chebyshev.degree

numpy.polynomial.chebyshev.Chebyshev.cutdeg

Chebyshev.cutdeg(deg) [source]

Truncate series to the given degree.

Reduce the degree of the series to deg by discarding the high order terms. If deg is greater than the current degree a copy of the current series is returned. This can be useful in least squares where the coefficients of the high degree terms may be very small.

New in version 1.5.0.

Parameters:

deg : non-negative int

The series is reduced to degree deg by discarding the high order terms. The value of deg must be a non-negative integer.
Returns:

new_series : series

New instance of series with reduced degree.


numpy.polynomial.chebyshev.Chebyshev.degree

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.cutdeg

Next topic

numpy.polynomial.chebyshev.Chebyshev.deriv

numpy.polynomial.chebyshev.Chebyshev.degree

Chebyshev.degree() [source]

The degree of the series.

New in version 1.5.0.

Returns:

degree : int

Degree of the series, one less than the number of coefficients.


numpy.polynomial.chebyshev.Chebyshev.deriv

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.degree

Next topic

numpy.polynomial.chebyshev.Chebyshev.fit

numpy.polynomial.chebyshev.Chebyshev.deriv

Chebyshev.deriv(m=1) [source]

Differentiate.

Return a series instance of that is the derivative of the current series.

Parameters:

m : non-negative int

The number of integrations to perform.
Returns:

new_series : series

A new series representing the derivative. The domain is the same as the domain of the differentiated series.


numpy.polynomial.chebyshev.Chebyshev.fit

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.deriv

Next topic

numpy.polynomial.chebyshev.Chebyshev.fromroots

numpy.polynomial.chebyshev.Chebyshev.fit

classmethod Chebyshev.fit(x, y, deg, domain=None, rcond=None, full=False, w=None, window=None) [source]

Least squares fit to data.

Return a series instance that is the least squares fit to the data y sampled at x. The domain of the returned instance can be specified and this will often result in a superior fit with less chance of ill conditioning.

Parameters:

x : array_like, shape (M,)

x-coordinates of the M sample points (x[i], y[i]).

y : array_like, shape (M,) or (M, K)

y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column.

deg : int

Degree of the fitting polynomial.

domain : {None, [beg, end], []}, optional

Domain to use for the returned series. If None, then a minimal domain that covers the points x is chosen. If [] the class domain is used. The default value was the class domain in NumPy 1.4 and None in later versions. The [] option was added in numpy 1.5.0.

rcond : float, optional

Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)*eps, where eps is the relative precision of the float type, about 2e-16 in most cases.

full : bool, optional

Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned.

w : array_like, shape (M,), optional

Weights. If not None the contribution of each point (x[i],y[i]) to the fit is weighted by w[i]. Ideally the weights are chosen so that the errors of the products w[i]*y[i] all have the same variance. The default value is None.

New in version 1.5.0.

window : {[beg, end]}, optional

Window to use for the returned series. The default value is the default class domain

New in version 1.6.0.
Returns:

new_series : series

A series that represents the least squares fit to the data and has the domain specified in the call.

[resid, rank, sv, rcond] : list

These values are only returned if full = True

resid – sum of squared residuals of the least squares fit rank – the numerical rank of the scaled Vandermonde matrix sv – singular values of the scaled Vandermonde matrix rcond – value of rcond.

For more details, see linalg.lstsq.


numpy.polynomial.chebyshev.Chebyshev.fromroots

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.fit

Next topic

numpy.polynomial.chebyshev.Chebyshev.has_samecoef

numpy.polynomial.chebyshev.Chebyshev.fromroots

classmethod Chebyshev.fromroots(roots, domain=[], window=None) [source]

Return series instance that has the specified roots.

Returns a series representing the product (x - r[0])*(x - r[1])*...*(x - r[n-1]), where r is a list of roots.

Parameters:

roots : array_like

List of roots.

domain : {[], None, array_like}, optional

Domain for the resulting series. If None the domain is the interval from the smallest root to the largest. If [] the domain is the class domain. The default is [].

window : {None, array_like}, optional

Window for the returned series. If None the class window is used. The default is None.
Returns:

new_series : series

Series with the specified roots.


numpy.polynomial.chebyshev.Chebyshev.has_samecoef

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.fromroots

Next topic

numpy.polynomial.chebyshev.Chebyshev.has_samedomain

numpy.polynomial.chebyshev.Chebyshev.has_samecoef

Chebyshev.has_samecoef(other) [source]

Check if coefficients match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the coef attribute.
Returns:

bool : boolean

True if the coefficients are the same, False otherwise.


numpy.polynomial.chebyshev.Chebyshev.has_samedomain

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.has_samecoef

Next topic

numpy.polynomial.chebyshev.Chebyshev.has_sametype

numpy.polynomial.chebyshev.Chebyshev.has_samedomain

Chebyshev.has_samedomain(other) [source]

Check if domains match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the domain attribute.
Returns:

bool : boolean

True if the domains are the same, False otherwise.


numpy.polynomial.chebyshev.Chebyshev.has_sametype

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.has_samedomain

Next topic

numpy.polynomial.chebyshev.Chebyshev.has_samewindow

numpy.polynomial.chebyshev.Chebyshev.has_sametype

Chebyshev.has_sametype(other) [source]

Check if types match.

New in version 1.7.0.

Parameters:

other : object

Class instance.
Returns:

bool : boolean

True if other is same class as self


numpy.polynomial.chebyshev.Chebyshev.has_samewindow

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.has_sametype

Next topic

numpy.polynomial.chebyshev.Chebyshev.identity

numpy.polynomial.chebyshev.Chebyshev.has_samewindow

Chebyshev.has_samewindow(other) [source]

Check if windows match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the window attribute.
Returns:

bool : boolean

True if the windows are the same, False otherwise.


numpy.polynomial.chebyshev.Chebyshev.identity

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.has_samewindow

Next topic

numpy.polynomial.chebyshev.Chebyshev.integ

numpy.polynomial.chebyshev.Chebyshev.identity

classmethod Chebyshev.identity(domain=None, window=None) [source]

Identity function.

If p is the returned series, then p(x) == x for all values of x.

Parameters:

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

Series of representing the identity.


numpy.polynomial.chebyshev.Chebyshev.integ

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.identity

Next topic

numpy.polynomial.chebyshev.Chebyshev.linspace

numpy.polynomial.chebyshev.Chebyshev.integ

Chebyshev.integ(m=1, k=[], lbnd=None) [source]

Integrate.

Return a series instance that is the definite integral of the current series.

Parameters:

m : non-negative int

The number of integrations to perform.

k : array_like

Integration constants. The first constant is applied to the first integration, the second to the second, and so on. The list of values must less than or equal to m in length and any missing values are set to zero.

lbnd : Scalar

The lower bound of the definite integral.
Returns:

new_series : series

A new series representing the integral. The domain is the same as the domain of the integrated series.


numpy.polynomial.chebyshev.Chebyshev.linspace

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.integ

Next topic

numpy.polynomial.chebyshev.Chebyshev.mapparms

numpy.polynomial.chebyshev.Chebyshev.linspace

Chebyshev.linspace(n=100, domain=None) [source]

Return x, y values at equally spaced points in domain.

Returns the x, y values at n linearly spaced points across the domain. Here y is the value of the polynomial at the points x. By default the domain is the same as that of the series instance. This method is intended mostly as a plotting aid.

New in version 1.5.0.

Parameters:

n : int, optional

Number of point pairs to return. The default value is 100.

domain : {None, array_like}, optional

If not None, the specified domain is used instead of that of the calling instance. It should be of the form [beg,end]. The default is None which case the class domain is used.
Returns:

x, y : ndarray

x is equal to linspace(self.domain[0], self.domain[1], n) and y is the series evaluated at element of x.


numpy.polynomial.chebyshev.Chebyshev.mapparms

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.linspace

Next topic

numpy.polynomial.chebyshev.Chebyshev.roots

numpy.polynomial.chebyshev.Chebyshev.mapparms

Chebyshev.mapparms() [source]

Return the mapping parameters.

The returned values define a linear map off + scl*x that is applied to the input arguments before the series is evaluated. The map depends on the domain and window; if the current domain is equal to the window the resulting map is the identity. If the coefficients of the series instance are to be used by themselves outside this class, then the linear function must be substituted for the x in the standard representation of the base polynomials.

Returns:

off, scl : float or complex

The mapping function is defined by off + scl*x.

Notes

If the current domain is the interval [l1, r1] and the window is [l2, r2], then the linear mapping function L is defined by the equations:

L(l1) = l2
L(r1) = r2


numpy.polynomial.chebyshev.Chebyshev.roots

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.mapparms

Next topic

numpy.polynomial.chebyshev.Chebyshev.trim

numpy.polynomial.chebyshev.Chebyshev.roots

Chebyshev.roots() [source]

Return the roots of the series polynomial.

Compute the roots for the series. Note that the accuracy of the roots decrease the further outside the domain they lie.

Returns:

roots : ndarray

Array containing the roots of the series.


numpy.polynomial.chebyshev.Chebyshev.trim

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.roots

Next topic

numpy.polynomial.chebyshev.Chebyshev.truncate

numpy.polynomial.chebyshev.Chebyshev.trim

Chebyshev.trim(tol=0) [source]

Remove trailing coefficients

Remove trailing coefficients until a coefficient is reached whose absolute value greater than tol or the beginning of the series is reached. If all the coefficients would be removed the series is set to [0]. A new series instance is returned with the new coefficients. The current instance remains unchanged.

Parameters:

tol : non-negative number.

All trailing coefficients less than tol will be removed.
Returns:

new_series : series

Contains the new set of coefficients.


numpy.polynomial.chebyshev.Chebyshev.truncate

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • numpy.polynomial.chebyshev.Chebyshev
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.trim

Next topic

numpy.polynomial.chebyshev.chebval

numpy.polynomial.chebyshev.Chebyshev.truncate

Chebyshev.truncate(size) [source]

Truncate series to length size.

Reduce the series to length size by discarding the high degree terms. The value of size must be a positive integer. This can be useful in least squares where the coefficients of the high degree terms may be very small.

Parameters:

size : positive int

The series is reduced to length size by discarding the high degree terms. The value of size must be a positive integer.
Returns:

new_series : series

New instance of series with truncated coefficients.


numpy.polynomial.chebyshev.chebval

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.Chebyshev.truncate

Next topic

numpy.polynomial.chebyshev.chebval2d

numpy.polynomial.chebyshev.chebval

numpy.polynomial.chebyshev.chebval(x, c, tensor=True) [source]

Evaluate a Chebyshev series at points x.

If c is of length n + 1, this function returns the value:

p(x) = c_0 * T_0(x) + c_1 * T_1(x) + ... + c_n * T_n(x)

The parameter x is converted to an array only if it is a tuple or a list, otherwise it is treated as a scalar. In either case, either x or its elements must support multiplication and addition both with themselves and with the elements of c.

If c is a 1-D array, then p(x) will have the same shape as x. If c is multidimensional, then the shape of the result depends on the value of tensor. If tensor is true the shape will be c.shape[1:] + x.shape. If tensor is false the shape will be c.shape[1:]. Note that scalars have shape (,).

Trailing zeros in the coefficients will be used in the evaluation, so they should be avoided if efficiency is a concern.

Parameters:

x : array_like, compatible object

If x is a list or tuple, it is converted to an ndarray, otherwise it is left unchanged and treated as a scalar. In either case, x or its elements must support addition and multiplication with with themselves and with the elements of c.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree n are contained in c[n]. If c is multidimensional the remaining indices enumerate multiple polynomials. In the two dimensional case the coefficients may be thought of as stored in the columns of c.

tensor : boolean, optional

If True, the shape of the coefficient array is extended with ones on the right, one for each dimension of x. Scalars have dimension 0 for this action. The result is that every column of coefficients in c is evaluated for every element of x. If False, x is broadcast over the columns of c for the evaluation. This keyword is useful when c is multidimensional. The default value is True.

New in version 1.7.0.
Returns:

values : ndarray, algebra_like

The shape of the return value is described above.

See also

chebval2d, chebgrid2d, chebval3d, chebgrid3d

Notes

The evaluation uses Clenshaw recursion, aka synthetic division.


numpy.polynomial.chebyshev.chebval2d

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebval

Next topic

numpy.polynomial.chebyshev.chebval3d

numpy.polynomial.chebyshev.chebval2d

numpy.polynomial.chebyshev.chebval2d(x, y, c) [source]

Evaluate a 2-D Chebyshev series at points (x, y).

This function returns the values:

The parameters x and y are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars and they must have the same shape after conversion. In either case, either x and y or their elements must support multiplication and addition both with themselves and with the elements of c.

If c is a 1-D array a one is implicitly appended to its shape to make it 2-D. The shape of the result will be c.shape[2:] + x.shape.

Parameters:

x, y : array_like, compatible objects

The two dimensional series is evaluated at the points (x, y), where x and y must have the same shape. If x or y is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and if it isn’t an ndarray it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j is contained in c[i,j]. If c has dimension greater than 2 the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional Chebyshev series at points formed from pairs of corresponding values from x and y.

See also

chebval, chebgrid2d, chebval3d, chebgrid3d

Notes


numpy.polynomial.chebyshev.chebval3d

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebval2d

Next topic

numpy.polynomial.chebyshev.chebgrid2d

numpy.polynomial.chebyshev.chebval3d

numpy.polynomial.chebyshev.chebval3d(x, y, z, c) [source]

Evaluate a 3-D Chebyshev series at points (x, y, z).

This function returns the values:

The parameters x, y, and z are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars and they must have the same shape after conversion. In either case, either x, y, and z or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than 3 dimensions, ones are implicitly appended to its shape to make it 3-D. The shape of the result will be c.shape[3:] + x.shape.

Parameters:

x, y, z : array_like, compatible object

The three dimensional series is evaluated at the points (x, y, z), where x, y, and z must have the same shape. If any of x, y, or z is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and if it isn’t an ndarray it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j,k is contained in c[i,j,k]. If c has dimension greater than 3 the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the multidimensional polynomial on points formed with triples of corresponding values from x, y, and z.

See also

chebval, chebval2d, chebgrid2d, chebgrid3d

Notes


numpy.polynomial.chebyshev.chebgrid2d

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebval3d

Next topic

numpy.polynomial.chebyshev.chebgrid3d

numpy.polynomial.chebyshev.chebgrid2d

numpy.polynomial.chebyshev.chebgrid2d(x, y, c) [source]

Evaluate a 2-D Chebyshev series on the Cartesian product of x and y.

This function returns the values:

where the points (a, b) consist of all pairs formed by taking a from x and b from y. The resulting points form a grid with x in the first dimension and y in the second.

The parameters x and y are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars. In either case, either x and y or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than two dimensions, ones are implicitly appended to its shape to make it 2-D. The shape of the result will be c.shape[2:] + x.shape + y.shape.

Parameters:

x, y : array_like, compatible objects

The two dimensional series is evaluated at the points in the Cartesian product of x and y. If x or y is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and, if it isn’t an ndarray, it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j is contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional Chebyshev series at points in the Cartesian product of x and y.

See also

chebval, chebval2d, chebval3d, chebgrid3d

Notes


numpy.polynomial.chebyshev.chebgrid3d

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebgrid2d

Next topic

numpy.polynomial.chebyshev.chebroots

numpy.polynomial.chebyshev.chebgrid3d

numpy.polynomial.chebyshev.chebgrid3d(x, y, z, c) [source]

Evaluate a 3-D Chebyshev series on the Cartesian product of x, y, and z.

This function returns the values:

where the points (a, b, c) consist of all triples formed by taking a from x, b from y, and c from z. The resulting points form a grid with x in the first dimension, y in the second, and z in the third.

The parameters x, y, and z are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars. In either case, either x, y, and z or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than three dimensions, ones are implicitly appended to its shape to make it 3-D. The shape of the result will be c.shape[3:] + x.shape + y.shape + z.shape.

Parameters:

x, y, z : array_like, compatible objects

The three dimensional series is evaluated at the points in the Cartesian product of x, y, and z. If x,`y`, or z is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and, if it isn’t an ndarray, it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree i,j are contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional polynomial at points in the Cartesian product of x and y.

See also

chebval, chebval2d, chebgrid2d, chebval3d

Notes


numpy.polynomial.chebyshev.chebroots

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebgrid3d

Next topic

numpy.polynomial.chebyshev.chebfromroots

numpy.polynomial.chebyshev.chebroots

numpy.polynomial.chebyshev.chebroots(c) [source]

Compute the roots of a Chebyshev series.

Return the roots (a.k.a. “zeros”) of the polynomial

Parameters:

c : 1-D array_like

1-D array of coefficients.
Returns:

out : ndarray

Array of the roots of the series. If all the roots are real, then out is also real, otherwise it is complex.

See also

polyroots, legroots, lagroots, hermroots, hermeroots

Notes

The root estimates are obtained as the eigenvalues of the companion matrix, Roots far from the origin of the complex plane may have large errors due to the numerical instability of the series for such values. Roots with multiplicity greater than 1 will also show larger errors as the value of the series near such points is relatively insensitive to errors in the roots. Isolated roots near the origin can be improved by a few iterations of Newton’s method.

The Chebyshev series basis polynomials aren’t powers of x so the results of this function may seem unintuitive.

Examples

>>> import numpy.polynomial.chebyshev as cheb
>>> cheb.chebroots((-1, 1,-1, 1)) # T3 - T2 + T1 - T0 has real roots
array([ -5.00000000e-01,   2.60860684e-17,   1.00000000e+00])


numpy.polynomial.chebyshev.chebfromroots

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebroots

Next topic

numpy.polynomial.chebyshev.chebfit

numpy.polynomial.chebyshev.chebfromroots

numpy.polynomial.chebyshev.chebfromroots(roots) [source]

Generate a Chebyshev series with given roots.

The function returns the coefficients of the polynomial

p(x) = (x - r_0) * (x - r_1) * ... * (x - r_n),

in Chebyshev form, where the r_n are the roots specified in roots. If a zero has multiplicity n, then it must appear in roots n times. For instance, if 2 is a root of multiplicity three and 3 is a root of multiplicity 2, then roots looks something like [2, 2, 2, 3, 3]. The roots can appear in any order.

If the returned coefficients are c, then

p(x) = c_0 + c_1 * T_1(x) + ... + c_n * T_n(x)

The coefficient of the last term is not generally 1 for monic polynomials in Chebyshev form.

Parameters:

roots : array_like

Sequence containing the roots.
Returns:

out : ndarray

1-D array of coefficients. If all roots are real then out is a real array, if some of the roots are complex, then out is complex even if all the coefficients in the result are real (see Examples below).

See also

polyfromroots, legfromroots, lagfromroots, hermfromroots, hermefromroots.

Examples

>>> import numpy.polynomial.chebyshev as C
>>> C.chebfromroots((-1,0,1)) # x^3 - x relative to the standard basis
array([ 0.  , -0.25,  0.  ,  0.25])
>>> j = complex(0,1)
>>> C.chebfromroots((-j,j)) # x^2 + 1 relative to the standard basis
array([ 1.5+0.j,  0.0+0.j,  0.5+0.j])


numpy.polynomial.chebyshev.chebfit

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebfromroots

Next topic

numpy.polynomial.chebyshev.chebvander

numpy.polynomial.chebyshev.chebfit

numpy.polynomial.chebyshev.chebfit(x, y, deg, rcond=None, full=False, w=None) [source]

Least squares fit of Chebyshev series to data.

Return the coefficients of a Legendre series of degree deg that is the least squares fit to the data values y given at points x. If y is 1-D the returned coefficients will also be 1-D. If y is 2-D multiple fits are done, one for each column of y, and the resulting coefficients are stored in the corresponding columns of a 2-D return. The fitted polynomial(s) are in the form

p(x) = c_0 + c_1 * T_1(x) + ... + c_n * T_n(x),

where n is deg.

Parameters:

x : array_like, shape (M,)

x-coordinates of the M sample points (x[i], y[i]).

y : array_like, shape (M,) or (M, K)

y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column.

deg : int

Degree of the fitting series

rcond : float, optional

Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)*eps, where eps is the relative precision of the float type, about 2e-16 in most cases.

full : bool, optional

Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned.

w : array_like, shape (M,), optional

Weights. If not None, the contribution of each point (x[i],y[i]) to the fit is weighted by w[i]. Ideally the weights are chosen so that the errors of the products w[i]*y[i] all have the same variance. The default value is None.

New in version 1.5.0.
Returns:

coef : ndarray, shape (M,) or (M, K)

Chebyshev coefficients ordered from low to high. If y was 2-D, the coefficients for the data in column k of y are in column k.

[residuals, rank, singular_values, rcond] : list

These values are only returned if full = True

resid – sum of squared residuals of the least squares fit rank – the numerical rank of the scaled Vandermonde matrix sv – singular values of the scaled Vandermonde matrix rcond – value of rcond.

For more details, see linalg.lstsq.
Warns:

RankWarning

The rank of the coefficient matrix in the least-squares fit is deficient. The warning is only raised if full = False. The warnings can be turned off by

>>> import warnings
>>> warnings.simplefilter('ignore', RankWarning)

See also

polyfit, legfit, lagfit, hermfit, hermefit

chebval
Evaluates a Chebyshev series.
chebvander
Vandermonde matrix of Chebyshev series.
chebweight
Chebyshev weight function.
linalg.lstsq
Computes a least-squares fit from the matrix.
scipy.interpolate.UnivariateSpline
Computes spline fits.

Notes

The solution is the coefficients of the Chebyshev series p that minimizes the sum of the weighted squared errors

where [image] are the weights. This problem is solved by setting up as the (typically) overdetermined matrix equation

V(x) * c = w * y,

where V is the weighted pseudo Vandermonde matrix of x, c are the coefficients to be solved for, w are the weights, and y are the observed values. This equation is then solved using the singular value decomposition of V.

If some of the singular values of V are so small that they are neglected, then a RankWarning will be issued. This means that the coefficient values may be poorly determined. Using a lower order fit will usually get rid of the warning. The rcond parameter can also be set to a value smaller than its default, but the resulting fit may be spurious and have large contributions from roundoff error.

Fits using Chebyshev series are usually better conditioned than fits using power series, but much can depend on the distribution of the sample points and the smoothness of the data. If the quality of the fit is inadequate splines may be a good alternative.

References

[R60] Wikipedia, “Curve fitting”, http://en.wikipedia.org/wiki/Curve_fitting


numpy.polynomial.chebyshev.chebvander

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebfit

Next topic

numpy.polynomial.chebyshev.chebvander2d

numpy.polynomial.chebyshev.chebvander

numpy.polynomial.chebyshev.chebvander(x, deg) [source]

Pseudo-Vandermonde matrix of given degree.

Returns the pseudo-Vandermonde matrix of degree deg and sample points x. The pseudo-Vandermonde matrix is defined by

V[..., i] = T_i(x),

where 0 <= i <= deg. The leading indices of V index the elements of x and the last index is the degree of the Chebyshev polynomial.

If c is a 1-D array of coefficients of length n + 1 and V is the matrix V = chebvander(x, n), then np.dot(V, c) and chebval(x, c) are the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of Chebyshev series of the same degree and sample points.

Parameters:

x : array_like

Array of points. The dtype is converted to float64 or complex128 depending on whether any of the elements are complex. If x is scalar it is converted to a 1-D array.

deg : int

Degree of the resulting matrix.
Returns:

vander : ndarray

The pseudo Vandermonde matrix. The shape of the returned matrix is x.shape + (deg + 1,), where The last index is the degree of the corresponding Chebyshev polynomial. The dtype will be the same as the converted x.


numpy.polynomial.chebyshev.chebvander2d

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebvander

Next topic

numpy.polynomial.chebyshev.chebvander3d

numpy.polynomial.chebyshev.chebvander2d

numpy.polynomial.chebyshev.chebvander2d(x, y, deg) [source]

Pseudo-Vandermonde matrix of given degrees.

Returns the pseudo-Vandermonde matrix of degrees deg and sample points (x, y). The pseudo-Vandermonde matrix is defined by

V[..., deg[1]*i + j] = T_i(x) * T_j(y),

where 0 <= i <= deg[0] and 0 <= j <= deg[1]. The leading indices of V index the points (x, y) and the last index encodes the degrees of the Chebyshev polynomials.

If V = chebvander2d(x, y, [xdeg, ydeg]), then the columns of V correspond to the elements of a 2-D coefficient array c of shape (xdeg + 1, ydeg + 1) in the order

c_{00}, c_{01}, c_{02} ... , c_{10}, c_{11}, c_{12} ...

and np.dot(V, c.flat) and chebval2d(x, y, c) will be the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of 2-D Chebyshev series of the same degrees and sample points.

Parameters:

x, y : array_like

Arrays of point coordinates, all of the same shape. The dtypes will be converted to either float64 or complex128 depending on whether any of the elements are complex. Scalars are converted to 1-D arrays.

deg : list of ints

List of maximum degrees of the form [x_deg, y_deg].
Returns:

vander2d : ndarray

The shape of the returned matrix is x.shape + (order,), where order = (deg[0]+1)*(deg([1]+1). The dtype will be the same as the converted x and y.

See also

chebvander, chebvander3d., chebval3d

Notes


numpy.polynomial.chebyshev.chebvander3d

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebvander2d

Next topic

numpy.polynomial.chebyshev.chebder

numpy.polynomial.chebyshev.chebvander3d

numpy.polynomial.chebyshev.chebvander3d(x, y, z, deg) [source]

Pseudo-Vandermonde matrix of given degrees.

Returns the pseudo-Vandermonde matrix of degrees deg and sample points (x, y, z). If l, m, n are the given degrees in x, y, z, then The pseudo-Vandermonde matrix is defined by

V[..., (m+1)(n+1)i + (n+1)j + k] = T_i(x)*T_j(y)*T_k(z),

where 0 <= i <= l, 0 <= j <= m, and 0 <= j <= n. The leading indices of V index the points (x, y, z) and the last index encodes the degrees of the Chebyshev polynomials.

If V = chebvander3d(x, y, z, [xdeg, ydeg, zdeg]), then the columns of V correspond to the elements of a 3-D coefficient array c of shape (xdeg + 1, ydeg + 1, zdeg + 1) in the order

c_{000}, c_{001}, c_{002},... , c_{010}, c_{011}, c_{012},...

and np.dot(V, c.flat) and chebval3d(x, y, z, c) will be the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of 3-D Chebyshev series of the same degrees and sample points.

Parameters:

x, y, z : array_like

Arrays of point coordinates, all of the same shape. The dtypes will be converted to either float64 or complex128 depending on whether any of the elements are complex. Scalars are converted to 1-D arrays.

deg : list of ints

List of maximum degrees of the form [x_deg, y_deg, z_deg].
Returns:

vander3d : ndarray

The shape of the returned matrix is x.shape + (order,), where order = (deg[0]+1)*(deg([1]+1)*(deg[2]+1). The dtype will be the same as the converted x, y, and z.

See also

chebvander, chebvander3d., chebval3d

Notes


numpy.polynomial.chebyshev.chebder

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebvander3d

Next topic

numpy.polynomial.chebyshev.chebint

numpy.polynomial.chebyshev.chebder

numpy.polynomial.chebyshev.chebder(c, m=1, scl=1, axis=0) [source]

Differentiate a Chebyshev series.

Returns the Chebyshev series coefficients c differentiated m times along axis. At each iteration the result is multiplied by scl (the scaling factor is for use in a linear change of variable). The argument c is an array of coefficients from low to high degree along each axis, e.g., [1,2,3] represents the series 1*T_0 + 2*T_1 + 3*T_2 while [[1,2],[1,2]] represents 1*T_0(x)*T_0(y) + 1*T_1(x)*T_0(y) + 2*T_0(x)*T_1(y) + 2*T_1(x)*T_1(y) if axis=0 is x and axis=1 is y.

Parameters:

c : array_like

Array of Chebyshev series coefficients. If c is multidimensional the different axis correspond to different variables with the degree in each axis given by the corresponding index.

m : int, optional

Number of derivatives taken, must be non-negative. (Default: 1)

scl : scalar, optional

Each differentiation is multiplied by scl. The end result is multiplication by scl**m. This is for use in a linear change of variable. (Default: 1)

axis : int, optional

Axis over which the derivative is taken. (Default: 0).

New in version 1.7.0.
Returns:

der : ndarray

Chebyshev series of the derivative.

See also

chebint

Notes

In general, the result of differentiating a C-series needs to be “reprojected” onto the C-series basis set. Thus, typically, the result of this function is “unintuitive,” albeit correct; see Examples section below.

Examples

>>> from numpy.polynomial import chebyshev as C
>>> c = (1,2,3,4)
>>> C.chebder(c)
array([ 14.,  12.,  24.])
>>> C.chebder(c,3)
array([ 96.])
>>> C.chebder(c,scl=-1)
array([-14., -12., -24.])
>>> C.chebder(c,2,-1)
array([ 12.,  96.])


numpy.polynomial.chebyshev.chebint

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebder

Next topic

numpy.polynomial.chebyshev.chebadd

numpy.polynomial.chebyshev.chebint

numpy.polynomial.chebyshev.chebint(c, m=1, k=[], lbnd=0, scl=1, axis=0) [source]

Integrate a Chebyshev series.

Returns the Chebyshev series coefficients c integrated m times from lbnd along axis. At each iteration the resulting series is multiplied by scl and an integration constant, k, is added. The scaling factor is for use in a linear change of variable. (“Buyer beware”: note that, depending on what one is doing, one may want scl to be the reciprocal of what one might expect; for more information, see the Notes section below.) The argument c is an array of coefficients from low to high degree along each axis, e.g., [1,2,3] represents the series T_0 + 2*T_1 + 3*T_2 while [[1,2],[1,2]] represents 1*T_0(x)*T_0(y) + 1*T_1(x)*T_0(y) + 2*T_0(x)*T_1(y) + 2*T_1(x)*T_1(y) if axis=0 is x and axis=1 is y.

Parameters:

c : array_like

Array of Chebyshev series coefficients. If c is multidimensional the different axis correspond to different variables with the degree in each axis given by the corresponding index.

m : int, optional

Order of integration, must be positive. (Default: 1)

k : {[], list, scalar}, optional

Integration constant(s). The value of the first integral at zero is the first value in the list, the value of the second integral at zero is the second value, etc. If k == [] (the default), all constants are set to zero. If m == 1, a single scalar can be given instead of a list.

lbnd : scalar, optional

The lower bound of the integral. (Default: 0)

scl : scalar, optional

Following each integration the result is multiplied by scl before the integration constant is added. (Default: 1)

axis : int, optional

Axis over which the integral is taken. (Default: 0).

New in version 1.7.0.
Returns:

S : ndarray

C-series coefficients of the integral.
Raises:

ValueError

If m < 1, len(k) > m, np.isscalar(lbnd) == False, or np.isscalar(scl) == False.

See also

chebder

Notes

Note that the result of each integration is multiplied by scl. Why is this important to note? Say one is making a linear change of variable u = ax + b in an integral relative to x. Then .. math::dx = du/a, so one will need to set scl equal to 1/a - perhaps not what one would have first thought.

Also note that, in general, the result of integrating a C-series needs to be “reprojected” onto the C-series basis set. Thus, typically, the result of this function is “unintuitive,” albeit correct; see Examples section below.

Examples

>>> from numpy.polynomial import chebyshev as C
>>> c = (1,2,3)
>>> C.chebint(c)
array([ 0.5, -0.5,  0.5,  0.5])
>>> C.chebint(c,3)
array([ 0.03125   , -0.1875    ,  0.04166667, -0.05208333,  0.01041667,
        0.00625   ])
>>> C.chebint(c, k=3)
array([ 3.5, -0.5,  0.5,  0.5])
>>> C.chebint(c,lbnd=-2)
array([ 8.5, -0.5,  0.5,  0.5])
>>> C.chebint(c,scl=-2)
array([-1.,  1., -1., -1.])


numpy.polynomial.chebyshev.chebadd

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebint

Next topic

numpy.polynomial.chebyshev.chebsub

numpy.polynomial.chebyshev.chebadd

numpy.polynomial.chebyshev.chebadd(c1, c2) [source]

Add one Chebyshev series to another.

Returns the sum of two Chebyshev series c1 + c2. The arguments are sequences of coefficients ordered from lowest order term to highest, i.e., [1,2,3] represents the series T_0 + 2*T_1 + 3*T_2.

Parameters:

c1, c2 : array_like

1-D arrays of Chebyshev series coefficients ordered from low to high.
Returns:

out : ndarray

Array representing the Chebyshev series of their sum.

See also

chebsub, chebmul, chebdiv, chebpow

Notes

Unlike multiplication, division, etc., the sum of two Chebyshev series is a Chebyshev series (without having to “reproject” the result onto the basis set) so addition, just like that of “standard” polynomials, is simply “component-wise.”

Examples

>>> from numpy.polynomial import chebyshev as C
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
>>> C.chebadd(c1,c2)
array([ 4.,  4.,  4.])


numpy.polynomial.chebyshev.chebsub

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebadd

Next topic

numpy.polynomial.chebyshev.chebmul

numpy.polynomial.chebyshev.chebsub

numpy.polynomial.chebyshev.chebsub(c1, c2) [source]

Subtract one Chebyshev series from another.

Returns the difference of two Chebyshev series c1 - c2. The sequences of coefficients are from lowest order term to highest, i.e., [1,2,3] represents the series T_0 + 2*T_1 + 3*T_2.

Parameters:

c1, c2 : array_like

1-D arrays of Chebyshev series coefficients ordered from low to high.
Returns:

out : ndarray

Of Chebyshev series coefficients representing their difference.

See also

chebadd, chebmul, chebdiv, chebpow

Notes

Unlike multiplication, division, etc., the difference of two Chebyshev series is a Chebyshev series (without having to “reproject” the result onto the basis set) so subtraction, just like that of “standard” polynomials, is simply “component-wise.”

Examples

>>> from numpy.polynomial import chebyshev as C
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
>>> C.chebsub(c1,c2)
array([-2.,  0.,  2.])
>>> C.chebsub(c2,c1) # -C.chebsub(c1,c2)
array([ 2.,  0., -2.])


numpy.polynomial.chebyshev.chebmul

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebsub

Next topic

numpy.polynomial.chebyshev.chebmulx

numpy.polynomial.chebyshev.chebmul

numpy.polynomial.chebyshev.chebmul(c1, c2) [source]

Multiply one Chebyshev series by another.

Returns the product of two Chebyshev series c1 * c2. The arguments are sequences of coefficients, from lowest order “term” to highest, e.g., [1,2,3] represents the series T_0 + 2*T_1 + 3*T_2.

Parameters:

c1, c2 : array_like

1-D arrays of Chebyshev series coefficients ordered from low to high.
Returns:

out : ndarray

Of Chebyshev series coefficients representing their product.

See also

chebadd, chebsub, chebdiv, chebpow

Notes

In general, the (polynomial) product of two C-series results in terms that are not in the Chebyshev polynomial basis set. Thus, to express the product as a C-series, it is typically necessary to “reproject” the product onto said basis set, which typically produces “unintuitive live” (but correct) results; see Examples section below.

Examples

>>> from numpy.polynomial import chebyshev as C
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
>>> C.chebmul(c1,c2) # multiplication requires "reprojection"
array([  6.5,  12. ,  12. ,   4. ,   1.5])


numpy.polynomial.chebyshev.chebmulx

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebmul

Next topic

numpy.polynomial.chebyshev.chebdiv

numpy.polynomial.chebyshev.chebmulx

numpy.polynomial.chebyshev.chebmulx(c) [source]

Multiply a Chebyshev series by x.

Multiply the polynomial c by x, where x is the independent variable.

Parameters:

c : array_like

1-D array of Chebyshev series coefficients ordered from low to high.
Returns:

out : ndarray

Array representing the result of the multiplication.

Notes

New in version 1.5.0.


numpy.polynomial.chebyshev.chebdiv

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebmulx

Next topic

numpy.polynomial.chebyshev.chebpow

numpy.polynomial.chebyshev.chebdiv

numpy.polynomial.chebyshev.chebdiv(c1, c2) [source]

Divide one Chebyshev series by another.

Returns the quotient-with-remainder of two Chebyshev series c1 / c2. The arguments are sequences of coefficients from lowest order “term” to highest, e.g., [1,2,3] represents the series T_0 + 2*T_1 + 3*T_2.

Parameters:

c1, c2 : array_like

1-D arrays of Chebyshev series coefficients ordered from low to high.
Returns:

[quo, rem] : ndarrays

Of Chebyshev series coefficients representing the quotient and remainder.

See also

chebadd, chebsub, chebmul, chebpow

Notes

In general, the (polynomial) division of one C-series by another results in quotient and remainder terms that are not in the Chebyshev polynomial basis set. Thus, to express these results as C-series, it is typically necessary to “reproject” the results onto said basis set, which typically produces “unintuitive” (but correct) results; see Examples section below.

Examples

>>> from numpy.polynomial import chebyshev as C
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
>>> C.chebdiv(c1,c2) # quotient "intuitive," remainder not
(array([ 3.]), array([-8., -4.]))
>>> c2 = (0,1,2,3)
>>> C.chebdiv(c2,c1) # neither "intuitive"
(array([ 0.,  2.]), array([-2., -4.]))


numpy.polynomial.chebyshev.chebpow

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebdiv

Next topic

numpy.polynomial.chebyshev.chebgauss

numpy.polynomial.chebyshev.chebpow

numpy.polynomial.chebyshev.chebpow(c, pow, maxpower=16) [source]

Raise a Chebyshev series to a power.

Returns the Chebyshev series c raised to the power pow. The argument c is a sequence of coefficients ordered from low to high. i.e., [1,2,3] is the series T_0 + 2*T_1 + 3*T_2.

Parameters:

c : array_like

1-D array of Chebyshev series coefficients ordered from low to high.

pow : integer

Power to which the series will be raised

maxpower : integer, optional

Maximum power allowed. This is mainly to limit growth of the series to unmanageable size. Default is 16
Returns:

coef : ndarray

Chebyshev series of power.

See also

chebadd, chebsub, chebmul, chebdiv


numpy.polynomial.chebyshev.chebgauss

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebpow

Next topic

numpy.polynomial.chebyshev.chebweight

numpy.polynomial.chebyshev.chebgauss

numpy.polynomial.chebyshev.chebgauss(deg) [source]

Gauss-Chebyshev quadrature.

Computes the sample points and weights for Gauss-Chebyshev quadrature. These sample points and weights will correctly integrate polynomials of degree 2*deg - 1 or less over the interval [-1, 1] with the weight function [image].

Parameters:

deg : int

Number of sample points and weights. It must be >= 1.
Returns:

x : ndarray

1-D ndarray containing the sample points.

y : ndarray

1-D ndarray containing the weights.

Notes

New in version 1.7.0.

The results have only been tested up to degree 100, higher degrees may be problematic. For Gauss-Chebyshev there are closed form solutions for the sample points and weights. If n = deg, then


numpy.polynomial.chebyshev.chebweight

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebgauss

Next topic

numpy.polynomial.chebyshev.chebcompanion

numpy.polynomial.chebyshev.chebweight

numpy.polynomial.chebyshev.chebweight(x) [source]

The weight function of the Chebyshev polynomials.

The weight function is [image] and the interval of integration is [-1, 1]. The Chebyshev polynomials are orthogonal, but not normalized, with respect to this weight function.

Parameters:

x : array_like

Values at which the weight function will be computed.
Returns:

w : ndarray

The weight function at x.

Notes

New in version 1.7.0.


numpy.polynomial.chebyshev.chebcompanion

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebweight

Next topic

numpy.polynomial.chebyshev.chebdomain

numpy.polynomial.chebyshev.chebcompanion

numpy.polynomial.chebyshev.chebcompanion(c) [source]

Return the scaled companion matrix of c.

The basis polynomials are scaled so that the companion matrix is symmetric when c is aa Chebyshev basis polynomial. This provides better eigenvalue estimates than the unscaled case and for basis polynomials the eigenvalues are guaranteed to be real if numpy.linalg.eigvalsh is used to obtain them.

Parameters:

c : array_like

1-D array of Chebyshev series coefficients ordered from low to high degree.
Returns:

mat : ndarray

Scaled companion matrix of dimensions (deg, deg).

Notes


numpy.polynomial.chebyshev.chebdomain

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebcompanion

Next topic

numpy.polynomial.chebyshev.chebzero

numpy.polynomial.chebyshev.chebdomain

numpy.polynomial.chebyshev.chebdomain = array([-1, 1])


numpy.polynomial.chebyshev.chebzero

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebdomain

Next topic

numpy.polynomial.chebyshev.chebone

numpy.polynomial.chebyshev.chebzero

numpy.polynomial.chebyshev.chebzero = array([0])


numpy.polynomial.chebyshev.chebone

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebzero

Next topic

numpy.polynomial.chebyshev.chebx

numpy.polynomial.chebyshev.chebone

numpy.polynomial.chebyshev.chebone = array([1])


numpy.polynomial.chebyshev.chebx

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebone

Next topic

numpy.polynomial.chebyshev.chebtrim

numpy.polynomial.chebyshev.chebx

numpy.polynomial.chebyshev.chebx = array([0, 1])


numpy.polynomial.chebyshev.chebtrim

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebx

Next topic

numpy.polynomial.chebyshev.chebline

numpy.polynomial.chebyshev.chebtrim

numpy.polynomial.chebyshev.chebtrim(c, tol=0) [source]

Remove “small” “trailing” coefficients from a polynomial.

“Small” means “small in absolute value” and is controlled by the parameter tol; “trailing” means highest order coefficient(s), e.g., in [0, 1, 1, 0, 0] (which represents 0 + x + x**2 + 0*x**3 + 0*x**4) both the 3-rd and 4-th order coefficients would be “trimmed.”

Parameters:

c : array_like

1-d array of coefficients, ordered from lowest order to highest.

tol : number, optional

Trailing (i.e., highest order) elements with absolute value less than or equal to tol (default value is zero) are removed.
Returns:

trimmed : ndarray

1-d array with trailing zeros removed. If the resulting series would be empty, a series containing a single zero is returned.
Raises:

ValueError

If tol < 0

See also

trimseq

Examples

>>> from numpy import polynomial as P
>>> P.trimcoef((0,0,3,0,5,0,0))
array([ 0.,  0.,  3.,  0.,  5.])
>>> P.trimcoef((0,0,1e-3,0,1e-5,0,0),1e-3) # item == tol is trimmed
array([ 0.])
>>> i = complex(0,1) # works for complex
>>> P.trimcoef((3e-4,1e-3*(1-i),5e-4,2e-5*(1+i)), 1e-3)
array([ 0.0003+0.j   ,  0.0010-0.001j])


numpy.polynomial.chebyshev.chebline

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebtrim

Next topic

numpy.polynomial.chebyshev.cheb2poly

numpy.polynomial.chebyshev.chebline

numpy.polynomial.chebyshev.chebline(off, scl) [source]

Chebyshev series whose graph is a straight line.

Parameters:

off, scl : scalars

The specified line is given by off + scl*x.
Returns:

y : ndarray

This module’s representation of the Chebyshev series for off + scl*x.

See also

polyline

Examples

>>> import numpy.polynomial.chebyshev as C
>>> C.chebline(3,2)
array([3, 2])
>>> C.chebval(-3, C.chebline(3,2)) # should be -3
-3.0


numpy.polynomial.chebyshev.cheb2poly

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.chebline

Next topic

numpy.polynomial.chebyshev.poly2cheb

numpy.polynomial.chebyshev.cheb2poly

numpy.polynomial.chebyshev.cheb2poly(c) [source]

Convert a Chebyshev series to a polynomial.

Convert an array representing the coefficients of a Chebyshev series, ordered from lowest degree to highest, to an array of the coefficients of the equivalent polynomial (relative to the “standard” basis) ordered from lowest to highest degree.

Parameters:

c : array_like

1-D array containing the Chebyshev series coefficients, ordered from lowest order term to highest.
Returns:

pol : ndarray

1-D array containing the coefficients of the equivalent polynomial (relative to the “standard” basis) ordered from lowest order term to highest.

See also

poly2cheb

Notes

The easy way to do conversions between polynomial basis sets is to use the convert method of a class instance.

Examples

>>> from numpy import polynomial as P
>>> c = P.Chebyshev(range(4))
>>> c
Chebyshev([ 0.,  1.,  2.,  3.], [-1.,  1.])
>>> p = c.convert(kind=P.Polynomial)
>>> p
Polynomial([ -2.,  -8.,   4.,  12.], [-1.,  1.])
>>> P.cheb2poly(range(4))
array([ -2.,  -8.,   4.,  12.])


numpy.polynomial.chebyshev.poly2cheb

  • Polynomials
  • Polynomial Package
  • Chebyshev Module (numpy.polynomial.chebyshev)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.chebyshev.cheb2poly

Next topic

Legendre Module (numpy.polynomial.legendre)

numpy.polynomial.chebyshev.poly2cheb

numpy.polynomial.chebyshev.poly2cheb(pol) [source]

Convert a polynomial to a Chebyshev series.

Convert an array representing the coefficients of a polynomial (relative to the “standard” basis) ordered from lowest degree to highest, to an array of the coefficients of the equivalent Chebyshev series, ordered from lowest to highest degree.

Parameters:

pol : array_like

1-D array containing the polynomial coefficients
Returns:

c : ndarray

1-D array containing the coefficients of the equivalent Chebyshev series.

See also

cheb2poly

Notes

The easy way to do conversions between polynomial basis sets is to use the convert method of a class instance.

Examples

>>> from numpy import polynomial as P
>>> p = P.Polynomial(range(4))
>>> p
Polynomial([ 0.,  1.,  2.,  3.], [-1.,  1.])
>>> c = p.convert(kind=P.Chebyshev)
>>> c
Chebyshev([ 1.  ,  3.25,  1.  ,  0.75], [-1.,  1.])
>>> P.poly2cheb(range(4))
array([ 1.  ,  3.25,  1.  ,  0.75])


Legendre Module (numpy.polynomial.legendre)

  • Polynomials
  • Polynomial Package
  • index
  • next
  • previous

Table Of Contents

  • Legendre Module (numpy.polynomial.legendre)
    • Legendre Class
    • Basics
    • Fitting
    • Calculus
    • Algebra
    • Quadrature
    • Miscellaneous

Previous topic

numpy.polynomial.chebyshev.poly2cheb

Next topic

numpy.polynomial.legendre.Legendre

Legendre Module (numpy.polynomial.legendre)

New in version 1.6.0.

This module provides a number of objects (mostly functions) useful for dealing with Legendre series, including a Legendre class that encapsulates the usual arithmetic operations. (General information on how this module represents and works with such polynomials is in the docstring for its “parent” sub-package, numpy.polynomial).

Legendre Class

Legendre(coef[, domain, window]) A Legendre series class.

Basics

legval(x, c[, tensor]) | Evaluate a Legendre series at points x.
legval2d(x, y, c) | Evaluate a 2-D Legendre series at points (x, y).
legval3d(x, y, z, c) | Evaluate a 3-D Legendre series at points (x, y, z).
leggrid2d(x, y, c) | Evaluate a 2-D Legendre series on the Cartesian product of x and y.
leggrid3d(x, y, z, c) | Evaluate a 3-D Legendre series on the Cartesian product of x, y, and z.
legroots(c) | Compute the roots of a Legendre series.
legfromroots(roots) | Generate a Legendre series with given roots.

Fitting

legfit(x, y, deg[, rcond, full, w]) | Least squares fit of Legendre series to data.
legvander(x, deg) | Pseudo-Vandermonde matrix of given degree.
legvander2d(x, y, deg) | Pseudo-Vandermonde matrix of given degrees.
legvander3d(x, y, z, deg) | Pseudo-Vandermonde matrix of given degrees.

Calculus

legder(c[, m, scl, axis]) | Differentiate a Legendre series.
legint(c[, m, k, lbnd, scl, axis]) | Integrate a Legendre series.

Algebra

legadd(c1, c2) | Add one Legendre series to another.
legsub(c1, c2) | Subtract one Legendre series from another.
legmul(c1, c2) | Multiply one Legendre series by another.
legmulx(c) | Multiply a Legendre series by x.
legdiv(c1, c2) | Divide one Legendre series by another.
legpow(c, pow[, maxpower]) | Raise a Legendre series to a power.

Quadrature

leggauss(deg) | Gauss-Legendre quadrature.
legweight(x) | Weight function of the Legendre polynomials.

Miscellaneous

legcompanion(c) | Return the scaled companion matrix of c.
legdomain |
legzero |
legone |
legx |
legtrim(c[, tol]) | Remove “small” “trailing” coefficients from a polynomial.
legline(off, scl) | Legendre series whose graph is a straight line.
leg2poly(c) | Convert a Legendre series to a polynomial.
poly2leg(pol) | Convert a polynomial to a Legendre series.


numpy.polynomial.legendre.Legendre

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.poly2leg

Next topic

numpy.polynomial.legendre.Legendre.__call__

numpy.polynomial.legendre.Legendre

class numpy.polynomial.legendre.Legendre(coef, domain=None, window=None) [source]

A Legendre series class.

The Legendre class provides the standard Python numerical methods ‘+’, ‘-‘, ‘*’, ‘//’, ‘%’, ‘divmod’, ‘**’, and ‘()’ as well as the attributes and methods listed in the ABCPolyBase documentation.

Parameters:

coef : array_like

Legendre coefficients in order of increasing degree, i.e., (1, 2, 3) gives 1*P_0(x) + 2*P_1(x) + 3*P_2(x).

domain : (2,) array_like, optional

Domain to use. The interval [domain[0], domain[1]] is mapped to the interval [window[0], window[1]] by shifting and scaling. The default value is [-1, 1].

window : (2,) array_like, optional

Window, see domain for its use. The default value is [-1, 1].

New in version 1.6.0.

Methods

__call__(arg)
basis(deg[, domain, window]) | Series basis polynomial of degree deg.
cast(series[, domain, window]) | Convert series to series of this class.
convert([domain, kind, window]) | Convert series to a different kind and/or domain and/or window.
copy() | Return a copy.
cutdeg(deg) | Truncate series to the given degree.
degree() | The degree of the series.
deriv([m]) | Differentiate.
fit(x, y, deg[, domain, rcond, full, w, window]) | Least squares fit to data.
fromroots(roots[, domain, window]) | Return series instance that has the specified roots.
has_samecoef(other) | Check if coefficients match.
has_samedomain(other) | Check if domains match.
has_sametype(other) | Check if types match.
has_samewindow(other) | Check if windows match.
identity([domain, window]) | Identity function.
integ([m, k, lbnd]) | Integrate.
linspace([n, domain]) | Return x, y values at equally spaced points in domain.
mapparms() | Return the mapping parameters.
roots() | Return the roots of the series polynomial.
trim([tol]) | Remove trailing coefficients
truncate(size) | Truncate series to length size.


numpy.polynomial.legendre.Legendre.__call__

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre

Next topic

numpy.polynomial.legendre.Legendre.basis

numpy.polynomial.legendre.Legendre.__call__

Legendre.__call__(arg) [source]


numpy.polynomial.legendre.Legendre.basis

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.__call__

Next topic

numpy.polynomial.legendre.Legendre.cast

numpy.polynomial.legendre.Legendre.basis

classmethod Legendre.basis(deg, domain=None, window=None) [source]

Series basis polynomial of degree deg.

Returns the series representing the basis polynomial of degree deg.

New in version 1.7.0.

Parameters:

deg : int

Degree of the basis polynomial for the series. Must be >= 0.

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

A series with the coefficient of the deg term set to one and all others zero.


numpy.polynomial.legendre.Legendre.cast

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.basis

Next topic

numpy.polynomial.legendre.Legendre.convert

numpy.polynomial.legendre.Legendre.cast

classmethod Legendre.cast(series, domain=None, window=None) [source]

Convert series to series of this class.

The series is expected to be an instance of some polynomial series of one of the types supported by by the numpy.polynomial module, but could be some other class that supports the convert method.

New in version 1.7.0.

Parameters:

series : series

The series instance to be converted.

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

A series of the same kind as the calling class and equal to series when evaluated.

See also

convert
similar instance method


numpy.polynomial.legendre.Legendre.convert

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.cast

Next topic

numpy.polynomial.legendre.Legendre.copy

numpy.polynomial.legendre.Legendre.convert

Legendre.convert(domain=None, kind=None, window=None) [source]

Convert series to a different kind and/or domain and/or window.

Parameters:

domain : array_like, optional

The domain of the converted series. If the value is None, the default domain of kind is used.

kind : class, optional

The polynomial series type class to which the current instance should be converted. If kind is None, then the class of the current instance is used.

window : array_like, optional

The window of the converted series. If the value is None, the default window of kind is used.
Returns:

new_series : series

The returned class can be of different type than the current instance and/or have a different domain and/or different window.

Notes

Conversion between domains and class types can result in numerically ill defined series.


numpy.polynomial.legendre.Legendre.copy

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.convert

Next topic

numpy.polynomial.legendre.Legendre.cutdeg

numpy.polynomial.legendre.Legendre.copy

Legendre.copy() [source]

Return a copy.

Returns:

new_series : series

Copy of self.


numpy.polynomial.legendre.Legendre.cutdeg

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.copy

Next topic

numpy.polynomial.legendre.Legendre.degree

numpy.polynomial.legendre.Legendre.cutdeg

Legendre.cutdeg(deg) [source]

Truncate series to the given degree.

Reduce the degree of the series to deg by discarding the high order terms. If deg is greater than the current degree a copy of the current series is returned. This can be useful in least squares where the coefficients of the high degree terms may be very small.

New in version 1.5.0.

Parameters:

deg : non-negative int

The series is reduced to degree deg by discarding the high order terms. The value of deg must be a non-negative integer.
Returns:

new_series : series

New instance of series with reduced degree.


numpy.polynomial.legendre.Legendre.degree

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.cutdeg

Next topic

numpy.polynomial.legendre.Legendre.deriv

numpy.polynomial.legendre.Legendre.degree

Legendre.degree() [source]

The degree of the series.

New in version 1.5.0.

Returns:

degree : int

Degree of the series, one less than the number of coefficients.


numpy.polynomial.legendre.Legendre.deriv

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.degree

Next topic

numpy.polynomial.legendre.Legendre.fit

numpy.polynomial.legendre.Legendre.deriv

Legendre.deriv(m=1) [source]

Differentiate.

Return a series instance of that is the derivative of the current series.

Parameters:

m : non-negative int

The number of integrations to perform.
Returns:

new_series : series

A new series representing the derivative. The domain is the same as the domain of the differentiated series.


numpy.polynomial.legendre.Legendre.fit

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.deriv

Next topic

numpy.polynomial.legendre.Legendre.fromroots

numpy.polynomial.legendre.Legendre.fit

classmethod Legendre.fit(x, y, deg, domain=None, rcond=None, full=False, w=None, window=None) [source]

Least squares fit to data.

Return a series instance that is the least squares fit to the data y sampled at x. The domain of the returned instance can be specified and this will often result in a superior fit with less chance of ill conditioning.

Parameters:

x : array_like, shape (M,)

x-coordinates of the M sample points (x[i], y[i]).

y : array_like, shape (M,) or (M, K)

y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column.

deg : int

Degree of the fitting polynomial.

domain : {None, [beg, end], []}, optional

Domain to use for the returned series. If None, then a minimal domain that covers the points x is chosen. If [] the class domain is used. The default value was the class domain in NumPy 1.4 and None in later versions. The [] option was added in numpy 1.5.0.

rcond : float, optional

Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)*eps, where eps is the relative precision of the float type, about 2e-16 in most cases.

full : bool, optional

Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned.

w : array_like, shape (M,), optional

Weights. If not None the contribution of each point (x[i],y[i]) to the fit is weighted by w[i]. Ideally the weights are chosen so that the errors of the products w[i]*y[i] all have the same variance. The default value is None.

New in version 1.5.0.

window : {[beg, end]}, optional

Window to use for the returned series. The default value is the default class domain

New in version 1.6.0.
Returns:

new_series : series

A series that represents the least squares fit to the data and has the domain specified in the call.

[resid, rank, sv, rcond] : list

These values are only returned if full = True

resid – sum of squared residuals of the least squares fit rank – the numerical rank of the scaled Vandermonde matrix sv – singular values of the scaled Vandermonde matrix rcond – value of rcond.

For more details, see linalg.lstsq.


numpy.polynomial.legendre.Legendre.fromroots

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.fit

Next topic

numpy.polynomial.legendre.Legendre.has_samecoef

numpy.polynomial.legendre.Legendre.fromroots

classmethod Legendre.fromroots(roots, domain=[], window=None) [source]

Return series instance that has the specified roots.

Returns a series representing the product (x - r[0])*(x - r[1])*...*(x - r[n-1]), where r is a list of roots.

Parameters:

roots : array_like

List of roots.

domain : {[], None, array_like}, optional

Domain for the resulting series. If None the domain is the interval from the smallest root to the largest. If [] the domain is the class domain. The default is [].

window : {None, array_like}, optional

Window for the returned series. If None the class window is used. The default is None.
Returns:

new_series : series

Series with the specified roots.


numpy.polynomial.legendre.Legendre.has_samecoef

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.fromroots

Next topic

numpy.polynomial.legendre.Legendre.has_samedomain

numpy.polynomial.legendre.Legendre.has_samecoef

Legendre.has_samecoef(other) [source]

Check if coefficients match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the coef attribute.
Returns:

bool : boolean

True if the coefficients are the same, False otherwise.


numpy.polynomial.legendre.Legendre.has_samedomain

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.has_samecoef

Next topic

numpy.polynomial.legendre.Legendre.has_sametype

numpy.polynomial.legendre.Legendre.has_samedomain

Legendre.has_samedomain(other) [source]

Check if domains match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the domain attribute.
Returns:

bool : boolean

True if the domains are the same, False otherwise.


numpy.polynomial.legendre.Legendre.has_sametype

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.has_samedomain

Next topic

numpy.polynomial.legendre.Legendre.has_samewindow

numpy.polynomial.legendre.Legendre.has_sametype

Legendre.has_sametype(other) [source]

Check if types match.

New in version 1.7.0.

Parameters:

other : object

Class instance.
Returns:

bool : boolean

True if other is same class as self


numpy.polynomial.legendre.Legendre.has_samewindow

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.has_sametype

Next topic

numpy.polynomial.legendre.Legendre.identity

numpy.polynomial.legendre.Legendre.has_samewindow

Legendre.has_samewindow(other) [source]

Check if windows match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the window attribute.
Returns:

bool : boolean

True if the windows are the same, False otherwise.


numpy.polynomial.legendre.Legendre.identity

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.has_samewindow

Next topic

numpy.polynomial.legendre.Legendre.integ

numpy.polynomial.legendre.Legendre.identity

classmethod Legendre.identity(domain=None, window=None) [source]

Identity function.

If p is the returned series, then p(x) == x for all values of x.

Parameters:

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

Series of representing the identity.


numpy.polynomial.legendre.Legendre.integ

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.identity

Next topic

numpy.polynomial.legendre.Legendre.linspace

numpy.polynomial.legendre.Legendre.integ

Legendre.integ(m=1, k=[], lbnd=None) [source]

Integrate.

Return a series instance that is the definite integral of the current series.

Parameters:

m : non-negative int

The number of integrations to perform.

k : array_like

Integration constants. The first constant is applied to the first integration, the second to the second, and so on. The list of values must less than or equal to m in length and any missing values are set to zero.

lbnd : Scalar

The lower bound of the definite integral.
Returns:

new_series : series

A new series representing the integral. The domain is the same as the domain of the integrated series.


numpy.polynomial.legendre.Legendre.linspace

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.integ

Next topic

numpy.polynomial.legendre.Legendre.mapparms

numpy.polynomial.legendre.Legendre.linspace

Legendre.linspace(n=100, domain=None) [source]

Return x, y values at equally spaced points in domain.

Returns the x, y values at n linearly spaced points across the domain. Here y is the value of the polynomial at the points x. By default the domain is the same as that of the series instance. This method is intended mostly as a plotting aid.

New in version 1.5.0.

Parameters:

n : int, optional

Number of point pairs to return. The default value is 100.

domain : {None, array_like}, optional

If not None, the specified domain is used instead of that of the calling instance. It should be of the form [beg,end]. The default is None which case the class domain is used.
Returns:

x, y : ndarray

x is equal to linspace(self.domain[0], self.domain[1], n) and y is the series evaluated at element of x.


numpy.polynomial.legendre.Legendre.mapparms

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.linspace

Next topic

numpy.polynomial.legendre.Legendre.roots

numpy.polynomial.legendre.Legendre.mapparms

Legendre.mapparms() [source]

Return the mapping parameters.

The returned values define a linear map off + scl*x that is applied to the input arguments before the series is evaluated. The map depends on the domain and window; if the current domain is equal to the window the resulting map is the identity. If the coefficients of the series instance are to be used by themselves outside this class, then the linear function must be substituted for the x in the standard representation of the base polynomials.

Returns:

off, scl : float or complex

The mapping function is defined by off + scl*x.

Notes

If the current domain is the interval [l1, r1] and the window is [l2, r2], then the linear mapping function L is defined by the equations:

L(l1) = l2
L(r1) = r2


numpy.polynomial.legendre.Legendre.roots

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.mapparms

Next topic

numpy.polynomial.legendre.Legendre.trim

numpy.polynomial.legendre.Legendre.roots

Legendre.roots() [source]

Return the roots of the series polynomial.

Compute the roots for the series. Note that the accuracy of the roots decrease the further outside the domain they lie.

Returns:

roots : ndarray

Array containing the roots of the series.


numpy.polynomial.legendre.Legendre.trim

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.roots

Next topic

numpy.polynomial.legendre.Legendre.truncate

numpy.polynomial.legendre.Legendre.trim

Legendre.trim(tol=0) [source]

Remove trailing coefficients

Remove trailing coefficients until a coefficient is reached whose absolute value greater than tol or the beginning of the series is reached. If all the coefficients would be removed the series is set to [0]. A new series instance is returned with the new coefficients. The current instance remains unchanged.

Parameters:

tol : non-negative number.

All trailing coefficients less than tol will be removed.
Returns:

new_series : series

Contains the new set of coefficients.


numpy.polynomial.legendre.Legendre.truncate

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • numpy.polynomial.legendre.Legendre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.trim

Next topic

numpy.polynomial.legendre.legval

numpy.polynomial.legendre.Legendre.truncate

Legendre.truncate(size) [source]

Truncate series to length size.

Reduce the series to length size by discarding the high degree terms. The value of size must be a positive integer. This can be useful in least squares where the coefficients of the high degree terms may be very small.

Parameters:

size : positive int

The series is reduced to length size by discarding the high degree terms. The value of size must be a positive integer.
Returns:

new_series : series

New instance of series with truncated coefficients.


numpy.polynomial.legendre.legval

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.Legendre.truncate

Next topic

numpy.polynomial.legendre.legval2d

numpy.polynomial.legendre.legval

numpy.polynomial.legendre.legval(x, c, tensor=True) [source]

Evaluate a Legendre series at points x.

If c is of length n + 1, this function returns the value:

p(x) = c_0 * L_0(x) + c_1 * L_1(x) + ... + c_n * L_n(x)

The parameter x is converted to an array only if it is a tuple or a list, otherwise it is treated as a scalar. In either case, either x or its elements must support multiplication and addition both with themselves and with the elements of c.

If c is a 1-D array, then p(x) will have the same shape as x. If c is multidimensional, then the shape of the result depends on the value of tensor. If tensor is true the shape will be c.shape[1:] + x.shape. If tensor is false the shape will be c.shape[1:]. Note that scalars have shape (,).

Trailing zeros in the coefficients will be used in the evaluation, so they should be avoided if efficiency is a concern.

Parameters:

x : array_like, compatible object

If x is a list or tuple, it is converted to an ndarray, otherwise it is left unchanged and treated as a scalar. In either case, x or its elements must support addition and multiplication with with themselves and with the elements of c.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree n are contained in c[n]. If c is multidimensional the remaining indices enumerate multiple polynomials. In the two dimensional case the coefficients may be thought of as stored in the columns of c.

tensor : boolean, optional

If True, the shape of the coefficient array is extended with ones on the right, one for each dimension of x. Scalars have dimension 0 for this action. The result is that every column of coefficients in c is evaluated for every element of x. If False, x is broadcast over the columns of c for the evaluation. This keyword is useful when c is multidimensional. The default value is True.

New in version 1.7.0.
Returns:

values : ndarray, algebra_like

The shape of the return value is described above.

See also

legval2d, leggrid2d, legval3d, leggrid3d

Notes

The evaluation uses Clenshaw recursion, aka synthetic division.


numpy.polynomial.legendre.legval2d

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legval

Next topic

numpy.polynomial.legendre.legval3d

numpy.polynomial.legendre.legval2d

numpy.polynomial.legendre.legval2d(x, y, c) [source]

Evaluate a 2-D Legendre series at points (x, y).

This function returns the values:

The parameters x and y are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars and they must have the same shape after conversion. In either case, either x and y or their elements must support multiplication and addition both with themselves and with the elements of c.

If c is a 1-D array a one is implicitly appended to its shape to make it 2-D. The shape of the result will be c.shape[2:] + x.shape.

Parameters:

x, y : array_like, compatible objects

The two dimensional series is evaluated at the points (x, y), where x and y must have the same shape. If x or y is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and if it isn’t an ndarray it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j is contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional Legendre series at points formed from pairs of corresponding values from x and y.

See also

legval, leggrid2d, legval3d, leggrid3d

Notes


numpy.polynomial.legendre.legval3d

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legval2d

Next topic

numpy.polynomial.legendre.leggrid2d

numpy.polynomial.legendre.legval3d

numpy.polynomial.legendre.legval3d(x, y, z, c) [source]

Evaluate a 3-D Legendre series at points (x, y, z).

This function returns the values:

The parameters x, y, and z are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars and they must have the same shape after conversion. In either case, either x, y, and z or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than 3 dimensions, ones are implicitly appended to its shape to make it 3-D. The shape of the result will be c.shape[3:] + x.shape.

Parameters:

x, y, z : array_like, compatible object

The three dimensional series is evaluated at the points (x, y, z), where x, y, and z must have the same shape. If any of x, y, or z is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and if it isn’t an ndarray it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j,k is contained in c[i,j,k]. If c has dimension greater than 3 the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the multidimensional polynomial on points formed with triples of corresponding values from x, y, and z.

See also

legval, legval2d, leggrid2d, leggrid3d

Notes


numpy.polynomial.legendre.leggrid2d

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legval3d

Next topic

numpy.polynomial.legendre.leggrid3d

numpy.polynomial.legendre.leggrid2d

numpy.polynomial.legendre.leggrid2d(x, y, c) [source]

Evaluate a 2-D Legendre series on the Cartesian product of x and y.

This function returns the values:

where the points (a, b) consist of all pairs formed by taking a from x and b from y. The resulting points form a grid with x in the first dimension and y in the second.

The parameters x and y are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars. In either case, either x and y or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than two dimensions, ones are implicitly appended to its shape to make it 2-D. The shape of the result will be c.shape[2:] + x.shape + y.shape.

Parameters:

x, y : array_like, compatible objects

The two dimensional series is evaluated at the points in the Cartesian product of x and y. If x or y is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and, if it isn’t an ndarray, it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j is contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional Chebyshev series at points in the Cartesian product of x and y.

See also

legval, legval2d, legval3d, leggrid3d

Notes


numpy.polynomial.legendre.leggrid3d

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.leggrid2d

Next topic

numpy.polynomial.legendre.legroots

numpy.polynomial.legendre.leggrid3d

numpy.polynomial.legendre.leggrid3d(x, y, z, c) [source]

Evaluate a 3-D Legendre series on the Cartesian product of x, y, and z.

This function returns the values:

where the points (a, b, c) consist of all triples formed by taking a from x, b from y, and c from z. The resulting points form a grid with x in the first dimension, y in the second, and z in the third.

The parameters x, y, and z are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars. In either case, either x, y, and z or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than three dimensions, ones are implicitly appended to its shape to make it 3-D. The shape of the result will be c.shape[3:] + x.shape + y.shape + z.shape.

Parameters:

x, y, z : array_like, compatible objects

The three dimensional series is evaluated at the points in the Cartesian product of x, y, and z. If x,`y`, or z is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and, if it isn’t an ndarray, it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree i,j are contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional polynomial at points in the Cartesian product of x and y.

See also

legval, legval2d, leggrid2d, legval3d

Notes


numpy.polynomial.legendre.legroots

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.leggrid3d

Next topic

numpy.polynomial.legendre.legfromroots

numpy.polynomial.legendre.legroots

numpy.polynomial.legendre.legroots(c) [source]

Compute the roots of a Legendre series.

Return the roots (a.k.a. “zeros”) of the polynomial

Parameters:

c : 1-D array_like

1-D array of coefficients.
Returns:

out : ndarray

Array of the roots of the series. If all the roots are real, then out is also real, otherwise it is complex.

See also

polyroots, chebroots, lagroots, hermroots, hermeroots

Notes

The root estimates are obtained as the eigenvalues of the companion matrix, Roots far from the origin of the complex plane may have large errors due to the numerical instability of the series for such values. Roots with multiplicity greater than 1 will also show larger errors as the value of the series near such points is relatively insensitive to errors in the roots. Isolated roots near the origin can be improved by a few iterations of Newton’s method.

The Legendre series basis polynomials aren’t powers of x so the results of this function may seem unintuitive.

Examples

>>> import numpy.polynomial.legendre as leg
>>> leg.legroots((1, 2, 3, 4)) # 4L_3 + 3L_2 + 2L_1 + 1L_0, all real roots
array([-0.85099543, -0.11407192,  0.51506735])


numpy.polynomial.legendre.legfromroots

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legroots

Next topic

numpy.polynomial.legendre.legfit

numpy.polynomial.legendre.legfromroots

numpy.polynomial.legendre.legfromroots(roots) [source]

Generate a Legendre series with given roots.

The function returns the coefficients of the polynomial

p(x) = (x - r_0) * (x - r_1) * ... * (x - r_n),

in Legendre form, where the r_n are the roots specified in roots. If a zero has multiplicity n, then it must appear in roots n times. For instance, if 2 is a root of multiplicity three and 3 is a root of multiplicity 2, then roots looks something like [2, 2, 2, 3, 3]. The roots can appear in any order.

If the returned coefficients are c, then

p(x) = c_0 + c_1 * L_1(x) + ... + c_n * L_n(x)

The coefficient of the last term is not generally 1 for monic polynomials in Legendre form.

Parameters:

roots : array_like

Sequence containing the roots.
Returns:

out : ndarray

1-D array of coefficients. If all roots are real then out is a real array, if some of the roots are complex, then out is complex even if all the coefficients in the result are real (see Examples below).

See also

polyfromroots, chebfromroots, lagfromroots, hermfromroots, hermefromroots.

Examples

>>> import numpy.polynomial.legendre as L
>>> L.legfromroots((-1,0,1)) # x^3 - x relative to the standard basis
array([ 0. , -0.4,  0. ,  0.4])
>>> j = complex(0,1)
>>> L.legfromroots((-j,j)) # x^2 + 1 relative to the standard basis
array([ 1.33333333+0.j,  0.00000000+0.j,  0.66666667+0.j])


numpy.polynomial.legendre.legfit

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legfromroots

Next topic

numpy.polynomial.legendre.legvander

numpy.polynomial.legendre.legfit

numpy.polynomial.legendre.legfit(x, y, deg, rcond=None, full=False, w=None) [source]

Least squares fit of Legendre series to data.

Return the coefficients of a Legendre series of degree deg that is the least squares fit to the data values y given at points x. If y is 1-D the returned coefficients will also be 1-D. If y is 2-D multiple fits are done, one for each column of y, and the resulting coefficients are stored in the corresponding columns of a 2-D return. The fitted polynomial(s) are in the form

p(x) = c_0 + c_1 * L_1(x) + ... + c_n * L_n(x),

where n is deg.

Parameters:

x : array_like, shape (M,)

x-coordinates of the M sample points (x[i], y[i]).

y : array_like, shape (M,) or (M, K)

y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column.

deg : int

Degree of the fitting polynomial

rcond : float, optional

Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)*eps, where eps is the relative precision of the float type, about 2e-16 in most cases.

full : bool, optional

Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned.

w : array_like, shape (M,), optional

Weights. If not None, the contribution of each point (x[i],y[i]) to the fit is weighted by w[i]. Ideally the weights are chosen so that the errors of the products w[i]*y[i] all have the same variance. The default value is None.

New in version 1.5.0.
Returns:

coef : ndarray, shape (M,) or (M, K)

Legendre coefficients ordered from low to high. If y was 2-D, the coefficients for the data in column k of y are in column k.

[residuals, rank, singular_values, rcond] : list

These values are only returned if full = True

resid – sum of squared residuals of the least squares fit rank – the numerical rank of the scaled Vandermonde matrix sv – singular values of the scaled Vandermonde matrix rcond – value of rcond.

For more details, see linalg.lstsq.
Warns:

RankWarning

The rank of the coefficient matrix in the least-squares fit is deficient. The warning is only raised if full = False. The warnings can be turned off by

>>> import warnings
>>> warnings.simplefilter('ignore', RankWarning)

See also

chebfit, polyfit, lagfit, hermfit, hermefit

legval
Evaluates a Legendre series.
legvander
Vandermonde matrix of Legendre series.
legweight
Legendre weight function (= 1).
linalg.lstsq
Computes a least-squares fit from the matrix.
scipy.interpolate.UnivariateSpline
Computes spline fits.

Notes

The solution is the coefficients of the Legendre series p that minimizes the sum of the weighted squared errors

where [image] are the weights. This problem is solved by setting up as the (typically) overdetermined matrix equation

V(x) * c = w * y,

where V is the weighted pseudo Vandermonde matrix of x, c are the coefficients to be solved for, w are the weights, and y are the observed values. This equation is then solved using the singular value decomposition of V.

If some of the singular values of V are so small that they are neglected, then a RankWarning will be issued. This means that the coefficient values may be poorly determined. Using a lower order fit will usually get rid of the warning. The rcond parameter can also be set to a value smaller than its default, but the resulting fit may be spurious and have large contributions from roundoff error.

Fits using Legendre series are usually better conditioned than fits using power series, but much can depend on the distribution of the sample points and the smoothness of the data. If the quality of the fit is inadequate splines may be a good alternative.

References

[R64] Wikipedia, “Curve fitting”, http://en.wikipedia.org/wiki/Curve_fitting


numpy.polynomial.legendre.legvander

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legfit

Next topic

numpy.polynomial.legendre.legvander2d

numpy.polynomial.legendre.legvander

numpy.polynomial.legendre.legvander(x, deg) [source]

Pseudo-Vandermonde matrix of given degree.

Returns the pseudo-Vandermonde matrix of degree deg and sample points x. The pseudo-Vandermonde matrix is defined by

V[..., i] = L_i(x)

where 0 <= i <= deg. The leading indices of V index the elements of x and the last index is the degree of the Legendre polynomial.

If c is a 1-D array of coefficients of length n + 1 and V is the array V = legvander(x, n), then np.dot(V, c) and legval(x, c) are the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of Legendre series of the same degree and sample points.

Parameters:

x : array_like

Array of points. The dtype is converted to float64 or complex128 depending on whether any of the elements are complex. If x is scalar it is converted to a 1-D array.

deg : int

Degree of the resulting matrix.
Returns:

vander : ndarray

The pseudo-Vandermonde matrix. The shape of the returned matrix is x.shape + (deg + 1,), where The last index is the degree of the corresponding Legendre polynomial. The dtype will be the same as the converted x.


numpy.polynomial.legendre.legvander2d

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legvander

Next topic

numpy.polynomial.legendre.legvander3d

numpy.polynomial.legendre.legvander2d

numpy.polynomial.legendre.legvander2d(x, y, deg) [source]

Pseudo-Vandermonde matrix of given degrees.

Returns the pseudo-Vandermonde matrix of degrees deg and sample points (x, y). The pseudo-Vandermonde matrix is defined by

V[..., deg[1]*i + j] = L_i(x) * L_j(y),

where 0 <= i <= deg[0] and 0 <= j <= deg[1]. The leading indices of V index the points (x, y) and the last index encodes the degrees of the Legendre polynomials.

If V = legvander2d(x, y, [xdeg, ydeg]), then the columns of V correspond to the elements of a 2-D coefficient array c of shape (xdeg + 1, ydeg + 1) in the order

c_{00}, c_{01}, c_{02} ... , c_{10}, c_{11}, c_{12} ...

and np.dot(V, c.flat) and legval2d(x, y, c) will be the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of 2-D Legendre series of the same degrees and sample points.

Parameters:

x, y : array_like

Arrays of point coordinates, all of the same shape. The dtypes will be converted to either float64 or complex128 depending on whether any of the elements are complex. Scalars are converted to 1-D arrays.

deg : list of ints

List of maximum degrees of the form [x_deg, y_deg].
Returns:

vander2d : ndarray

The shape of the returned matrix is x.shape + (order,), where order = (deg[0]+1)*(deg([1]+1). The dtype will be the same as the converted x and y.

See also

legvander, legvander3d., legval3d

Notes


numpy.polynomial.legendre.legvander3d

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legvander2d

Next topic

numpy.polynomial.legendre.legder

numpy.polynomial.legendre.legvander3d

numpy.polynomial.legendre.legvander3d(x, y, z, deg) [source]

Pseudo-Vandermonde matrix of given degrees.

Returns the pseudo-Vandermonde matrix of degrees deg and sample points (x, y, z). If l, m, n are the given degrees in x, y, z, then The pseudo-Vandermonde matrix is defined by

V[..., (m+1)(n+1)i + (n+1)j + k] = L_i(x)*L_j(y)*L_k(z),

where 0 <= i <= l, 0 <= j <= m, and 0 <= j <= n. The leading indices of V index the points (x, y, z) and the last index encodes the degrees of the Legendre polynomials.

If V = legvander3d(x, y, z, [xdeg, ydeg, zdeg]), then the columns of V correspond to the elements of a 3-D coefficient array c of shape (xdeg + 1, ydeg + 1, zdeg + 1) in the order

c_{000}, c_{001}, c_{002},... , c_{010}, c_{011}, c_{012},...

and np.dot(V, c.flat) and legval3d(x, y, z, c) will be the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of 3-D Legendre series of the same degrees and sample points.

Parameters:

x, y, z : array_like

Arrays of point coordinates, all of the same shape. The dtypes will be converted to either float64 or complex128 depending on whether any of the elements are complex. Scalars are converted to 1-D arrays.

deg : list of ints

List of maximum degrees of the form [x_deg, y_deg, z_deg].
Returns:

vander3d : ndarray

The shape of the returned matrix is x.shape + (order,), where order = (deg[0]+1)*(deg([1]+1)*(deg[2]+1). The dtype will be the same as the converted x, y, and z.

See also

legvander, legvander3d., legval3d

Notes


numpy.polynomial.legendre.legder

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legvander3d

Next topic

numpy.polynomial.legendre.legint

numpy.polynomial.legendre.legder

numpy.polynomial.legendre.legder(c, m=1, scl=1, axis=0) [source]

Differentiate a Legendre series.

Returns the Legendre series coefficients c differentiated m times along axis. At each iteration the result is multiplied by scl (the scaling factor is for use in a linear change of variable). The argument c is an array of coefficients from low to high degree along each axis, e.g., [1,2,3] represents the series 1*L_0 + 2*L_1 + 3*L_2 while [[1,2],[1,2]] represents 1*L_0(x)*L_0(y) + 1*L_1(x)*L_0(y) + 2*L_0(x)*L_1(y) + 2*L_1(x)*L_1(y) if axis=0 is x and axis=1 is y.

Parameters:

c : array_like

Array of Legendre series coefficients. If c is multidimensional the different axis correspond to different variables with the degree in each axis given by the corresponding index.

m : int, optional

Number of derivatives taken, must be non-negative. (Default: 1)

scl : scalar, optional

Each differentiation is multiplied by scl. The end result is multiplication by scl**m. This is for use in a linear change of variable. (Default: 1)

axis : int, optional

Axis over which the derivative is taken. (Default: 0).

New in version 1.7.0.
Returns:

der : ndarray

Legendre series of the derivative.

See also

legint

Notes

In general, the result of differentiating a Legendre series does not resemble the same operation on a power series. Thus the result of this function may be “unintuitive,” albeit correct; see Examples section below.

Examples

>>> from numpy.polynomial import legendre as L
>>> c = (1,2,3,4)
>>> L.legder(c)
array([  6.,   9.,  20.])
>>> L.legder(c, 3)
array([ 60.])
>>> L.legder(c, scl=-1)
array([ -6.,  -9., -20.])
>>> L.legder(c, 2,-1)
array([  9.,  60.])


numpy.polynomial.legendre.legint

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legder

Next topic

numpy.polynomial.legendre.legadd

numpy.polynomial.legendre.legint

numpy.polynomial.legendre.legint(c, m=1, k=[], lbnd=0, scl=1, axis=0) [source]

Integrate a Legendre series.

Returns the Legendre series coefficients c integrated m times from lbnd along axis. At each iteration the resulting series is multiplied by scl and an integration constant, k, is added. The scaling factor is for use in a linear change of variable. (“Buyer beware”: note that, depending on what one is doing, one may want scl to be the reciprocal of what one might expect; for more information, see the Notes section below.) The argument c is an array of coefficients from low to high degree along each axis, e.g., [1,2,3] represents the series L_0 + 2*L_1 + 3*L_2 while [[1,2],[1,2]] represents 1*L_0(x)*L_0(y) + 1*L_1(x)*L_0(y) + 2*L_0(x)*L_1(y) + 2*L_1(x)*L_1(y) if axis=0 is x and axis=1 is y.

Parameters:

c : array_like

Array of Legendre series coefficients. If c is multidimensional the different axis correspond to different variables with the degree in each axis given by the corresponding index.

m : int, optional

Order of integration, must be positive. (Default: 1)

k : {[], list, scalar}, optional

Integration constant(s). The value of the first integral at lbnd is the first value in the list, the value of the second integral at lbnd is the second value, etc. If k == [] (the default), all constants are set to zero. If m == 1, a single scalar can be given instead of a list.

lbnd : scalar, optional

The lower bound of the integral. (Default: 0)

scl : scalar, optional

Following each integration the result is multiplied by scl before the integration constant is added. (Default: 1)

axis : int, optional

Axis over which the integral is taken. (Default: 0).

New in version 1.7.0.
Returns:

S : ndarray

Legendre series coefficient array of the integral.
Raises:

ValueError

If m < 0, len(k) > m, np.isscalar(lbnd) == False, or np.isscalar(scl) == False.

See also

legder

Notes

Note that the result of each integration is multiplied by scl. Why is this important to note? Say one is making a linear change of variable u = ax + b in an integral relative to x. Then .. math::dx = du/a, so one will need to set scl equal to 1/a - perhaps not what one would have first thought.

Also note that, in general, the result of integrating a C-series needs to be “reprojected” onto the C-series basis set. Thus, typically, the result of this function is “unintuitive,” albeit correct; see Examples section below.

Examples

>>> from numpy.polynomial import legendre as L
>>> c = (1,2,3)
>>> L.legint(c)
array([ 0.33333333,  0.4       ,  0.66666667,  0.6       ])
>>> L.legint(c, 3)
array([  1.66666667e-02,  -1.78571429e-02,   4.76190476e-02,
        -1.73472348e-18,   1.90476190e-02,   9.52380952e-03])
>>> L.legint(c, k=3)
array([ 3.33333333,  0.4       ,  0.66666667,  0.6       ])
>>> L.legint(c, lbnd=-2)
array([ 7.33333333,  0.4       ,  0.66666667,  0.6       ])
>>> L.legint(c, scl=2)
array([ 0.66666667,  0.8       ,  1.33333333,  1.2       ])


numpy.polynomial.legendre.legadd

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legint

Next topic

numpy.polynomial.legendre.legsub

numpy.polynomial.legendre.legadd

numpy.polynomial.legendre.legadd(c1, c2) [source]

Add one Legendre series to another.

Returns the sum of two Legendre series c1 + c2. The arguments are sequences of coefficients ordered from lowest order term to highest, i.e., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Legendre series coefficients ordered from low to high.
Returns:

out : ndarray

Array representing the Legendre series of their sum.

See also

legsub, legmul, legdiv, legpow

Notes

Unlike multiplication, division, etc., the sum of two Legendre series is a Legendre series (without having to “reproject” the result onto the basis set) so addition, just like that of “standard” polynomials, is simply “component-wise.”

Examples

>>> from numpy.polynomial import legendre as L
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
>>> L.legadd(c1,c2)
array([ 4.,  4.,  4.])


numpy.polynomial.legendre.legsub

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legadd

Next topic

numpy.polynomial.legendre.legmul

numpy.polynomial.legendre.legsub

numpy.polynomial.legendre.legsub(c1, c2) [source]

Subtract one Legendre series from another.

Returns the difference of two Legendre series c1 - c2. The sequences of coefficients are from lowest order term to highest, i.e., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Legendre series coefficients ordered from low to high.
Returns:

out : ndarray

Of Legendre series coefficients representing their difference.

See also

legadd, legmul, legdiv, legpow

Notes

Unlike multiplication, division, etc., the difference of two Legendre series is a Legendre series (without having to “reproject” the result onto the basis set) so subtraction, just like that of “standard” polynomials, is simply “component-wise.”

Examples

>>> from numpy.polynomial import legendre as L
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
>>> L.legsub(c1,c2)
array([-2.,  0.,  2.])
>>> L.legsub(c2,c1) # -C.legsub(c1,c2)
array([ 2.,  0., -2.])


numpy.polynomial.legendre.legmul

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legsub

Next topic

numpy.polynomial.legendre.legmulx

numpy.polynomial.legendre.legmul

numpy.polynomial.legendre.legmul(c1, c2) [source]

Multiply one Legendre series by another.

Returns the product of two Legendre series c1 * c2. The arguments are sequences of coefficients, from lowest order “term” to highest, e.g., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Legendre series coefficients ordered from low to high.
Returns:

out : ndarray

Of Legendre series coefficients representing their product.

See also

legadd, legsub, legdiv, legpow

Notes

In general, the (polynomial) product of two C-series results in terms that are not in the Legendre polynomial basis set. Thus, to express the product as a Legendre series, it is necessary to “reproject” the product onto said basis set, which may produce “unintuitive” (but correct) results; see Examples section below.

Examples

>>> from numpy.polynomial import legendre as L
>>> c1 = (1,2,3)
>>> c2 = (3,2)
>>> P.legmul(c1,c2) # multiplication requires "reprojection"
array([  4.33333333,  10.4       ,  11.66666667,   3.6       ])


numpy.polynomial.legendre.legmulx

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legmul

Next topic

numpy.polynomial.legendre.legdiv

numpy.polynomial.legendre.legmulx

numpy.polynomial.legendre.legmulx(c) [source]

Multiply a Legendre series by x.

Multiply the Legendre series c by x, where x is the independent variable.

Parameters:

c : array_like

1-D array of Legendre series coefficients ordered from low to high.
Returns:

out : ndarray

Array representing the result of the multiplication.

Notes

The multiplication uses the recursion relationship for Legendre polynomials in the form

xP_i(x) = ((i + 1)*P_{i + 1}(x) + i*P_{i - 1}(x))/(2i + 1)


numpy.polynomial.legendre.legdiv

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legmulx

Next topic

numpy.polynomial.legendre.legpow

numpy.polynomial.legendre.legdiv

numpy.polynomial.legendre.legdiv(c1, c2) [source]

Divide one Legendre series by another.

Returns the quotient-with-remainder of two Legendre series c1 / c2. The arguments are sequences of coefficients from lowest order “term” to highest, e.g., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Legendre series coefficients ordered from low to high.
Returns:

quo, rem : ndarrays

Of Legendre series coefficients representing the quotient and remainder.

See also

legadd, legsub, legmul, legpow

Notes

In general, the (polynomial) division of one Legendre series by another results in quotient and remainder terms that are not in the Legendre polynomial basis set. Thus, to express these results as a Legendre series, it is necessary to “reproject” the results onto the Legendre basis set, which may produce “unintuitive” (but correct) results; see Examples section below.

Examples

>>> from numpy.polynomial import legendre as L
>>> c1 = (1,2,3)
>>> c2 = (3,2,1)
>>> L.legdiv(c1,c2) # quotient "intuitive," remainder not
(array([ 3.]), array([-8., -4.]))
>>> c2 = (0,1,2,3)
>>> L.legdiv(c2,c1) # neither "intuitive"
(array([-0.07407407,  1.66666667]), array([-1.03703704, -2.51851852]))


numpy.polynomial.legendre.legpow

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legdiv

Next topic

numpy.polynomial.legendre.leggauss

numpy.polynomial.legendre.legpow

numpy.polynomial.legendre.legpow(c, pow, maxpower=16) [source]

Raise a Legendre series to a power.

Returns the Legendre series c raised to the power pow. The arguement c is a sequence of coefficients ordered from low to high. i.e., [1,2,3] is the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c : array_like

1-D array of Legendre series coefficients ordered from low to high.

pow : integer

Power to which the series will be raised

maxpower : integer, optional

Maximum power allowed. This is mainly to limit growth of the series to unmanageable size. Default is 16
Returns:

coef : ndarray

Legendre series of power.

See also

legadd, legsub, legmul, legdiv


numpy.polynomial.legendre.leggauss

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legpow

Next topic

numpy.polynomial.legendre.legweight

numpy.polynomial.legendre.leggauss

numpy.polynomial.legendre.leggauss(deg) [source]

Gauss-Legendre quadrature.

Computes the sample points and weights for Gauss-Legendre quadrature. These sample points and weights will correctly integrate polynomials of degree 2*deg - 1 or less over the interval [-1, 1] with the weight function f(x) = 1.

Parameters:

deg : int

Number of sample points and weights. It must be >= 1.
Returns:

x : ndarray

1-D ndarray containing the sample points.

y : ndarray

1-D ndarray containing the weights.

Notes

The results have only been tested up to degree 100, higher degrees may be problematic. The weights are determined by using the fact that

w_k = c / (L'_n(x_k) * L_{n-1}(x_k))

where c is a constant independent of k and [image] is the k’th root of [image], and then scaling the results to get the right value when integrating 1.


numpy.polynomial.legendre.legweight

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.leggauss

Next topic

numpy.polynomial.legendre.legcompanion

numpy.polynomial.legendre.legweight

numpy.polynomial.legendre.legweight(x) [source]

Weight function of the Legendre polynomials.

The weight function is 1 and the interval of integration is [-1, 1]. The Legendre polynomials are orthogonal, but not normalized, with respect to this weight function.

Parameters:

x : array_like

Values at which the weight function will be computed.
Returns:

w : ndarray

The weight function at x.

Notes


numpy.polynomial.legendre.legcompanion

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legweight

Next topic

numpy.polynomial.legendre.legdomain

numpy.polynomial.legendre.legcompanion

numpy.polynomial.legendre.legcompanion(c) [source]

Return the scaled companion matrix of c.

The basis polynomials are scaled so that the companion matrix is symmetric when c is an Legendre basis polynomial. This provides better eigenvalue estimates than the unscaled case and for basis polynomials the eigenvalues are guaranteed to be real if numpy.linalg.eigvalsh is used to obtain them.

Parameters:

c : array_like

1-D array of Legendre series coefficients ordered from low to high degree.
Returns:

mat : ndarray

Scaled companion matrix of dimensions (deg, deg).

Notes


numpy.polynomial.legendre.legdomain

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legcompanion

Next topic

numpy.polynomial.legendre.legzero

numpy.polynomial.legendre.legdomain

numpy.polynomial.legendre.legdomain = array([-1, 1])


numpy.polynomial.legendre.legzero

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legdomain

Next topic

numpy.polynomial.legendre.legone

numpy.polynomial.legendre.legzero

numpy.polynomial.legendre.legzero = array([0])


numpy.polynomial.legendre.legone

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legzero

Next topic

numpy.polynomial.legendre.legx

numpy.polynomial.legendre.legone

numpy.polynomial.legendre.legone = array([1])


numpy.polynomial.legendre.legx

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legone

Next topic

numpy.polynomial.legendre.legtrim

numpy.polynomial.legendre.legx

numpy.polynomial.legendre.legx = array([0, 1])


numpy.polynomial.legendre.legtrim

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legx

Next topic

numpy.polynomial.legendre.legline

numpy.polynomial.legendre.legtrim

numpy.polynomial.legendre.legtrim(c, tol=0) [source]

Remove “small” “trailing” coefficients from a polynomial.

“Small” means “small in absolute value” and is controlled by the parameter tol; “trailing” means highest order coefficient(s), e.g., in [0, 1, 1, 0, 0] (which represents 0 + x + x**2 + 0*x**3 + 0*x**4) both the 3-rd and 4-th order coefficients would be “trimmed.”

Parameters:

c : array_like

1-d array of coefficients, ordered from lowest order to highest.

tol : number, optional

Trailing (i.e., highest order) elements with absolute value less than or equal to tol (default value is zero) are removed.
Returns:

trimmed : ndarray

1-d array with trailing zeros removed. If the resulting series would be empty, a series containing a single zero is returned.
Raises:

ValueError

If tol < 0

See also

trimseq

Examples

>>> from numpy import polynomial as P
>>> P.trimcoef((0,0,3,0,5,0,0))
array([ 0.,  0.,  3.,  0.,  5.])
>>> P.trimcoef((0,0,1e-3,0,1e-5,0,0),1e-3) # item == tol is trimmed
array([ 0.])
>>> i = complex(0,1) # works for complex
>>> P.trimcoef((3e-4,1e-3*(1-i),5e-4,2e-5*(1+i)), 1e-3)
array([ 0.0003+0.j   ,  0.0010-0.001j])


numpy.polynomial.legendre.legline

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legtrim

Next topic

numpy.polynomial.legendre.leg2poly

numpy.polynomial.legendre.legline

numpy.polynomial.legendre.legline(off, scl) [source]

Legendre series whose graph is a straight line.

Parameters:

off, scl : scalars

The specified line is given by off + scl*x.
Returns:

y : ndarray

This module’s representation of the Legendre series for off + scl*x.

See also

polyline, chebline

Examples

>>> import numpy.polynomial.legendre as L
>>> L.legline(3,2)
array([3, 2])
>>> L.legval(-3, L.legline(3,2)) # should be -3
-3.0


numpy.polynomial.legendre.leg2poly

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.legline

Next topic

numpy.polynomial.legendre.poly2leg

numpy.polynomial.legendre.leg2poly

numpy.polynomial.legendre.leg2poly(c) [source]

Convert a Legendre series to a polynomial.

Convert an array representing the coefficients of a Legendre series, ordered from lowest degree to highest, to an array of the coefficients of the equivalent polynomial (relative to the “standard” basis) ordered from lowest to highest degree.

Parameters:

c : array_like

1-D array containing the Legendre series coefficients, ordered from lowest order term to highest.
Returns:

pol : ndarray

1-D array containing the coefficients of the equivalent polynomial (relative to the “standard” basis) ordered from lowest order term to highest.

See also

poly2leg

Notes

The easy way to do conversions between polynomial basis sets is to use the convert method of a class instance.

Examples

>>> c = P.Legendre(range(4))
>>> c
Legendre([ 0.,  1.,  2.,  3.], [-1.,  1.])
>>> p = c.convert(kind=P.Polynomial)
>>> p
Polynomial([-1. , -3.5,  3. ,  7.5], [-1.,  1.])
>>> P.leg2poly(range(4))
array([-1. , -3.5,  3. ,  7.5])


numpy.polynomial.legendre.poly2leg

  • Polynomials
  • Polynomial Package
  • Legendre Module (numpy.polynomial.legendre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.legendre.leg2poly

Next topic

Laguerre Module (numpy.polynomial.laguerre)

numpy.polynomial.legendre.poly2leg

numpy.polynomial.legendre.poly2leg(pol) [source]

Convert a polynomial to a Legendre series.

Convert an array representing the coefficients of a polynomial (relative to the “standard” basis) ordered from lowest degree to highest, to an array of the coefficients of the equivalent Legendre series, ordered from lowest to highest degree.

Parameters:

pol : array_like

1-D array containing the polynomial coefficients
Returns:

c : ndarray

1-D array containing the coefficients of the equivalent Legendre series.

See also

leg2poly

Notes

The easy way to do conversions between polynomial basis sets is to use the convert method of a class instance.

Examples

>>> from numpy import polynomial as P
>>> p = P.Polynomial(np.arange(4))
>>> p
Polynomial([ 0.,  1.,  2.,  3.], [-1.,  1.])
>>> c = P.Legendre(P.poly2leg(p.coef))
>>> c
Legendre([ 1.  ,  3.25,  1.  ,  0.75], [-1.,  1.])


Laguerre Module (numpy.polynomial.laguerre)

  • Polynomials
  • Polynomial Package
  • index
  • next
  • previous

Table Of Contents

  • Laguerre Module (numpy.polynomial.laguerre)
    • Laguerre Class
    • Basics
    • Fitting
    • Calculus
    • Algebra
    • Quadrature
    • Miscellaneous

Previous topic

numpy.polynomial.legendre.poly2leg

Next topic

numpy.polynomial.laguerre.Laguerre

Laguerre Module (numpy.polynomial.laguerre)

New in version 1.6.0.

This module provides a number of objects (mostly functions) useful for dealing with Laguerre series, including a Laguerre class that encapsulates the usual arithmetic operations. (General information on how this module represents and works with such polynomials is in the docstring for its “parent” sub-package, numpy.polynomial).

Laguerre Class

Laguerre(coef[, domain, window]) A Laguerre series class.

Basics

lagval(x, c[, tensor]) | Evaluate a Laguerre series at points x.
lagval2d(x, y, c) | Evaluate a 2-D Laguerre series at points (x, y).
lagval3d(x, y, z, c) | Evaluate a 3-D Laguerre series at points (x, y, z).
laggrid2d(x, y, c) | Evaluate a 2-D Laguerre series on the Cartesian product of x and y.
laggrid3d(x, y, z, c) | Evaluate a 3-D Laguerre series on the Cartesian product of x, y, and z.
lagroots(c) | Compute the roots of a Laguerre series.
lagfromroots(roots) | Generate a Laguerre series with given roots.

Fitting

lagfit(x, y, deg[, rcond, full, w]) | Least squares fit of Laguerre series to data.
lagvander(x, deg) | Pseudo-Vandermonde matrix of given degree.
lagvander2d(x, y, deg) | Pseudo-Vandermonde matrix of given degrees.
lagvander3d(x, y, z, deg) | Pseudo-Vandermonde matrix of given degrees.

Calculus

lagder(c[, m, scl, axis]) | Differentiate a Laguerre series.
lagint(c[, m, k, lbnd, scl, axis]) | Integrate a Laguerre series.

Algebra

lagadd(c1, c2) | Add one Laguerre series to another.
lagsub(c1, c2) | Subtract one Laguerre series from another.
lagmul(c1, c2) | Multiply one Laguerre series by another.
lagmulx(c) | Multiply a Laguerre series by x.
lagdiv(c1, c2) | Divide one Laguerre series by another.
lagpow(c, pow[, maxpower]) | Raise a Laguerre series to a power.

Quadrature

laggauss(deg) | Gauss-Laguerre quadrature.
lagweight(x) | Weight function of the Laguerre polynomials.

Miscellaneous

lagcompanion(c) | Return the companion matrix of c.
lagdomain |
lagzero |
lagone |
lagx |
lagtrim(c[, tol]) | Remove “small” “trailing” coefficients from a polynomial.
lagline(off, scl) | Laguerre series whose graph is a straight line.
lag2poly(c) | Convert a Laguerre series to a polynomial.
poly2lag(pol) | Convert a polynomial to a Laguerre series.


numpy.polynomial.laguerre.Laguerre

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.poly2lag

Next topic

numpy.polynomial.laguerre.Laguerre.__call__

numpy.polynomial.laguerre.Laguerre

class numpy.polynomial.laguerre.Laguerre(coef, domain=None, window=None) [source]

A Laguerre series class.

The Laguerre class provides the standard Python numerical methods ‘+’, ‘-‘, ‘*’, ‘//’, ‘%’, ‘divmod’, ‘**’, and ‘()’ as well as the attributes and methods listed in the ABCPolyBase documentation.

Parameters:

coef : array_like

Laguerre coefficients in order of increasing degree, i.e, (1, 2, 3) gives 1*L_0(x) + 2*L_1(X) + 3*L_2(x).

domain : (2,) array_like, optional

Domain to use. The interval [domain[0], domain[1]] is mapped to the interval [window[0], window[1]] by shifting and scaling. The default value is [0, 1].

window : (2,) array_like, optional

Window, see domain for its use. The default value is [0, 1].

New in version 1.6.0.

Methods

__call__(arg)
basis(deg[, domain, window]) | Series basis polynomial of degree deg.
cast(series[, domain, window]) | Convert series to series of this class.
convert([domain, kind, window]) | Convert series to a different kind and/or domain and/or window.
copy() | Return a copy.
cutdeg(deg) | Truncate series to the given degree.
degree() | The degree of the series.
deriv([m]) | Differentiate.
fit(x, y, deg[, domain, rcond, full, w, window]) | Least squares fit to data.
fromroots(roots[, domain, window]) | Return series instance that has the specified roots.
has_samecoef(other) | Check if coefficients match.
has_samedomain(other) | Check if domains match.
has_sametype(other) | Check if types match.
has_samewindow(other) | Check if windows match.
identity([domain, window]) | Identity function.
integ([m, k, lbnd]) | Integrate.
linspace([n, domain]) | Return x, y values at equally spaced points in domain.
mapparms() | Return the mapping parameters.
roots() | Return the roots of the series polynomial.
trim([tol]) | Remove trailing coefficients
truncate(size) | Truncate series to length size.


numpy.polynomial.laguerre.Laguerre.__call__

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre

Next topic

numpy.polynomial.laguerre.Laguerre.basis

numpy.polynomial.laguerre.Laguerre.__call__

Laguerre.__call__(arg) [source]


numpy.polynomial.laguerre.Laguerre.basis

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.__call__

Next topic

numpy.polynomial.laguerre.Laguerre.cast

numpy.polynomial.laguerre.Laguerre.basis

classmethod Laguerre.basis(deg, domain=None, window=None) [source]

Series basis polynomial of degree deg.

Returns the series representing the basis polynomial of degree deg.

New in version 1.7.0.

Parameters:

deg : int

Degree of the basis polynomial for the series. Must be >= 0.

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

A series with the coefficient of the deg term set to one and all others zero.


numpy.polynomial.laguerre.Laguerre.cast

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.basis

Next topic

numpy.polynomial.laguerre.Laguerre.convert

numpy.polynomial.laguerre.Laguerre.cast

classmethod Laguerre.cast(series, domain=None, window=None) [source]

Convert series to series of this class.

The series is expected to be an instance of some polynomial series of one of the types supported by by the numpy.polynomial module, but could be some other class that supports the convert method.

New in version 1.7.0.

Parameters:

series : series

The series instance to be converted.

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

A series of the same kind as the calling class and equal to series when evaluated.

See also

convert
similar instance method


numpy.polynomial.laguerre.Laguerre.convert

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.cast

Next topic

numpy.polynomial.laguerre.Laguerre.copy

numpy.polynomial.laguerre.Laguerre.convert

Laguerre.convert(domain=None, kind=None, window=None) [source]

Convert series to a different kind and/or domain and/or window.

Parameters:

domain : array_like, optional

The domain of the converted series. If the value is None, the default domain of kind is used.

kind : class, optional

The polynomial series type class to which the current instance should be converted. If kind is None, then the class of the current instance is used.

window : array_like, optional

The window of the converted series. If the value is None, the default window of kind is used.
Returns:

new_series : series

The returned class can be of different type than the current instance and/or have a different domain and/or different window.

Notes

Conversion between domains and class types can result in numerically ill defined series.


numpy.polynomial.laguerre.Laguerre.copy

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.convert

Next topic

numpy.polynomial.laguerre.Laguerre.cutdeg

numpy.polynomial.laguerre.Laguerre.copy

Laguerre.copy() [source]

Return a copy.

Returns:

new_series : series

Copy of self.


numpy.polynomial.laguerre.Laguerre.cutdeg

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.copy

Next topic

numpy.polynomial.laguerre.Laguerre.degree

numpy.polynomial.laguerre.Laguerre.cutdeg

Laguerre.cutdeg(deg) [source]

Truncate series to the given degree.

Reduce the degree of the series to deg by discarding the high order terms. If deg is greater than the current degree a copy of the current series is returned. This can be useful in least squares where the coefficients of the high degree terms may be very small.

New in version 1.5.0.

Parameters:

deg : non-negative int

The series is reduced to degree deg by discarding the high order terms. The value of deg must be a non-negative integer.
Returns:

new_series : series

New instance of series with reduced degree.


numpy.polynomial.laguerre.Laguerre.degree

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.cutdeg

Next topic

numpy.polynomial.laguerre.Laguerre.deriv

numpy.polynomial.laguerre.Laguerre.degree

Laguerre.degree() [source]

The degree of the series.

New in version 1.5.0.

Returns:

degree : int

Degree of the series, one less than the number of coefficients.


numpy.polynomial.laguerre.Laguerre.deriv

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.degree

Next topic

numpy.polynomial.laguerre.Laguerre.fit

numpy.polynomial.laguerre.Laguerre.deriv

Laguerre.deriv(m=1) [source]

Differentiate.

Return a series instance of that is the derivative of the current series.

Parameters:

m : non-negative int

The number of integrations to perform.
Returns:

new_series : series

A new series representing the derivative. The domain is the same as the domain of the differentiated series.


numpy.polynomial.laguerre.Laguerre.fit

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.deriv

Next topic

numpy.polynomial.laguerre.Laguerre.fromroots

numpy.polynomial.laguerre.Laguerre.fit

classmethod Laguerre.fit(x, y, deg, domain=None, rcond=None, full=False, w=None, window=None) [source]

Least squares fit to data.

Return a series instance that is the least squares fit to the data y sampled at x. The domain of the returned instance can be specified and this will often result in a superior fit with less chance of ill conditioning.

Parameters:

x : array_like, shape (M,)

x-coordinates of the M sample points (x[i], y[i]).

y : array_like, shape (M,) or (M, K)

y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column.

deg : int

Degree of the fitting polynomial.

domain : {None, [beg, end], []}, optional

Domain to use for the returned series. If None, then a minimal domain that covers the points x is chosen. If [] the class domain is used. The default value was the class domain in NumPy 1.4 and None in later versions. The [] option was added in numpy 1.5.0.

rcond : float, optional

Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)*eps, where eps is the relative precision of the float type, about 2e-16 in most cases.

full : bool, optional

Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned.

w : array_like, shape (M,), optional

Weights. If not None the contribution of each point (x[i],y[i]) to the fit is weighted by w[i]. Ideally the weights are chosen so that the errors of the products w[i]*y[i] all have the same variance. The default value is None.

New in version 1.5.0.

window : {[beg, end]}, optional

Window to use for the returned series. The default value is the default class domain

New in version 1.6.0.
Returns:

new_series : series

A series that represents the least squares fit to the data and has the domain specified in the call.

[resid, rank, sv, rcond] : list

These values are only returned if full = True

resid – sum of squared residuals of the least squares fit rank – the numerical rank of the scaled Vandermonde matrix sv – singular values of the scaled Vandermonde matrix rcond – value of rcond.

For more details, see linalg.lstsq.


numpy.polynomial.laguerre.Laguerre.fromroots

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.fit

Next topic

numpy.polynomial.laguerre.Laguerre.has_samecoef

numpy.polynomial.laguerre.Laguerre.fromroots

classmethod Laguerre.fromroots(roots, domain=[], window=None) [source]

Return series instance that has the specified roots.

Returns a series representing the product (x - r[0])*(x - r[1])*...*(x - r[n-1]), where r is a list of roots.

Parameters:

roots : array_like

List of roots.

domain : {[], None, array_like}, optional

Domain for the resulting series. If None the domain is the interval from the smallest root to the largest. If [] the domain is the class domain. The default is [].

window : {None, array_like}, optional

Window for the returned series. If None the class window is used. The default is None.
Returns:

new_series : series

Series with the specified roots.


numpy.polynomial.laguerre.Laguerre.has_samecoef

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.fromroots

Next topic

numpy.polynomial.laguerre.Laguerre.has_samedomain

numpy.polynomial.laguerre.Laguerre.has_samecoef

Laguerre.has_samecoef(other) [source]

Check if coefficients match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the coef attribute.
Returns:

bool : boolean

True if the coefficients are the same, False otherwise.


numpy.polynomial.laguerre.Laguerre.has_samedomain

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.has_samecoef

Next topic

numpy.polynomial.laguerre.Laguerre.has_sametype

numpy.polynomial.laguerre.Laguerre.has_samedomain

Laguerre.has_samedomain(other) [source]

Check if domains match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the domain attribute.
Returns:

bool : boolean

True if the domains are the same, False otherwise.


numpy.polynomial.laguerre.Laguerre.has_sametype

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.has_samedomain

Next topic

numpy.polynomial.laguerre.Laguerre.has_samewindow

numpy.polynomial.laguerre.Laguerre.has_sametype

Laguerre.has_sametype(other) [source]

Check if types match.

New in version 1.7.0.

Parameters:

other : object

Class instance.
Returns:

bool : boolean

True if other is same class as self


numpy.polynomial.laguerre.Laguerre.has_samewindow

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.has_sametype

Next topic

numpy.polynomial.laguerre.Laguerre.identity

numpy.polynomial.laguerre.Laguerre.has_samewindow

Laguerre.has_samewindow(other) [source]

Check if windows match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the window attribute.
Returns:

bool : boolean

True if the windows are the same, False otherwise.


numpy.polynomial.laguerre.Laguerre.identity

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.has_samewindow

Next topic

numpy.polynomial.laguerre.Laguerre.integ

numpy.polynomial.laguerre.Laguerre.identity

classmethod Laguerre.identity(domain=None, window=None) [source]

Identity function.

If p is the returned series, then p(x) == x for all values of x.

Parameters:

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

Series of representing the identity.


numpy.polynomial.laguerre.Laguerre.integ

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.identity

Next topic

numpy.polynomial.laguerre.Laguerre.linspace

numpy.polynomial.laguerre.Laguerre.integ

Laguerre.integ(m=1, k=[], lbnd=None) [source]

Integrate.

Return a series instance that is the definite integral of the current series.

Parameters:

m : non-negative int

The number of integrations to perform.

k : array_like

Integration constants. The first constant is applied to the first integration, the second to the second, and so on. The list of values must less than or equal to m in length and any missing values are set to zero.

lbnd : Scalar

The lower bound of the definite integral.
Returns:

new_series : series

A new series representing the integral. The domain is the same as the domain of the integrated series.


numpy.polynomial.laguerre.Laguerre.linspace

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.integ

Next topic

numpy.polynomial.laguerre.Laguerre.mapparms

numpy.polynomial.laguerre.Laguerre.linspace

Laguerre.linspace(n=100, domain=None) [source]

Return x, y values at equally spaced points in domain.

Returns the x, y values at n linearly spaced points across the domain. Here y is the value of the polynomial at the points x. By default the domain is the same as that of the series instance. This method is intended mostly as a plotting aid.

New in version 1.5.0.

Parameters:

n : int, optional

Number of point pairs to return. The default value is 100.

domain : {None, array_like}, optional

If not None, the specified domain is used instead of that of the calling instance. It should be of the form [beg,end]. The default is None which case the class domain is used.
Returns:

x, y : ndarray

x is equal to linspace(self.domain[0], self.domain[1], n) and y is the series evaluated at element of x.


numpy.polynomial.laguerre.Laguerre.mapparms

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.linspace

Next topic

numpy.polynomial.laguerre.Laguerre.roots

numpy.polynomial.laguerre.Laguerre.mapparms

Laguerre.mapparms() [source]

Return the mapping parameters.

The returned values define a linear map off + scl*x that is applied to the input arguments before the series is evaluated. The map depends on the domain and window; if the current domain is equal to the window the resulting map is the identity. If the coefficients of the series instance are to be used by themselves outside this class, then the linear function must be substituted for the x in the standard representation of the base polynomials.

Returns:

off, scl : float or complex

The mapping function is defined by off + scl*x.

Notes

If the current domain is the interval [l1, r1] and the window is [l2, r2], then the linear mapping function L is defined by the equations:

L(l1) = l2
L(r1) = r2


numpy.polynomial.laguerre.Laguerre.roots

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.mapparms

Next topic

numpy.polynomial.laguerre.Laguerre.trim

numpy.polynomial.laguerre.Laguerre.roots

Laguerre.roots() [source]

Return the roots of the series polynomial.

Compute the roots for the series. Note that the accuracy of the roots decrease the further outside the domain they lie.

Returns:

roots : ndarray

Array containing the roots of the series.


numpy.polynomial.laguerre.Laguerre.trim

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.roots

Next topic

numpy.polynomial.laguerre.Laguerre.truncate

numpy.polynomial.laguerre.Laguerre.trim

Laguerre.trim(tol=0) [source]

Remove trailing coefficients

Remove trailing coefficients until a coefficient is reached whose absolute value greater than tol or the beginning of the series is reached. If all the coefficients would be removed the series is set to [0]. A new series instance is returned with the new coefficients. The current instance remains unchanged.

Parameters:

tol : non-negative number.

All trailing coefficients less than tol will be removed.
Returns:

new_series : series

Contains the new set of coefficients.


numpy.polynomial.laguerre.Laguerre.truncate

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • numpy.polynomial.laguerre.Laguerre
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.trim

Next topic

numpy.polynomial.laguerre.lagval

numpy.polynomial.laguerre.Laguerre.truncate

Laguerre.truncate(size) [source]

Truncate series to length size.

Reduce the series to length size by discarding the high degree terms. The value of size must be a positive integer. This can be useful in least squares where the coefficients of the high degree terms may be very small.

Parameters:

size : positive int

The series is reduced to length size by discarding the high degree terms. The value of size must be a positive integer.
Returns:

new_series : series

New instance of series with truncated coefficients.


numpy.polynomial.laguerre.lagval

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.Laguerre.truncate

Next topic

numpy.polynomial.laguerre.lagval2d

numpy.polynomial.laguerre.lagval

numpy.polynomial.laguerre.lagval(x, c, tensor=True) [source]

Evaluate a Laguerre series at points x.

If c is of length n + 1, this function returns the value:

p(x) = c_0 * L_0(x) + c_1 * L_1(x) + ... + c_n * L_n(x)

The parameter x is converted to an array only if it is a tuple or a list, otherwise it is treated as a scalar. In either case, either x or its elements must support multiplication and addition both with themselves and with the elements of c.

If c is a 1-D array, then p(x) will have the same shape as x. If c is multidimensional, then the shape of the result depends on the value of tensor. If tensor is true the shape will be c.shape[1:] + x.shape. If tensor is false the shape will be c.shape[1:]. Note that scalars have shape (,).

Trailing zeros in the coefficients will be used in the evaluation, so they should be avoided if efficiency is a concern.

Parameters:

x : array_like, compatible object

If x is a list or tuple, it is converted to an ndarray, otherwise it is left unchanged and treated as a scalar. In either case, x or its elements must support addition and multiplication with with themselves and with the elements of c.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree n are contained in c[n]. If c is multidimensional the remaining indices enumerate multiple polynomials. In the two dimensional case the coefficients may be thought of as stored in the columns of c.

tensor : boolean, optional

If True, the shape of the coefficient array is extended with ones on the right, one for each dimension of x. Scalars have dimension 0 for this action. The result is that every column of coefficients in c is evaluated for every element of x. If False, x is broadcast over the columns of c for the evaluation. This keyword is useful when c is multidimensional. The default value is True.

New in version 1.7.0.
Returns:

values : ndarray, algebra_like

The shape of the return value is described above.

See also

lagval2d, laggrid2d, lagval3d, laggrid3d

Notes

The evaluation uses Clenshaw recursion, aka synthetic division.

Examples

>>> from numpy.polynomial.laguerre import lagval
>>> coef = [1,2,3]
>>> lagval(1, coef)
-0.5
>>> lagval([[1,2],[3,4]], coef)
array([[-0.5, -4. ],
       [-4.5, -2. ]])


numpy.polynomial.laguerre.lagval2d

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagval

Next topic

numpy.polynomial.laguerre.lagval3d

numpy.polynomial.laguerre.lagval2d

numpy.polynomial.laguerre.lagval2d(x, y, c) [source]

Evaluate a 2-D Laguerre series at points (x, y).

This function returns the values:

The parameters x and y are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars and they must have the same shape after conversion. In either case, either x and y or their elements must support multiplication and addition both with themselves and with the elements of c.

If c is a 1-D array a one is implicitly appended to its shape to make it 2-D. The shape of the result will be c.shape[2:] + x.shape.

Parameters:

x, y : array_like, compatible objects

The two dimensional series is evaluated at the points (x, y), where x and y must have the same shape. If x or y is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and if it isn’t an ndarray it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j is contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional polynomial at points formed with pairs of corresponding values from x and y.

See also

lagval, laggrid2d, lagval3d, laggrid3d

Notes


numpy.polynomial.laguerre.lagval3d

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagval2d

Next topic

numpy.polynomial.laguerre.laggrid2d

numpy.polynomial.laguerre.lagval3d

numpy.polynomial.laguerre.lagval3d(x, y, z, c) [source]

Evaluate a 3-D Laguerre series at points (x, y, z).

This function returns the values:

The parameters x, y, and z are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars and they must have the same shape after conversion. In either case, either x, y, and z or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than 3 dimensions, ones are implicitly appended to its shape to make it 3-D. The shape of the result will be c.shape[3:] + x.shape.

Parameters:

x, y, z : array_like, compatible object

The three dimensional series is evaluated at the points (x, y, z), where x, y, and z must have the same shape. If any of x, y, or z is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and if it isn’t an ndarray it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j,k is contained in c[i,j,k]. If c has dimension greater than 3 the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the multidimension polynomial on points formed with triples of corresponding values from x, y, and z.

See also

lagval, lagval2d, laggrid2d, laggrid3d

Notes


numpy.polynomial.laguerre.laggrid2d

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagval3d

Next topic

numpy.polynomial.laguerre.laggrid3d

numpy.polynomial.laguerre.laggrid2d

numpy.polynomial.laguerre.laggrid2d(x, y, c) [source]

Evaluate a 2-D Laguerre series on the Cartesian product of x and y.

This function returns the values:

where the points (a, b) consist of all pairs formed by taking a from x and b from y. The resulting points form a grid with x in the first dimension and y in the second.

The parameters x and y are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars. In either case, either x and y or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than two dimensions, ones are implicitly appended to its shape to make it 2-D. The shape of the result will be c.shape[2:] + x.shape + y.shape.

Parameters:

x, y : array_like, compatible objects

The two dimensional series is evaluated at the points in the Cartesian product of x and y. If x or y is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and, if it isn’t an ndarray, it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j is contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional Chebyshev series at points in the Cartesian product of x and y.

See also

lagval, lagval2d, lagval3d, laggrid3d

Notes


numpy.polynomial.laguerre.laggrid3d

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.laggrid2d

Next topic

numpy.polynomial.laguerre.lagroots

numpy.polynomial.laguerre.laggrid3d

numpy.polynomial.laguerre.laggrid3d(x, y, z, c) [source]

Evaluate a 3-D Laguerre series on the Cartesian product of x, y, and z.

This function returns the values:

where the points (a, b, c) consist of all triples formed by taking a from x, b from y, and c from z. The resulting points form a grid with x in the first dimension, y in the second, and z in the third.

The parameters x, y, and z are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars. In either case, either x, y, and z or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than three dimensions, ones are implicitly appended to its shape to make it 3-D. The shape of the result will be c.shape[3:] + x.shape + y.shape + z.shape.

Parameters:

x, y, z : array_like, compatible objects

The three dimensional series is evaluated at the points in the Cartesian product of x, y, and z. If x,`y`, or z is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and, if it isn’t an ndarray, it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree i,j are contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional polynomial at points in the Cartesian product of x and y.

See also

lagval, lagval2d, laggrid2d, lagval3d

Notes


numpy.polynomial.laguerre.lagroots

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.laggrid3d

Next topic

numpy.polynomial.laguerre.lagfromroots

numpy.polynomial.laguerre.lagroots

numpy.polynomial.laguerre.lagroots(c) [source]

Compute the roots of a Laguerre series.

Return the roots (a.k.a. “zeros”) of the polynomial

Parameters:

c : 1-D array_like

1-D array of coefficients.
Returns:

out : ndarray

Array of the roots of the series. If all the roots are real, then out is also real, otherwise it is complex.

See also

polyroots, legroots, chebroots, hermroots, hermeroots

Notes

The root estimates are obtained as the eigenvalues of the companion matrix, Roots far from the origin of the complex plane may have large errors due to the numerical instability of the series for such values. Roots with multiplicity greater than 1 will also show larger errors as the value of the series near such points is relatively insensitive to errors in the roots. Isolated roots near the origin can be improved by a few iterations of Newton’s method.

The Laguerre series basis polynomials aren’t powers of x so the results of this function may seem unintuitive.

Examples

>>> from numpy.polynomial.laguerre import lagroots, lagfromroots
>>> coef = lagfromroots([0, 1, 2])
>>> coef
array([  2.,  -8.,  12.,  -6.])
>>> lagroots(coef)
array([ -4.44089210e-16,   1.00000000e+00,   2.00000000e+00])


numpy.polynomial.laguerre.lagfromroots

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagroots

Next topic

numpy.polynomial.laguerre.lagfit

numpy.polynomial.laguerre.lagfromroots

numpy.polynomial.laguerre.lagfromroots(roots) [source]

Generate a Laguerre series with given roots.

The function returns the coefficients of the polynomial

p(x) = (x - r_0) * (x - r_1) * ... * (x - r_n),

in Laguerre form, where the r_n are the roots specified in roots. If a zero has multiplicity n, then it must appear in roots n times. For instance, if 2 is a root of multiplicity three and 3 is a root of multiplicity 2, then roots looks something like [2, 2, 2, 3, 3]. The roots can appear in any order.

If the returned coefficients are c, then

p(x) = c_0 + c_1 * L_1(x) + ... + c_n * L_n(x)

The coefficient of the last term is not generally 1 for monic polynomials in Laguerre form.

Parameters:

roots : array_like

Sequence containing the roots.
Returns:

out : ndarray

1-D array of coefficients. If all roots are real then out is a real array, if some of the roots are complex, then out is complex even if all the coefficients in the result are real (see Examples below).

See also

polyfromroots, legfromroots, chebfromroots, hermfromroots, hermefromroots.

Examples

>>> from numpy.polynomial.laguerre import lagfromroots, lagval
>>> coef = lagfromroots((-1, 0, 1))
>>> lagval((-1, 0, 1), coef)
array([ 0.,  0.,  0.])
>>> coef = lagfromroots((-1j, 1j))
>>> lagval((-1j, 1j), coef)
array([ 0.+0.j,  0.+0.j])


numpy.polynomial.laguerre.lagfit

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagfromroots

Next topic

numpy.polynomial.laguerre.lagvander

numpy.polynomial.laguerre.lagfit

numpy.polynomial.laguerre.lagfit(x, y, deg, rcond=None, full=False, w=None) [source]

Least squares fit of Laguerre series to data.

Return the coefficients of a Laguerre series of degree deg that is the least squares fit to the data values y given at points x. If y is 1-D the returned coefficients will also be 1-D. If y is 2-D multiple fits are done, one for each column of y, and the resulting coefficients are stored in the corresponding columns of a 2-D return. The fitted polynomial(s) are in the form

p(x) = c_0 + c_1 * L_1(x) + ... + c_n * L_n(x),

where n is deg.

Parameters:

x : array_like, shape (M,)

x-coordinates of the M sample points (x[i], y[i]).

y : array_like, shape (M,) or (M, K)

y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column.

deg : int

Degree of the fitting polynomial

rcond : float, optional

Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)*eps, where eps is the relative precision of the float type, about 2e-16 in most cases.

full : bool, optional

Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned.

w : array_like, shape (M,), optional

Weights. If not None, the contribution of each point (x[i],y[i]) to the fit is weighted by w[i]. Ideally the weights are chosen so that the errors of the products w[i]*y[i] all have the same variance. The default value is None.
Returns:

coef : ndarray, shape (M,) or (M, K)

Laguerre coefficients ordered from low to high. If y was 2-D, the coefficients for the data in column k of y are in column k.

[residuals, rank, singular_values, rcond] : list

These values are only returned if full = True

resid – sum of squared residuals of the least squares fit rank – the numerical rank of the scaled Vandermonde matrix sv – singular values of the scaled Vandermonde matrix rcond – value of rcond.

For more details, see linalg.lstsq.
Warns:

RankWarning

The rank of the coefficient matrix in the least-squares fit is deficient. The warning is only raised if full = False. The warnings can be turned off by

>>> import warnings
>>> warnings.simplefilter('ignore', RankWarning)

See also

chebfit, legfit, polyfit, hermfit, hermefit

lagval
Evaluates a Laguerre series.
lagvander
pseudo Vandermonde matrix of Laguerre series.
lagweight
Laguerre weight function.
linalg.lstsq
Computes a least-squares fit from the matrix.
scipy.interpolate.UnivariateSpline
Computes spline fits.

Notes

The solution is the coefficients of the Laguerre series p that minimizes the sum of the weighted squared errors

where the [image] are the weights. This problem is solved by setting up as the (typically) overdetermined matrix equation

V(x) * c = w * y,

where V is the weighted pseudo Vandermonde matrix of x, c are the coefficients to be solved for, w are the weights, and y are the observed values. This equation is then solved using the singular value decomposition of V.

If some of the singular values of V are so small that they are neglected, then a RankWarning will be issued. This means that the coefficient values may be poorly determined. Using a lower order fit will usually get rid of the warning. The rcond parameter can also be set to a value smaller than its default, but the resulting fit may be spurious and have large contributions from roundoff error.

Fits using Laguerre series are probably most useful when the data can be approximated by sqrt(w(x)) * p(x), where w(x) is the Laguerre weight. In that case the weight sqrt(w(x[i]) should be used together with data values y[i]/sqrt(w(x[i]). The weight function is available as lagweight.

References

[R63] Wikipedia, “Curve fitting”, http://en.wikipedia.org/wiki/Curve_fitting

Examples

>>> from numpy.polynomial.laguerre import lagfit, lagval
>>> x = np.linspace(0, 10)
>>> err = np.random.randn(len(x))/10
>>> y = lagval(x, [1, 2, 3]) + err
>>> lagfit(x, y, 2)
array([ 0.96971004,  2.00193749,  3.00288744])


numpy.polynomial.laguerre.lagvander

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagfit

Next topic

numpy.polynomial.laguerre.lagvander2d

numpy.polynomial.laguerre.lagvander

numpy.polynomial.laguerre.lagvander(x, deg) [source]

Pseudo-Vandermonde matrix of given degree.

Returns the pseudo-Vandermonde matrix of degree deg and sample points x. The pseudo-Vandermonde matrix is defined by

V[..., i] = L_i(x)

where 0 <= i <= deg. The leading indices of V index the elements of x and the last index is the degree of the Laguerre polynomial.

If c is a 1-D array of coefficients of length n + 1 and V is the array V = lagvander(x, n), then np.dot(V, c) and lagval(x, c) are the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of Laguerre series of the same degree and sample points.

Parameters:

x : array_like

Array of points. The dtype is converted to float64 or complex128 depending on whether any of the elements are complex. If x is scalar it is converted to a 1-D array.

deg : int

Degree of the resulting matrix.
Returns:

vander : ndarray

The pseudo-Vandermonde matrix. The shape of the returned matrix is x.shape + (deg + 1,), where The last index is the degree of the corresponding Laguerre polynomial. The dtype will be the same as the converted x.

Examples

>>> from numpy.polynomial.laguerre import lagvander
>>> x = np.array([0, 1, 2])
>>> lagvander(x, 3)
array([[ 1.        ,  1.        ,  1.        ,  1.        ],
       [ 1.        ,  0.        , -0.5       , -0.66666667],
       [ 1.        , -1.        , -1.        , -0.33333333]])


numpy.polynomial.laguerre.lagvander2d

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagvander

Next topic

numpy.polynomial.laguerre.lagvander3d

numpy.polynomial.laguerre.lagvander2d

numpy.polynomial.laguerre.lagvander2d(x, y, deg) [source]

Pseudo-Vandermonde matrix of given degrees.

Returns the pseudo-Vandermonde matrix of degrees deg and sample points (x, y). The pseudo-Vandermonde matrix is defined by

V[..., deg[1]*i + j] = L_i(x) * L_j(y),

where 0 <= i <= deg[0] and 0 <= j <= deg[1]. The leading indices of V index the points (x, y) and the last index encodes the degrees of the Laguerre polynomials.

If V = lagvander2d(x, y, [xdeg, ydeg]), then the columns of V correspond to the elements of a 2-D coefficient array c of shape (xdeg + 1, ydeg + 1) in the order

c_{00}, c_{01}, c_{02} ... , c_{10}, c_{11}, c_{12} ...

and np.dot(V, c.flat) and lagval2d(x, y, c) will be the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of 2-D Laguerre series of the same degrees and sample points.

Parameters:

x, y : array_like

Arrays of point coordinates, all of the same shape. The dtypes will be converted to either float64 or complex128 depending on whether any of the elements are complex. Scalars are converted to 1-D arrays.

deg : list of ints

List of maximum degrees of the form [x_deg, y_deg].
Returns:

vander2d : ndarray

The shape of the returned matrix is x.shape + (order,), where order = (deg[0]+1)*(deg([1]+1). The dtype will be the same as the converted x and y.

See also

lagvander, lagvander3d., lagval3d

Notes


numpy.polynomial.laguerre.lagvander3d

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagvander2d

Next topic

numpy.polynomial.laguerre.lagder

numpy.polynomial.laguerre.lagvander3d

numpy.polynomial.laguerre.lagvander3d(x, y, z, deg) [source]

Pseudo-Vandermonde matrix of given degrees.

Returns the pseudo-Vandermonde matrix of degrees deg and sample points (x, y, z). If l, m, n are the given degrees in x, y, z, then The pseudo-Vandermonde matrix is defined by

V[..., (m+1)(n+1)i + (n+1)j + k] = L_i(x)*L_j(y)*L_k(z),

where 0 <= i <= l, 0 <= j <= m, and 0 <= j <= n. The leading indices of V index the points (x, y, z) and the last index encodes the degrees of the Laguerre polynomials.

If V = lagvander3d(x, y, z, [xdeg, ydeg, zdeg]), then the columns of V correspond to the elements of a 3-D coefficient array c of shape (xdeg + 1, ydeg + 1, zdeg + 1) in the order

c_{000}, c_{001}, c_{002},... , c_{010}, c_{011}, c_{012},...

and np.dot(V, c.flat) and lagval3d(x, y, z, c) will be the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of 3-D Laguerre series of the same degrees and sample points.

Parameters:

x, y, z : array_like

Arrays of point coordinates, all of the same shape. The dtypes will be converted to either float64 or complex128 depending on whether any of the elements are complex. Scalars are converted to 1-D arrays.

deg : list of ints

List of maximum degrees of the form [x_deg, y_deg, z_deg].
Returns:

vander3d : ndarray

The shape of the returned matrix is x.shape + (order,), where order = (deg[0]+1)*(deg([1]+1)*(deg[2]+1). The dtype will be the same as the converted x, y, and z.

See also

lagvander, lagvander3d., lagval3d

Notes


numpy.polynomial.laguerre.lagder

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagvander3d

Next topic

numpy.polynomial.laguerre.lagint

numpy.polynomial.laguerre.lagder

numpy.polynomial.laguerre.lagder(c, m=1, scl=1, axis=0) [source]

Differentiate a Laguerre series.

Returns the Laguerre series coefficients c differentiated m times along axis. At each iteration the result is multiplied by scl (the scaling factor is for use in a linear change of variable). The argument c is an array of coefficients from low to high degree along each axis, e.g., [1,2,3] represents the series 1*L_0 + 2*L_1 + 3*L_2 while [[1,2],[1,2]] represents 1*L_0(x)*L_0(y) + 1*L_1(x)*L_0(y) + 2*L_0(x)*L_1(y) + 2*L_1(x)*L_1(y) if axis=0 is x and axis=1 is y.

Parameters:

c : array_like

Array of Laguerre series coefficients. If c is multidimensional the different axis correspond to different variables with the degree in each axis given by the corresponding index.

m : int, optional

Number of derivatives taken, must be non-negative. (Default: 1)

scl : scalar, optional

Each differentiation is multiplied by scl. The end result is multiplication by scl**m. This is for use in a linear change of variable. (Default: 1)

axis : int, optional

Axis over which the derivative is taken. (Default: 0).

New in version 1.7.0.
Returns:

der : ndarray

Laguerre series of the derivative.

See also

lagint

Notes

In general, the result of differentiating a Laguerre series does not resemble the same operation on a power series. Thus the result of this function may be “unintuitive,” albeit correct; see Examples section below.

Examples

>>> from numpy.polynomial.laguerre import lagder
>>> lagder([ 1.,  1.,  1., -3.])
array([ 1.,  2.,  3.])
>>> lagder([ 1.,  0.,  0., -4.,  3.], m=2)
array([ 1.,  2.,  3.])


numpy.polynomial.laguerre.lagint

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagder

Next topic

numpy.polynomial.laguerre.lagadd

numpy.polynomial.laguerre.lagint

numpy.polynomial.laguerre.lagint(c, m=1, k=[], lbnd=0, scl=1, axis=0) [source]

Integrate a Laguerre series.

Returns the Laguerre series coefficients c integrated m times from lbnd along axis. At each iteration the resulting series is multiplied by scl and an integration constant, k, is added. The scaling factor is for use in a linear change of variable. (“Buyer beware”: note that, depending on what one is doing, one may want scl to be the reciprocal of what one might expect; for more information, see the Notes section below.) The argument c is an array of coefficients from low to high degree along each axis, e.g., [1,2,3] represents the series L_0 + 2*L_1 + 3*L_2 while [[1,2],[1,2]] represents 1*L_0(x)*L_0(y) + 1*L_1(x)*L_0(y) + 2*L_0(x)*L_1(y) + 2*L_1(x)*L_1(y) if axis=0 is x and axis=1 is y.

Parameters:

c : array_like

Array of Laguerre series coefficients. If c is multidimensional the different axis correspond to different variables with the degree in each axis given by the corresponding index.

m : int, optional

Order of integration, must be positive. (Default: 1)

k : {[], list, scalar}, optional

Integration constant(s). The value of the first integral at lbnd is the first value in the list, the value of the second integral at lbnd is the second value, etc. If k == [] (the default), all constants are set to zero. If m == 1, a single scalar can be given instead of a list.

lbnd : scalar, optional

The lower bound of the integral. (Default: 0)

scl : scalar, optional

Following each integration the result is multiplied by scl before the integration constant is added. (Default: 1)

axis : int, optional

Axis over which the integral is taken. (Default: 0).

New in version 1.7.0.
Returns:

S : ndarray

Laguerre series coefficients of the integral.
Raises:

ValueError

If m < 0, len(k) > m, np.isscalar(lbnd) == False, or np.isscalar(scl) == False.

See also

lagder

Notes

Note that the result of each integration is multiplied by scl. Why is this important to note? Say one is making a linear change of variable u = ax + b in an integral relative to x. Then .. math::dx = du/a, so one will need to set scl equal to 1/a - perhaps not what one would have first thought.

Also note that, in general, the result of integrating a C-series needs to be “reprojected” onto the C-series basis set. Thus, typically, the result of this function is “unintuitive,” albeit correct; see Examples section below.

Examples

>>> from numpy.polynomial.laguerre import lagint
>>> lagint([1,2,3])
array([ 1.,  1.,  1., -3.])
>>> lagint([1,2,3], m=2)
array([ 1.,  0.,  0., -4.,  3.])
>>> lagint([1,2,3], k=1)
array([ 2.,  1.,  1., -3.])
>>> lagint([1,2,3], lbnd=-1)
array([ 11.5,   1. ,   1. ,  -3. ])
>>> lagint([1,2], m=2, k=[1,2], lbnd=-1)
array([ 11.16666667,  -5.        ,  -3.        ,   2.        ])


numpy.polynomial.laguerre.lagadd

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagint

Next topic

numpy.polynomial.laguerre.lagsub

numpy.polynomial.laguerre.lagadd

numpy.polynomial.laguerre.lagadd(c1, c2) [source]

Add one Laguerre series to another.

Returns the sum of two Laguerre series c1 + c2. The arguments are sequences of coefficients ordered from lowest order term to highest, i.e., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Laguerre series coefficients ordered from low to high.
Returns:

out : ndarray

Array representing the Laguerre series of their sum.

See also

lagsub, lagmul, lagdiv, lagpow

Notes

Unlike multiplication, division, etc., the sum of two Laguerre series is a Laguerre series (without having to “reproject” the result onto the basis set) so addition, just like that of “standard” polynomials, is simply “component-wise.”

Examples

>>> from numpy.polynomial.laguerre import lagadd
>>> lagadd([1, 2, 3], [1, 2, 3, 4])
array([ 2.,  4.,  6.,  4.])


numpy.polynomial.laguerre.lagsub

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagadd

Next topic

numpy.polynomial.laguerre.lagmul

numpy.polynomial.laguerre.lagsub

numpy.polynomial.laguerre.lagsub(c1, c2) [source]

Subtract one Laguerre series from another.

Returns the difference of two Laguerre series c1 - c2. The sequences of coefficients are from lowest order term to highest, i.e., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Laguerre series coefficients ordered from low to high.
Returns:

out : ndarray

Of Laguerre series coefficients representing their difference.

See also

lagadd, lagmul, lagdiv, lagpow

Notes

Unlike multiplication, division, etc., the difference of two Laguerre series is a Laguerre series (without having to “reproject” the result onto the basis set) so subtraction, just like that of “standard” polynomials, is simply “component-wise.”

Examples

>>> from numpy.polynomial.laguerre import lagsub
>>> lagsub([1, 2, 3, 4], [1, 2, 3])
array([ 0.,  0.,  0.,  4.])


numpy.polynomial.laguerre.lagmul

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagsub

Next topic

numpy.polynomial.laguerre.lagmulx

numpy.polynomial.laguerre.lagmul

numpy.polynomial.laguerre.lagmul(c1, c2) [source]

Multiply one Laguerre series by another.

Returns the product of two Laguerre series c1 * c2. The arguments are sequences of coefficients, from lowest order “term” to highest, e.g., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Laguerre series coefficients ordered from low to high.
Returns:

out : ndarray

Of Laguerre series coefficients representing their product.

See also

lagadd, lagsub, lagdiv, lagpow

Notes

In general, the (polynomial) product of two C-series results in terms that are not in the Laguerre polynomial basis set. Thus, to express the product as a Laguerre series, it is necessary to “reproject” the product onto said basis set, which may produce “unintuitive” (but correct) results; see Examples section below.

Examples

>>> from numpy.polynomial.laguerre import lagmul
>>> lagmul([1, 2, 3], [0, 1, 2])
array([  8., -13.,  38., -51.,  36.])


numpy.polynomial.laguerre.lagmulx

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagmul

Next topic

numpy.polynomial.laguerre.lagdiv

numpy.polynomial.laguerre.lagmulx

numpy.polynomial.laguerre.lagmulx(c) [source]

Multiply a Laguerre series by x.

Multiply the Laguerre series c by x, where x is the independent variable.

Parameters:

c : array_like

1-D array of Laguerre series coefficients ordered from low to high.
Returns:

out : ndarray

Array representing the result of the multiplication.

Notes

The multiplication uses the recursion relationship for Laguerre polynomials in the form

xP_i(x) = (-(i + 1)*P_{i + 1}(x) + (2i + 1)P_{i}(x) - iP_{i - 1}(x))

Examples

>>> from numpy.polynomial.laguerre import lagmulx
>>> lagmulx([1, 2, 3])
array([ -1.,  -1.,  11.,  -9.])


numpy.polynomial.laguerre.lagdiv

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagmulx

Next topic

numpy.polynomial.laguerre.lagpow

numpy.polynomial.laguerre.lagdiv

numpy.polynomial.laguerre.lagdiv(c1, c2) [source]

Divide one Laguerre series by another.

Returns the quotient-with-remainder of two Laguerre series c1 / c2. The arguments are sequences of coefficients from lowest order “term” to highest, e.g., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Laguerre series coefficients ordered from low to high.
Returns:

[quo, rem] : ndarrays

Of Laguerre series coefficients representing the quotient and remainder.

See also

lagadd, lagsub, lagmul, lagpow

Notes

In general, the (polynomial) division of one Laguerre series by another results in quotient and remainder terms that are not in the Laguerre polynomial basis set. Thus, to express these results as a Laguerre series, it is necessary to “reproject” the results onto the Laguerre basis set, which may produce “unintuitive” (but correct) results; see Examples section below.

Examples

>>> from numpy.polynomial.laguerre import lagdiv
>>> lagdiv([  8., -13.,  38., -51.,  36.], [0, 1, 2])
(array([ 1.,  2.,  3.]), array([ 0.]))
>>> lagdiv([  9., -12.,  38., -51.,  36.], [0, 1, 2])
(array([ 1.,  2.,  3.]), array([ 1.,  1.]))


numpy.polynomial.laguerre.lagpow

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagdiv

Next topic

numpy.polynomial.laguerre.laggauss

numpy.polynomial.laguerre.lagpow

numpy.polynomial.laguerre.lagpow(c, pow, maxpower=16) [source]

Raise a Laguerre series to a power.

Returns the Laguerre series c raised to the power pow. The argument c is a sequence of coefficients ordered from low to high. i.e., [1,2,3] is the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c : array_like

1-D array of Laguerre series coefficients ordered from low to high.

pow : integer

Power to which the series will be raised

maxpower : integer, optional

Maximum power allowed. This is mainly to limit growth of the series to unmanageable size. Default is 16
Returns:

coef : ndarray

Laguerre series of power.

See also

lagadd, lagsub, lagmul, lagdiv

Examples

>>> from numpy.polynomial.laguerre import lagpow
>>> lagpow([1, 2, 3], 2)
array([ 14., -16.,  56., -72.,  54.])


numpy.polynomial.laguerre.laggauss

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagpow

Next topic

numpy.polynomial.laguerre.lagweight

numpy.polynomial.laguerre.laggauss

numpy.polynomial.laguerre.laggauss(deg) [source]

Gauss-Laguerre quadrature.

Computes the sample points and weights for Gauss-Laguerre quadrature. These sample points and weights will correctly integrate polynomials of degree 2*deg - 1 or less over the interval [image] with the weight function [image].

Parameters:

deg : int

Number of sample points and weights. It must be >= 1.
Returns:

x : ndarray

1-D ndarray containing the sample points.

y : ndarray

1-D ndarray containing the weights.

Notes

The results have only been tested up to degree 100 higher degrees may be problematic. The weights are determined by using the fact that

w_k = c / (L'_n(x_k) * L_{n-1}(x_k))

where c is a constant independent of k and [image] is the k’th root of [image], and then scaling the results to get the right value when integrating 1.


numpy.polynomial.laguerre.lagweight

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.laggauss

Next topic

numpy.polynomial.laguerre.lagcompanion

numpy.polynomial.laguerre.lagweight

numpy.polynomial.laguerre.lagweight(x) [source]

Weight function of the Laguerre polynomials.

The weight function is exp(-x) and the interval of integration is [image]. The Laguerre polynomials are orthogonal, but not normalized, with respect to this weight function.

Parameters:

x : array_like

Values at which the weight function will be computed.
Returns:

w : ndarray

The weight function at x.

Notes


numpy.polynomial.laguerre.lagcompanion

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagweight

Next topic

numpy.polynomial.laguerre.lagdomain

numpy.polynomial.laguerre.lagcompanion

numpy.polynomial.laguerre.lagcompanion(c) [source]

Return the companion matrix of c.

The usual companion matrix of the Laguerre polynomials is already symmetric when c is a basis Laguerre polynomial, so no scaling is applied.

Parameters:

c : array_like

1-D array of Laguerre series coefficients ordered from low to high degree.
Returns:

mat : ndarray

Companion matrix of dimensions (deg, deg).

Notes


numpy.polynomial.laguerre.lagdomain

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagcompanion

Next topic

numpy.polynomial.laguerre.lagzero

numpy.polynomial.laguerre.lagdomain

numpy.polynomial.laguerre.lagdomain = array([0, 1])


numpy.polynomial.laguerre.lagzero

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagdomain

Next topic

numpy.polynomial.laguerre.lagone

numpy.polynomial.laguerre.lagzero

numpy.polynomial.laguerre.lagzero = array([0])


numpy.polynomial.laguerre.lagone

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagzero

Next topic

numpy.polynomial.laguerre.lagx

numpy.polynomial.laguerre.lagone

numpy.polynomial.laguerre.lagone = array([1])


numpy.polynomial.laguerre.lagx

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagone

Next topic

numpy.polynomial.laguerre.lagtrim

numpy.polynomial.laguerre.lagx

numpy.polynomial.laguerre.lagx = array([ 1, -1])


numpy.polynomial.laguerre.lagtrim

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagx

Next topic

numpy.polynomial.laguerre.lagline

numpy.polynomial.laguerre.lagtrim

numpy.polynomial.laguerre.lagtrim(c, tol=0) [source]

Remove “small” “trailing” coefficients from a polynomial.

“Small” means “small in absolute value” and is controlled by the parameter tol; “trailing” means highest order coefficient(s), e.g., in [0, 1, 1, 0, 0] (which represents 0 + x + x**2 + 0*x**3 + 0*x**4) both the 3-rd and 4-th order coefficients would be “trimmed.”

Parameters:

c : array_like

1-d array of coefficients, ordered from lowest order to highest.

tol : number, optional

Trailing (i.e., highest order) elements with absolute value less than or equal to tol (default value is zero) are removed.
Returns:

trimmed : ndarray

1-d array with trailing zeros removed. If the resulting series would be empty, a series containing a single zero is returned.
Raises:

ValueError

If tol < 0

See also

trimseq

Examples

>>> from numpy import polynomial as P
>>> P.trimcoef((0,0,3,0,5,0,0))
array([ 0.,  0.,  3.,  0.,  5.])
>>> P.trimcoef((0,0,1e-3,0,1e-5,0,0),1e-3) # item == tol is trimmed
array([ 0.])
>>> i = complex(0,1) # works for complex
>>> P.trimcoef((3e-4,1e-3*(1-i),5e-4,2e-5*(1+i)), 1e-3)
array([ 0.0003+0.j   ,  0.0010-0.001j])


numpy.polynomial.laguerre.lagline

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagtrim

Next topic

numpy.polynomial.laguerre.lag2poly

numpy.polynomial.laguerre.lagline

numpy.polynomial.laguerre.lagline(off, scl) [source]

Laguerre series whose graph is a straight line.

Parameters:

off, scl : scalars

The specified line is given by off + scl*x.
Returns:

y : ndarray

This module’s representation of the Laguerre series for off + scl*x.

See also

polyline, chebline

Examples

>>> from numpy.polynomial.laguerre import lagline, lagval
>>> lagval(0,lagline(3, 2))
3.0
>>> lagval(1,lagline(3, 2))
5.0


numpy.polynomial.laguerre.lag2poly

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lagline

Next topic

numpy.polynomial.laguerre.poly2lag

numpy.polynomial.laguerre.lag2poly

numpy.polynomial.laguerre.lag2poly(c) [source]

Convert a Laguerre series to a polynomial.

Convert an array representing the coefficients of a Laguerre series, ordered from lowest degree to highest, to an array of the coefficients of the equivalent polynomial (relative to the “standard” basis) ordered from lowest to highest degree.

Parameters:

c : array_like

1-D array containing the Laguerre series coefficients, ordered from lowest order term to highest.
Returns:

pol : ndarray

1-D array containing the coefficients of the equivalent polynomial (relative to the “standard” basis) ordered from lowest order term to highest.

See also

poly2lag

Notes

The easy way to do conversions between polynomial basis sets is to use the convert method of a class instance.

Examples

>>> from numpy.polynomial.laguerre import lag2poly
>>> lag2poly([ 23., -63.,  58., -18.])
array([ 0.,  1.,  2.,  3.])


numpy.polynomial.laguerre.poly2lag

  • Polynomials
  • Polynomial Package
  • Laguerre Module (numpy.polynomial.laguerre)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.laguerre.lag2poly

Next topic

Hermite Module, “Physicists’” (numpy.polynomial.hermite)

numpy.polynomial.laguerre.poly2lag

numpy.polynomial.laguerre.poly2lag(pol) [source]

Convert a polynomial to a Laguerre series.

Convert an array representing the coefficients of a polynomial (relative to the “standard” basis) ordered from lowest degree to highest, to an array of the coefficients of the equivalent Laguerre series, ordered from lowest to highest degree.

Parameters:

pol : array_like

1-D array containing the polynomial coefficients
Returns:

c : ndarray

1-D array containing the coefficients of the equivalent Laguerre series.

See also

lag2poly

Notes

The easy way to do conversions between polynomial basis sets is to use the convert method of a class instance.

Examples

>>> from numpy.polynomial.laguerre import poly2lag
>>> poly2lag(np.arange(4))
array([ 23., -63.,  58., -18.])


Hermite Module, “Physicists’” (numpy.polynomial.hermite)

  • Polynomials
  • Polynomial Package
  • index
  • next
  • previous

Table Of Contents

  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
    • Hermite Class
    • Basics
    • Fitting
    • Calculus
    • Algebra
    • Quadrature
    • Miscellaneous

Previous topic

numpy.polynomial.laguerre.poly2lag

Next topic

numpy.polynomial.hermite.Hermite

Hermite Module, “Physicists’” (numpy.polynomial.hermite)

New in version 1.6.0.

This module provides a number of objects (mostly functions) useful for dealing with Hermite series, including a Hermite class that encapsulates the usual arithmetic operations. (General information on how this module represents and works with such polynomials is in the docstring for its “parent” sub-package, numpy.polynomial).

Hermite Class

Hermite(coef[, domain, window]) An Hermite series class.

Basics

hermval(x, c[, tensor]) | Evaluate an Hermite series at points x.
hermval2d(x, y, c) | Evaluate a 2-D Hermite series at points (x, y).
hermval3d(x, y, z, c) | Evaluate a 3-D Hermite series at points (x, y, z).
hermgrid2d(x, y, c) | Evaluate a 2-D Hermite series on the Cartesian product of x and y.
hermgrid3d(x, y, z, c) | Evaluate a 3-D Hermite series on the Cartesian product of x, y, and z.
hermroots(c) | Compute the roots of a Hermite series.
hermfromroots(roots) | Generate a Hermite series with given roots.

Fitting

hermfit(x, y, deg[, rcond, full, w]) | Least squares fit of Hermite series to data.
hermvander(x, deg) | Pseudo-Vandermonde matrix of given degree.
hermvander2d(x, y, deg) | Pseudo-Vandermonde matrix of given degrees.
hermvander3d(x, y, z, deg) | Pseudo-Vandermonde matrix of given degrees.

Calculus

hermder(c[, m, scl, axis]) | Differentiate a Hermite series.
hermint(c[, m, k, lbnd, scl, axis]) | Integrate a Hermite series.

Algebra

hermadd(c1, c2) | Add one Hermite series to another.
hermsub(c1, c2) | Subtract one Hermite series from another.
hermmul(c1, c2) | Multiply one Hermite series by another.
hermmulx(c) | Multiply a Hermite series by x.
hermdiv(c1, c2) | Divide one Hermite series by another.
hermpow(c, pow[, maxpower]) | Raise a Hermite series to a power.

Quadrature

hermgauss(deg) | Gauss-Hermite quadrature.
hermweight(x) | Weight function of the Hermite polynomials.

Miscellaneous

hermcompanion(c) | Return the scaled companion matrix of c.
hermdomain |
hermzero |
hermone |
hermx |
hermtrim(c[, tol]) | Remove “small” “trailing” coefficients from a polynomial.
hermline(off, scl) | Hermite series whose graph is a straight line.
herm2poly(c) | Convert a Hermite series to a polynomial.
poly2herm(pol) | Convert a polynomial to a Hermite series.


numpy.polynomial.hermite.Hermite

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.poly2herm

Next topic

numpy.polynomial.hermite.Hermite.__call__

numpy.polynomial.hermite.Hermite

class numpy.polynomial.hermite.Hermite(coef, domain=None, window=None) [source]

An Hermite series class.

The Hermite class provides the standard Python numerical methods ‘+’, ‘-‘, ‘*’, ‘//’, ‘%’, ‘divmod’, ‘**’, and ‘()’ as well as the attributes and methods listed in the ABCPolyBase documentation.

Parameters:

coef : array_like

Laguerre coefficients in order of increasing degree, i.e, (1, 2, 3) gives 1*H_0(x) + 2*H_1(X) + 3*H_2(x).

domain : (2,) array_like, optional

Domain to use. The interval [domain[0], domain[1]] is mapped to the interval [window[0], window[1]] by shifting and scaling. The default value is [-1, 1].

window : (2,) array_like, optional

Window, see domain for its use. The default value is [-1, 1].

New in version 1.6.0.

Methods

__call__(arg)
basis(deg[, domain, window]) | Series basis polynomial of degree deg.
cast(series[, domain, window]) | Convert series to series of this class.
convert([domain, kind, window]) | Convert series to a different kind and/or domain and/or window.
copy() | Return a copy.
cutdeg(deg) | Truncate series to the given degree.
degree() | The degree of the series.
deriv([m]) | Differentiate.
fit(x, y, deg[, domain, rcond, full, w, window]) | Least squares fit to data.
fromroots(roots[, domain, window]) | Return series instance that has the specified roots.
has_samecoef(other) | Check if coefficients match.
has_samedomain(other) | Check if domains match.
has_sametype(other) | Check if types match.
has_samewindow(other) | Check if windows match.
identity([domain, window]) | Identity function.
integ([m, k, lbnd]) | Integrate.
linspace([n, domain]) | Return x, y values at equally spaced points in domain.
mapparms() | Return the mapping parameters.
roots() | Return the roots of the series polynomial.
trim([tol]) | Remove trailing coefficients
truncate(size) | Truncate series to length size.


numpy.polynomial.hermite.Hermite.__call__

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite

Next topic

numpy.polynomial.hermite.Hermite.basis

numpy.polynomial.hermite.Hermite.__call__

Hermite.__call__(arg) [source]


numpy.polynomial.hermite.Hermite.basis

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.__call__

Next topic

numpy.polynomial.hermite.Hermite.cast

numpy.polynomial.hermite.Hermite.basis

classmethod Hermite.basis(deg, domain=None, window=None) [source]

Series basis polynomial of degree deg.

Returns the series representing the basis polynomial of degree deg.

New in version 1.7.0.

Parameters:

deg : int

Degree of the basis polynomial for the series. Must be >= 0.

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

A series with the coefficient of the deg term set to one and all others zero.


numpy.polynomial.hermite.Hermite.cast

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.basis

Next topic

numpy.polynomial.hermite.Hermite.convert

numpy.polynomial.hermite.Hermite.cast

classmethod Hermite.cast(series, domain=None, window=None) [source]

Convert series to series of this class.

The series is expected to be an instance of some polynomial series of one of the types supported by by the numpy.polynomial module, but could be some other class that supports the convert method.

New in version 1.7.0.

Parameters:

series : series

The series instance to be converted.

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

A series of the same kind as the calling class and equal to series when evaluated.

See also

convert
similar instance method


numpy.polynomial.hermite.Hermite.convert

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.cast

Next topic

numpy.polynomial.hermite.Hermite.copy

numpy.polynomial.hermite.Hermite.convert

Hermite.convert(domain=None, kind=None, window=None) [source]

Convert series to a different kind and/or domain and/or window.

Parameters:

domain : array_like, optional

The domain of the converted series. If the value is None, the default domain of kind is used.

kind : class, optional

The polynomial series type class to which the current instance should be converted. If kind is None, then the class of the current instance is used.

window : array_like, optional

The window of the converted series. If the value is None, the default window of kind is used.
Returns:

new_series : series

The returned class can be of different type than the current instance and/or have a different domain and/or different window.

Notes

Conversion between domains and class types can result in numerically ill defined series.


numpy.polynomial.hermite.Hermite.copy

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.convert

Next topic

numpy.polynomial.hermite.Hermite.cutdeg

numpy.polynomial.hermite.Hermite.copy

Hermite.copy() [source]

Return a copy.

Returns:

new_series : series

Copy of self.


numpy.polynomial.hermite.Hermite.cutdeg

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.copy

Next topic

numpy.polynomial.hermite.Hermite.degree

numpy.polynomial.hermite.Hermite.cutdeg

Hermite.cutdeg(deg) [source]

Truncate series to the given degree.

Reduce the degree of the series to deg by discarding the high order terms. If deg is greater than the current degree a copy of the current series is returned. This can be useful in least squares where the coefficients of the high degree terms may be very small.

New in version 1.5.0.

Parameters:

deg : non-negative int

The series is reduced to degree deg by discarding the high order terms. The value of deg must be a non-negative integer.
Returns:

new_series : series

New instance of series with reduced degree.


numpy.polynomial.hermite.Hermite.degree

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.cutdeg

Next topic

numpy.polynomial.hermite.Hermite.deriv

numpy.polynomial.hermite.Hermite.degree

Hermite.degree() [source]

The degree of the series.

New in version 1.5.0.

Returns:

degree : int

Degree of the series, one less than the number of coefficients.


numpy.polynomial.hermite.Hermite.deriv

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.degree

Next topic

numpy.polynomial.hermite.Hermite.fit

numpy.polynomial.hermite.Hermite.deriv

Hermite.deriv(m=1) [source]

Differentiate.

Return a series instance of that is the derivative of the current series.

Parameters:

m : non-negative int

The number of integrations to perform.
Returns:

new_series : series

A new series representing the derivative. The domain is the same as the domain of the differentiated series.


numpy.polynomial.hermite.Hermite.fit

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.deriv

Next topic

numpy.polynomial.hermite.Hermite.fromroots

numpy.polynomial.hermite.Hermite.fit

classmethod Hermite.fit(x, y, deg, domain=None, rcond=None, full=False, w=None, window=None) [source]

Least squares fit to data.

Return a series instance that is the least squares fit to the data y sampled at x. The domain of the returned instance can be specified and this will often result in a superior fit with less chance of ill conditioning.

Parameters:

x : array_like, shape (M,)

x-coordinates of the M sample points (x[i], y[i]).

y : array_like, shape (M,) or (M, K)

y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column.

deg : int

Degree of the fitting polynomial.

domain : {None, [beg, end], []}, optional

Domain to use for the returned series. If None, then a minimal domain that covers the points x is chosen. If [] the class domain is used. The default value was the class domain in NumPy 1.4 and None in later versions. The [] option was added in numpy 1.5.0.

rcond : float, optional

Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)*eps, where eps is the relative precision of the float type, about 2e-16 in most cases.

full : bool, optional

Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned.

w : array_like, shape (M,), optional

Weights. If not None the contribution of each point (x[i],y[i]) to the fit is weighted by w[i]. Ideally the weights are chosen so that the errors of the products w[i]*y[i] all have the same variance. The default value is None.

New in version 1.5.0.

window : {[beg, end]}, optional

Window to use for the returned series. The default value is the default class domain

New in version 1.6.0.
Returns:

new_series : series

A series that represents the least squares fit to the data and has the domain specified in the call.

[resid, rank, sv, rcond] : list

These values are only returned if full = True

resid – sum of squared residuals of the least squares fit rank – the numerical rank of the scaled Vandermonde matrix sv – singular values of the scaled Vandermonde matrix rcond – value of rcond.

For more details, see linalg.lstsq.


numpy.polynomial.hermite.Hermite.fromroots

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.fit

Next topic

numpy.polynomial.hermite.Hermite.has_samecoef

numpy.polynomial.hermite.Hermite.fromroots

classmethod Hermite.fromroots(roots, domain=[], window=None) [source]

Return series instance that has the specified roots.

Returns a series representing the product (x - r[0])*(x - r[1])*...*(x - r[n-1]), where r is a list of roots.

Parameters:

roots : array_like

List of roots.

domain : {[], None, array_like}, optional

Domain for the resulting series. If None the domain is the interval from the smallest root to the largest. If [] the domain is the class domain. The default is [].

window : {None, array_like}, optional

Window for the returned series. If None the class window is used. The default is None.
Returns:

new_series : series

Series with the specified roots.


numpy.polynomial.hermite.Hermite.has_samecoef

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.fromroots

Next topic

numpy.polynomial.hermite.Hermite.has_samedomain

numpy.polynomial.hermite.Hermite.has_samecoef

Hermite.has_samecoef(other) [source]

Check if coefficients match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the coef attribute.
Returns:

bool : boolean

True if the coefficients are the same, False otherwise.


numpy.polynomial.hermite.Hermite.has_samedomain

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.has_samecoef

Next topic

numpy.polynomial.hermite.Hermite.has_sametype

numpy.polynomial.hermite.Hermite.has_samedomain

Hermite.has_samedomain(other) [source]

Check if domains match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the domain attribute.
Returns:

bool : boolean

True if the domains are the same, False otherwise.


numpy.polynomial.hermite.Hermite.has_sametype

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.has_samedomain

Next topic

numpy.polynomial.hermite.Hermite.has_samewindow

numpy.polynomial.hermite.Hermite.has_sametype

Hermite.has_sametype(other) [source]

Check if types match.

New in version 1.7.0.

Parameters:

other : object

Class instance.
Returns:

bool : boolean

True if other is same class as self


numpy.polynomial.hermite.Hermite.has_samewindow

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.has_sametype

Next topic

numpy.polynomial.hermite.Hermite.identity

numpy.polynomial.hermite.Hermite.has_samewindow

Hermite.has_samewindow(other) [source]

Check if windows match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the window attribute.
Returns:

bool : boolean

True if the windows are the same, False otherwise.


numpy.polynomial.hermite.Hermite.identity

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.has_samewindow

Next topic

numpy.polynomial.hermite.Hermite.integ

numpy.polynomial.hermite.Hermite.identity

classmethod Hermite.identity(domain=None, window=None) [source]

Identity function.

If p is the returned series, then p(x) == x for all values of x.

Parameters:

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

Series of representing the identity.


numpy.polynomial.hermite.Hermite.integ

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.identity

Next topic

numpy.polynomial.hermite.Hermite.linspace

numpy.polynomial.hermite.Hermite.integ

Hermite.integ(m=1, k=[], lbnd=None) [source]

Integrate.

Return a series instance that is the definite integral of the current series.

Parameters:

m : non-negative int

The number of integrations to perform.

k : array_like

Integration constants. The first constant is applied to the first integration, the second to the second, and so on. The list of values must less than or equal to m in length and any missing values are set to zero.

lbnd : Scalar

The lower bound of the definite integral.
Returns:

new_series : series

A new series representing the integral. The domain is the same as the domain of the integrated series.


numpy.polynomial.hermite.Hermite.linspace

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.integ

Next topic

numpy.polynomial.hermite.Hermite.mapparms

numpy.polynomial.hermite.Hermite.linspace

Hermite.linspace(n=100, domain=None) [source]

Return x, y values at equally spaced points in domain.

Returns the x, y values at n linearly spaced points across the domain. Here y is the value of the polynomial at the points x. By default the domain is the same as that of the series instance. This method is intended mostly as a plotting aid.

New in version 1.5.0.

Parameters:

n : int, optional

Number of point pairs to return. The default value is 100.

domain : {None, array_like}, optional

If not None, the specified domain is used instead of that of the calling instance. It should be of the form [beg,end]. The default is None which case the class domain is used.
Returns:

x, y : ndarray

x is equal to linspace(self.domain[0], self.domain[1], n) and y is the series evaluated at element of x.


numpy.polynomial.hermite.Hermite.mapparms

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.linspace

Next topic

numpy.polynomial.hermite.Hermite.roots

numpy.polynomial.hermite.Hermite.mapparms

Hermite.mapparms() [source]

Return the mapping parameters.

The returned values define a linear map off + scl*x that is applied to the input arguments before the series is evaluated. The map depends on the domain and window; if the current domain is equal to the window the resulting map is the identity. If the coefficients of the series instance are to be used by themselves outside this class, then the linear function must be substituted for the x in the standard representation of the base polynomials.

Returns:

off, scl : float or complex

The mapping function is defined by off + scl*x.

Notes

If the current domain is the interval [l1, r1] and the window is [l2, r2], then the linear mapping function L is defined by the equations:

L(l1) = l2
L(r1) = r2


numpy.polynomial.hermite.Hermite.roots

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.mapparms

Next topic

numpy.polynomial.hermite.Hermite.trim

numpy.polynomial.hermite.Hermite.roots

Hermite.roots() [source]

Return the roots of the series polynomial.

Compute the roots for the series. Note that the accuracy of the roots decrease the further outside the domain they lie.

Returns:

roots : ndarray

Array containing the roots of the series.


numpy.polynomial.hermite.Hermite.trim

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.roots

Next topic

numpy.polynomial.hermite.Hermite.truncate

numpy.polynomial.hermite.Hermite.trim

Hermite.trim(tol=0) [source]

Remove trailing coefficients

Remove trailing coefficients until a coefficient is reached whose absolute value greater than tol or the beginning of the series is reached. If all the coefficients would be removed the series is set to [0]. A new series instance is returned with the new coefficients. The current instance remains unchanged.

Parameters:

tol : non-negative number.

All trailing coefficients less than tol will be removed.
Returns:

new_series : series

Contains the new set of coefficients.


numpy.polynomial.hermite.Hermite.truncate

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • numpy.polynomial.hermite.Hermite
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.trim

Next topic

numpy.polynomial.hermite.hermval

numpy.polynomial.hermite.Hermite.truncate

Hermite.truncate(size) [source]

Truncate series to length size.

Reduce the series to length size by discarding the high degree terms. The value of size must be a positive integer. This can be useful in least squares where the coefficients of the high degree terms may be very small.

Parameters:

size : positive int

The series is reduced to length size by discarding the high degree terms. The value of size must be a positive integer.
Returns:

new_series : series

New instance of series with truncated coefficients.


numpy.polynomial.hermite.hermval

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.Hermite.truncate

Next topic

numpy.polynomial.hermite.hermval2d

numpy.polynomial.hermite.hermval

numpy.polynomial.hermite.hermval(x, c, tensor=True) [source]

Evaluate an Hermite series at points x.

If c is of length n + 1, this function returns the value:

p(x) = c_0 * H_0(x) + c_1 * H_1(x) + ... + c_n * H_n(x)

The parameter x is converted to an array only if it is a tuple or a list, otherwise it is treated as a scalar. In either case, either x or its elements must support multiplication and addition both with themselves and with the elements of c.

If c is a 1-D array, then p(x) will have the same shape as x. If c is multidimensional, then the shape of the result depends on the value of tensor. If tensor is true the shape will be c.shape[1:] + x.shape. If tensor is false the shape will be c.shape[1:]. Note that scalars have shape (,).

Trailing zeros in the coefficients will be used in the evaluation, so they should be avoided if efficiency is a concern.

Parameters:

x : array_like, compatible object

If x is a list or tuple, it is converted to an ndarray, otherwise it is left unchanged and treated as a scalar. In either case, x or its elements must support addition and multiplication with with themselves and with the elements of c.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree n are contained in c[n]. If c is multidimensional the remaining indices enumerate multiple polynomials. In the two dimensional case the coefficients may be thought of as stored in the columns of c.

tensor : boolean, optional

If True, the shape of the coefficient array is extended with ones on the right, one for each dimension of x. Scalars have dimension 0 for this action. The result is that every column of coefficients in c is evaluated for every element of x. If False, x is broadcast over the columns of c for the evaluation. This keyword is useful when c is multidimensional. The default value is True.

New in version 1.7.0.
Returns:

values : ndarray, algebra_like

The shape of the return value is described above.

See also

hermval2d, hermgrid2d, hermval3d, hermgrid3d

Notes

The evaluation uses Clenshaw recursion, aka synthetic division.

Examples

>>> from numpy.polynomial.hermite import hermval
>>> coef = [1,2,3]
>>> hermval(1, coef)
11.0
>>> hermval([[1,2],[3,4]], coef)
array([[  11.,   51.],
       [ 115.,  203.]])


numpy.polynomial.hermite.hermval2d

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermval

Next topic

numpy.polynomial.hermite.hermval3d

numpy.polynomial.hermite.hermval2d

numpy.polynomial.hermite.hermval2d(x, y, c) [source]

Evaluate a 2-D Hermite series at points (x, y).

This function returns the values:

The parameters x and y are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars and they must have the same shape after conversion. In either case, either x and y or their elements must support multiplication and addition both with themselves and with the elements of c.

If c is a 1-D array a one is implicitly appended to its shape to make it 2-D. The shape of the result will be c.shape[2:] + x.shape.

Parameters:

x, y : array_like, compatible objects

The two dimensional series is evaluated at the points (x, y), where x and y must have the same shape. If x or y is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and if it isn’t an ndarray it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j is contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional polynomial at points formed with pairs of corresponding values from x and y.

See also

hermval, hermgrid2d, hermval3d, hermgrid3d

Notes


numpy.polynomial.hermite.hermval3d

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermval2d

Next topic

numpy.polynomial.hermite.hermgrid2d

numpy.polynomial.hermite.hermval3d

numpy.polynomial.hermite.hermval3d(x, y, z, c) [source]

Evaluate a 3-D Hermite series at points (x, y, z).

This function returns the values:

The parameters x, y, and z are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars and they must have the same shape after conversion. In either case, either x, y, and z or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than 3 dimensions, ones are implicitly appended to its shape to make it 3-D. The shape of the result will be c.shape[3:] + x.shape.

Parameters:

x, y, z : array_like, compatible object

The three dimensional series is evaluated at the points (x, y, z), where x, y, and z must have the same shape. If any of x, y, or z is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and if it isn’t an ndarray it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j,k is contained in c[i,j,k]. If c has dimension greater than 3 the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the multidimensional polynomial on points formed with triples of corresponding values from x, y, and z.

See also

hermval, hermval2d, hermgrid2d, hermgrid3d

Notes


numpy.polynomial.hermite.hermgrid2d

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermval3d

Next topic

numpy.polynomial.hermite.hermgrid3d

numpy.polynomial.hermite.hermgrid2d

numpy.polynomial.hermite.hermgrid2d(x, y, c) [source]

Evaluate a 2-D Hermite series on the Cartesian product of x and y.

This function returns the values:

where the points (a, b) consist of all pairs formed by taking a from x and b from y. The resulting points form a grid with x in the first dimension and y in the second.

The parameters x and y are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars. In either case, either x and y or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than two dimensions, ones are implicitly appended to its shape to make it 2-D. The shape of the result will be c.shape[2:] + x.shape.

Parameters:

x, y : array_like, compatible objects

The two dimensional series is evaluated at the points in the Cartesian product of x and y. If x or y is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and, if it isn’t an ndarray, it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree i,j are contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional polynomial at points in the Cartesian product of x and y.

See also

hermval, hermval2d, hermval3d, hermgrid3d

Notes


numpy.polynomial.hermite.hermgrid3d

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermgrid2d

Next topic

numpy.polynomial.hermite.hermroots

numpy.polynomial.hermite.hermgrid3d

numpy.polynomial.hermite.hermgrid3d(x, y, z, c) [source]

Evaluate a 3-D Hermite series on the Cartesian product of x, y, and z.

This function returns the values:

where the points (a, b, c) consist of all triples formed by taking a from x, b from y, and c from z. The resulting points form a grid with x in the first dimension, y in the second, and z in the third.

The parameters x, y, and z are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars. In either case, either x, y, and z or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than three dimensions, ones are implicitly appended to its shape to make it 3-D. The shape of the result will be c.shape[3:] + x.shape + y.shape + z.shape.

Parameters:

x, y, z : array_like, compatible objects

The three dimensional series is evaluated at the points in the Cartesian product of x, y, and z. If x,`y`, or z is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and, if it isn’t an ndarray, it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree i,j are contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional polynomial at points in the Cartesian product of x and y.

See also

hermval, hermval2d, hermgrid2d, hermval3d

Notes


numpy.polynomial.hermite.hermroots

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermgrid3d

Next topic

numpy.polynomial.hermite.hermfromroots

numpy.polynomial.hermite.hermroots

numpy.polynomial.hermite.hermroots(c) [source]

Compute the roots of a Hermite series.

Return the roots (a.k.a. “zeros”) of the polynomial

Parameters:

c : 1-D array_like

1-D array of coefficients.
Returns:

out : ndarray

Array of the roots of the series. If all the roots are real, then out is also real, otherwise it is complex.

See also

polyroots, legroots, lagroots, chebroots, hermeroots

Notes

The root estimates are obtained as the eigenvalues of the companion matrix, Roots far from the origin of the complex plane may have large errors due to the numerical instability of the series for such values. Roots with multiplicity greater than 1 will also show larger errors as the value of the series near such points is relatively insensitive to errors in the roots. Isolated roots near the origin can be improved by a few iterations of Newton’s method.

The Hermite series basis polynomials aren’t powers of x so the results of this function may seem unintuitive.

Examples

>>> from numpy.polynomial.hermite import hermroots, hermfromroots
>>> coef = hermfromroots([-1, 0, 1])
>>> coef
array([ 0.   ,  0.25 ,  0.   ,  0.125])
>>> hermroots(coef)
array([ -1.00000000e+00,  -1.38777878e-17,   1.00000000e+00])


numpy.polynomial.hermite.hermfromroots

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermroots

Next topic

numpy.polynomial.hermite.hermfit

numpy.polynomial.hermite.hermfromroots

numpy.polynomial.hermite.hermfromroots(roots) [source]

Generate a Hermite series with given roots.

The function returns the coefficients of the polynomial

p(x) = (x - r_0) * (x - r_1) * ... * (x - r_n),

in Hermite form, where the r_n are the roots specified in roots. If a zero has multiplicity n, then it must appear in roots n times. For instance, if 2 is a root of multiplicity three and 3 is a root of multiplicity 2, then roots looks something like [2, 2, 2, 3, 3]. The roots can appear in any order.

If the returned coefficients are c, then

p(x) = c_0 + c_1 * H_1(x) + ... + c_n * H_n(x)

The coefficient of the last term is not generally 1 for monic polynomials in Hermite form.

Parameters:

roots : array_like

Sequence containing the roots.
Returns:

out : ndarray

1-D array of coefficients. If all roots are real then out is a real array, if some of the roots are complex, then out is complex even if all the coefficients in the result are real (see Examples below).

See also

polyfromroots, legfromroots, lagfromroots, chebfromroots, hermefromroots.

Examples

>>> from numpy.polynomial.hermite import hermfromroots, hermval
>>> coef = hermfromroots((-1, 0, 1))
>>> hermval((-1, 0, 1), coef)
array([ 0.,  0.,  0.])
>>> coef = hermfromroots((-1j, 1j))
>>> hermval((-1j, 1j), coef)
array([ 0.+0.j,  0.+0.j])


numpy.polynomial.hermite.hermfit

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermfromroots

Next topic

numpy.polynomial.hermite.hermvander

numpy.polynomial.hermite.hermfit

numpy.polynomial.hermite.hermfit(x, y, deg, rcond=None, full=False, w=None) [source]

Least squares fit of Hermite series to data.

Return the coefficients of a Hermite series of degree deg that is the least squares fit to the data values y given at points x. If y is 1-D the returned coefficients will also be 1-D. If y is 2-D multiple fits are done, one for each column of y, and the resulting coefficients are stored in the corresponding columns of a 2-D return. The fitted polynomial(s) are in the form

p(x) = c_0 + c_1 * H_1(x) + ... + c_n * H_n(x),

where n is deg.

Parameters:

x : array_like, shape (M,)

x-coordinates of the M sample points (x[i], y[i]).

y : array_like, shape (M,) or (M, K)

y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column.

deg : int

Degree of the fitting polynomial

rcond : float, optional

Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)*eps, where eps is the relative precision of the float type, about 2e-16 in most cases.

full : bool, optional

Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned.

w : array_like, shape (M,), optional

Weights. If not None, the contribution of each point (x[i],y[i]) to the fit is weighted by w[i]. Ideally the weights are chosen so that the errors of the products w[i]*y[i] all have the same variance. The default value is None.
Returns:

coef : ndarray, shape (M,) or (M, K)

Hermite coefficients ordered from low to high. If y was 2-D, the coefficients for the data in column k of y are in column k.

[residuals, rank, singular_values, rcond] : list

These values are only returned if full = True

resid – sum of squared residuals of the least squares fit rank – the numerical rank of the scaled Vandermonde matrix sv – singular values of the scaled Vandermonde matrix rcond – value of rcond.

For more details, see linalg.lstsq.
Warns:

RankWarning

The rank of the coefficient matrix in the least-squares fit is deficient. The warning is only raised if full = False. The warnings can be turned off by

>>> import warnings
>>> warnings.simplefilter('ignore', RankWarning)

See also

chebfit, legfit, lagfit, polyfit, hermefit

hermval
Evaluates a Hermite series.
hermvander
Vandermonde matrix of Hermite series.
hermweight
Hermite weight function
linalg.lstsq
Computes a least-squares fit from the matrix.
scipy.interpolate.UnivariateSpline
Computes spline fits.

Notes

The solution is the coefficients of the Hermite series p that minimizes the sum of the weighted squared errors

where the [image] are the weights. This problem is solved by setting up the (typically) overdetermined matrix equation

V(x) * c = w * y,

where V is the weighted pseudo Vandermonde matrix of x, c are the coefficients to be solved for, w are the weights, y are the observed values. This equation is then solved using the singular value decomposition of V.

If some of the singular values of V are so small that they are neglected, then a RankWarning will be issued. This means that the coefficient values may be poorly determined. Using a lower order fit will usually get rid of the warning. The rcond parameter can also be set to a value smaller than its default, but the resulting fit may be spurious and have large contributions from roundoff error.

Fits using Hermite series are probably most useful when the data can be approximated by sqrt(w(x)) * p(x), where w(x) is the Hermite weight. In that case the weight sqrt(w(x[i]) should be used together with data values y[i]/sqrt(w(x[i]). The weight function is available as hermweight.

References

[R61] Wikipedia, “Curve fitting”, http://en.wikipedia.org/wiki/Curve_fitting

Examples

>>> from numpy.polynomial.hermite import hermfit, hermval
>>> x = np.linspace(-10, 10)
>>> err = np.random.randn(len(x))/10
>>> y = hermval(x, [1, 2, 3]) + err
>>> hermfit(x, y, 2)
array([ 0.97902637,  1.99849131,  3.00006   ])


numpy.polynomial.hermite.hermvander

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermfit

Next topic

numpy.polynomial.hermite.hermvander2d

numpy.polynomial.hermite.hermvander

numpy.polynomial.hermite.hermvander(x, deg) [source]

Pseudo-Vandermonde matrix of given degree.

Returns the pseudo-Vandermonde matrix of degree deg and sample points x. The pseudo-Vandermonde matrix is defined by

V[..., i] = H_i(x),

where 0 <= i <= deg. The leading indices of V index the elements of x and the last index is the degree of the Hermite polynomial.

If c is a 1-D array of coefficients of length n + 1 and V is the array V = hermvander(x, n), then np.dot(V, c) and hermval(x, c) are the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of Hermite series of the same degree and sample points.

Parameters:

x : array_like

Array of points. The dtype is converted to float64 or complex128 depending on whether any of the elements are complex. If x is scalar it is converted to a 1-D array.

deg : int

Degree of the resulting matrix.
Returns:

vander : ndarray

The pseudo-Vandermonde matrix. The shape of the returned matrix is x.shape + (deg + 1,), where The last index is the degree of the corresponding Hermite polynomial. The dtype will be the same as the converted x.

Examples

>>> from numpy.polynomial.hermite import hermvander
>>> x = np.array([-1, 0, 1])
>>> hermvander(x, 3)
array([[ 1., -2.,  2.,  4.],
       [ 1.,  0., -2., -0.],
       [ 1.,  2.,  2., -4.]])


numpy.polynomial.hermite.hermvander2d

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermvander

Next topic

numpy.polynomial.hermite.hermvander3d

numpy.polynomial.hermite.hermvander2d

numpy.polynomial.hermite.hermvander2d(x, y, deg) [source]

Pseudo-Vandermonde matrix of given degrees.

Returns the pseudo-Vandermonde matrix of degrees deg and sample points (x, y). The pseudo-Vandermonde matrix is defined by

V[..., deg[1]*i + j] = H_i(x) * H_j(y),

where 0 <= i <= deg[0] and 0 <= j <= deg[1]. The leading indices of V index the points (x, y) and the last index encodes the degrees of the Hermite polynomials.

If V = hermvander2d(x, y, [xdeg, ydeg]), then the columns of V correspond to the elements of a 2-D coefficient array c of shape (xdeg + 1, ydeg + 1) in the order

c_{00}, c_{01}, c_{02} ... , c_{10}, c_{11}, c_{12} ...

and np.dot(V, c.flat) and hermval2d(x, y, c) will be the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of 2-D Hermite series of the same degrees and sample points.

Parameters:

x, y : array_like

Arrays of point coordinates, all of the same shape. The dtypes will be converted to either float64 or complex128 depending on whether any of the elements are complex. Scalars are converted to 1-D arrays.

deg : list of ints

List of maximum degrees of the form [x_deg, y_deg].
Returns:

vander2d : ndarray

The shape of the returned matrix is x.shape + (order,), where order = (deg[0]+1)*(deg([1]+1). The dtype will be the same as the converted x and y.

See also

hermvander, hermvander3d., hermval3d

Notes


numpy.polynomial.hermite.hermvander3d

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermvander2d

Next topic

numpy.polynomial.hermite.hermder

numpy.polynomial.hermite.hermvander3d

numpy.polynomial.hermite.hermvander3d(x, y, z, deg) [source]

Pseudo-Vandermonde matrix of given degrees.

Returns the pseudo-Vandermonde matrix of degrees deg and sample points (x, y, z). If l, m, n are the given degrees in x, y, z, then The pseudo-Vandermonde matrix is defined by

V[..., (m+1)(n+1)i + (n+1)j + k] = H_i(x)*H_j(y)*H_k(z),

where 0 <= i <= l, 0 <= j <= m, and 0 <= j <= n. The leading indices of V index the points (x, y, z) and the last index encodes the degrees of the Hermite polynomials.

If V = hermvander3d(x, y, z, [xdeg, ydeg, zdeg]), then the columns of V correspond to the elements of a 3-D coefficient array c of shape (xdeg + 1, ydeg + 1, zdeg + 1) in the order

c_{000}, c_{001}, c_{002},... , c_{010}, c_{011}, c_{012},...

and np.dot(V, c.flat) and hermval3d(x, y, z, c) will be the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of 3-D Hermite series of the same degrees and sample points.

Parameters:

x, y, z : array_like

Arrays of point coordinates, all of the same shape. The dtypes will be converted to either float64 or complex128 depending on whether any of the elements are complex. Scalars are converted to 1-D arrays.

deg : list of ints

List of maximum degrees of the form [x_deg, y_deg, z_deg].
Returns:

vander3d : ndarray

The shape of the returned matrix is x.shape + (order,), where order = (deg[0]+1)*(deg([1]+1)*(deg[2]+1). The dtype will be the same as the converted x, y, and z.

See also

hermvander, hermvander3d., hermval3d

Notes


numpy.polynomial.hermite.hermder

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermvander3d

Next topic

numpy.polynomial.hermite.hermint

numpy.polynomial.hermite.hermder

numpy.polynomial.hermite.hermder(c, m=1, scl=1, axis=0) [source]

Differentiate a Hermite series.

Returns the Hermite series coefficients c differentiated m times along axis. At each iteration the result is multiplied by scl (the scaling factor is for use in a linear change of variable). The argument c is an array of coefficients from low to high degree along each axis, e.g., [1,2,3] represents the series 1*H_0 + 2*H_1 + 3*H_2 while [[1,2],[1,2]] represents 1*H_0(x)*H_0(y) + 1*H_1(x)*H_0(y) + 2*H_0(x)*H_1(y) + 2*H_1(x)*H_1(y) if axis=0 is x and axis=1 is y.

Parameters:

c : array_like

Array of Hermite series coefficients. If c is multidimensional the different axis correspond to different variables with the degree in each axis given by the corresponding index.

m : int, optional

Number of derivatives taken, must be non-negative. (Default: 1)

scl : scalar, optional

Each differentiation is multiplied by scl. The end result is multiplication by scl**m. This is for use in a linear change of variable. (Default: 1)

axis : int, optional

Axis over which the derivative is taken. (Default: 0).

New in version 1.7.0.
Returns:

der : ndarray

Hermite series of the derivative.

See also

hermint

Notes

In general, the result of differentiating a Hermite series does not resemble the same operation on a power series. Thus the result of this function may be “unintuitive,” albeit correct; see Examples section below.

Examples

>>> from numpy.polynomial.hermite import hermder
>>> hermder([ 1. ,  0.5,  0.5,  0.5])
array([ 1.,  2.,  3.])
>>> hermder([-0.5,  1./2.,  1./8.,  1./12.,  1./16.], m=2)
array([ 1.,  2.,  3.])


numpy.polynomial.hermite.hermint

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermder

Next topic

numpy.polynomial.hermite.hermadd

numpy.polynomial.hermite.hermint

numpy.polynomial.hermite.hermint(c, m=1, k=[], lbnd=0, scl=1, axis=0) [source]

Integrate a Hermite series.

Returns the Hermite series coefficients c integrated m times from lbnd along axis. At each iteration the resulting series is multiplied by scl and an integration constant, k, is added. The scaling factor is for use in a linear change of variable. (“Buyer beware”: note that, depending on what one is doing, one may want scl to be the reciprocal of what one might expect; for more information, see the Notes section below.) The argument c is an array of coefficients from low to high degree along each axis, e.g., [1,2,3] represents the series H_0 + 2*H_1 + 3*H_2 while [[1,2],[1,2]] represents 1*H_0(x)*H_0(y) + 1*H_1(x)*H_0(y) + 2*H_0(x)*H_1(y) + 2*H_1(x)*H_1(y) if axis=0 is x and axis=1 is y.

Parameters:

c : array_like

Array of Hermite series coefficients. If c is multidimensional the different axis correspond to different variables with the degree in each axis given by the corresponding index.

m : int, optional

Order of integration, must be positive. (Default: 1)

k : {[], list, scalar}, optional

Integration constant(s). The value of the first integral at lbnd is the first value in the list, the value of the second integral at lbnd is the second value, etc. If k == [] (the default), all constants are set to zero. If m == 1, a single scalar can be given instead of a list.

lbnd : scalar, optional

The lower bound of the integral. (Default: 0)

scl : scalar, optional

Following each integration the result is multiplied by scl before the integration constant is added. (Default: 1)

axis : int, optional

Axis over which the integral is taken. (Default: 0).

New in version 1.7.0.
Returns:

S : ndarray

Hermite series coefficients of the integral.
Raises:

ValueError

If m < 0, len(k) > m, np.isscalar(lbnd) == False, or np.isscalar(scl) == False.

See also

hermder

Notes

Note that the result of each integration is multiplied by scl. Why is this important to note? Say one is making a linear change of variable u = ax + b in an integral relative to x. Then .. math::dx = du/a, so one will need to set scl equal to 1/a - perhaps not what one would have first thought.

Also note that, in general, the result of integrating a C-series needs to be “reprojected” onto the C-series basis set. Thus, typically, the result of this function is “unintuitive,” albeit correct; see Examples section below.

Examples

>>> from numpy.polynomial.hermite import hermint
>>> hermint([1,2,3]) # integrate once, value 0 at 0.
array([ 1. ,  0.5,  0.5,  0.5])
>>> hermint([1,2,3], m=2) # integrate twice, value & deriv 0 at 0
array([-0.5       ,  0.5       ,  0.125     ,  0.08333333,  0.0625    ])
>>> hermint([1,2,3], k=1) # integrate once, value 1 at 0.
array([ 2. ,  0.5,  0.5,  0.5])
>>> hermint([1,2,3], lbnd=-1) # integrate once, value 0 at -1
array([-2. ,  0.5,  0.5,  0.5])
>>> hermint([1,2,3], m=2, k=[1,2], lbnd=-1)
array([ 1.66666667, -0.5       ,  0.125     ,  0.08333333,  0.0625    ])


numpy.polynomial.hermite.hermadd

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermint

Next topic

numpy.polynomial.hermite.hermsub

numpy.polynomial.hermite.hermadd

numpy.polynomial.hermite.hermadd(c1, c2) [source]

Add one Hermite series to another.

Returns the sum of two Hermite series c1 + c2. The arguments are sequences of coefficients ordered from lowest order term to highest, i.e., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Hermite series coefficients ordered from low to high.
Returns:

out : ndarray

Array representing the Hermite series of their sum.

See also

hermsub, hermmul, hermdiv, hermpow

Notes

Unlike multiplication, division, etc., the sum of two Hermite series is a Hermite series (without having to “reproject” the result onto the basis set) so addition, just like that of “standard” polynomials, is simply “component-wise.”

Examples

>>> from numpy.polynomial.hermite import hermadd
>>> hermadd([1, 2, 3], [1, 2, 3, 4])
array([ 2.,  4.,  6.,  4.])


numpy.polynomial.hermite.hermsub

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermadd

Next topic

numpy.polynomial.hermite.hermmul

numpy.polynomial.hermite.hermsub

numpy.polynomial.hermite.hermsub(c1, c2) [source]

Subtract one Hermite series from another.

Returns the difference of two Hermite series c1 - c2. The sequences of coefficients are from lowest order term to highest, i.e., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Hermite series coefficients ordered from low to high.
Returns:

out : ndarray

Of Hermite series coefficients representing their difference.

See also

hermadd, hermmul, hermdiv, hermpow

Notes

Unlike multiplication, division, etc., the difference of two Hermite series is a Hermite series (without having to “reproject” the result onto the basis set) so subtraction, just like that of “standard” polynomials, is simply “component-wise.”

Examples

>>> from numpy.polynomial.hermite import hermsub
>>> hermsub([1, 2, 3, 4], [1, 2, 3])
array([ 0.,  0.,  0.,  4.])


numpy.polynomial.hermite.hermmul

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermsub

Next topic

numpy.polynomial.hermite.hermmulx

numpy.polynomial.hermite.hermmul

numpy.polynomial.hermite.hermmul(c1, c2) [source]

Multiply one Hermite series by another.

Returns the product of two Hermite series c1 * c2. The arguments are sequences of coefficients, from lowest order “term” to highest, e.g., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Hermite series coefficients ordered from low to high.
Returns:

out : ndarray

Of Hermite series coefficients representing their product.

See also

hermadd, hermsub, hermdiv, hermpow

Notes

In general, the (polynomial) product of two C-series results in terms that are not in the Hermite polynomial basis set. Thus, to express the product as a Hermite series, it is necessary to “reproject” the product onto said basis set, which may produce “unintuitive” (but correct) results; see Examples section below.

Examples

>>> from numpy.polynomial.hermite import hermmul
>>> hermmul([1, 2, 3], [0, 1, 2])
array([ 52.,  29.,  52.,   7.,   6.])


numpy.polynomial.hermite.hermmulx

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermmul

Next topic

numpy.polynomial.hermite.hermdiv

numpy.polynomial.hermite.hermmulx

numpy.polynomial.hermite.hermmulx(c) [source]

Multiply a Hermite series by x.

Multiply the Hermite series c by x, where x is the independent variable.

Parameters:

c : array_like

1-D array of Hermite series coefficients ordered from low to high.
Returns:

out : ndarray

Array representing the result of the multiplication.

Notes

The multiplication uses the recursion relationship for Hermite polynomials in the form

xP_i(x) = (P_{i + 1}(x)/2 + i*P_{i - 1}(x))

Examples

>>> from numpy.polynomial.hermite import hermmulx
>>> hermmulx([1, 2, 3])
array([ 2. ,  6.5,  1. ,  1.5])


numpy.polynomial.hermite.hermdiv

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermmulx

Next topic

numpy.polynomial.hermite.hermpow

numpy.polynomial.hermite.hermdiv

numpy.polynomial.hermite.hermdiv(c1, c2) [source]

Divide one Hermite series by another.

Returns the quotient-with-remainder of two Hermite series c1 / c2. The arguments are sequences of coefficients from lowest order “term” to highest, e.g., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Hermite series coefficients ordered from low to high.
Returns:

[quo, rem] : ndarrays

Of Hermite series coefficients representing the quotient and remainder.

See also

hermadd, hermsub, hermmul, hermpow

Notes

In general, the (polynomial) division of one Hermite series by another results in quotient and remainder terms that are not in the Hermite polynomial basis set. Thus, to express these results as a Hermite series, it is necessary to “reproject” the results onto the Hermite basis set, which may produce “unintuitive” (but correct) results; see Examples section below.

Examples

>>> from numpy.polynomial.hermite import hermdiv
>>> hermdiv([ 52.,  29.,  52.,   7.,   6.], [0, 1, 2])
(array([ 1.,  2.,  3.]), array([ 0.]))
>>> hermdiv([ 54.,  31.,  52.,   7.,   6.], [0, 1, 2])
(array([ 1.,  2.,  3.]), array([ 2.,  2.]))
>>> hermdiv([ 53.,  30.,  52.,   7.,   6.], [0, 1, 2])
(array([ 1.,  2.,  3.]), array([ 1.,  1.]))


numpy.polynomial.hermite.hermpow

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermdiv

Next topic

numpy.polynomial.hermite.hermgauss

numpy.polynomial.hermite.hermpow

numpy.polynomial.hermite.hermpow(c, pow, maxpower=16) [source]

Raise a Hermite series to a power.

Returns the Hermite series c raised to the power pow. The argument c is a sequence of coefficients ordered from low to high. i.e., [1,2,3] is the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c : array_like

1-D array of Hermite series coefficients ordered from low to high.

pow : integer

Power to which the series will be raised

maxpower : integer, optional

Maximum power allowed. This is mainly to limit growth of the series to unmanageable size. Default is 16
Returns:

coef : ndarray

Hermite series of power.

See also

hermadd, hermsub, hermmul, hermdiv

Examples

>>> from numpy.polynomial.hermite import hermpow
>>> hermpow([1, 2, 3], 2)
array([ 81.,  52.,  82.,  12.,   9.])


numpy.polynomial.hermite.hermgauss

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermpow

Next topic

numpy.polynomial.hermite.hermweight

numpy.polynomial.hermite.hermgauss

numpy.polynomial.hermite.hermgauss(deg) [source]

Gauss-Hermite quadrature.

Computes the sample points and weights for Gauss-Hermite quadrature. These sample points and weights will correctly integrate polynomials of degree 2*deg - 1 or less over the interval [image] with the weight function [image].

Parameters:

deg : int

Number of sample points and weights. It must be >= 1.
Returns:

x : ndarray

1-D ndarray containing the sample points.

y : ndarray

1-D ndarray containing the weights.

Notes

The results have only been tested up to degree 100, higher degrees may be problematic. The weights are determined by using the fact that

w_k = c / (H'_n(x_k) * H_{n-1}(x_k))

where c is a constant independent of k and [image] is the k’th root of [image], and then scaling the results to get the right value when integrating 1.


numpy.polynomial.hermite.hermweight

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermgauss

Next topic

numpy.polynomial.hermite.hermcompanion

numpy.polynomial.hermite.hermweight

numpy.polynomial.hermite.hermweight(x) [source]

Weight function of the Hermite polynomials.

The weight function is [image] and the interval of integration is [image]. the Hermite polynomials are orthogonal, but not normalized, with respect to this weight function.

Parameters:

x : array_like

Values at which the weight function will be computed.
Returns:

w : ndarray

The weight function at x.

Notes


numpy.polynomial.hermite.hermcompanion

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermweight

Next topic

numpy.polynomial.hermite.hermdomain

numpy.polynomial.hermite.hermcompanion

numpy.polynomial.hermite.hermcompanion(c) [source]

Return the scaled companion matrix of c.

The basis polynomials are scaled so that the companion matrix is symmetric when c is an Hermite basis polynomial. This provides better eigenvalue estimates than the unscaled case and for basis polynomials the eigenvalues are guaranteed to be real if numpy.linalg.eigvalsh is used to obtain them.

Parameters:

c : array_like

1-D array of Hermite series coefficients ordered from low to high degree.
Returns:

mat : ndarray

Scaled companion matrix of dimensions (deg, deg).

Notes


numpy.polynomial.hermite.hermdomain

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermcompanion

Next topic

numpy.polynomial.hermite.hermzero

numpy.polynomial.hermite.hermdomain

numpy.polynomial.hermite.hermdomain = array([-1, 1])


numpy.polynomial.hermite.hermzero

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermdomain

Next topic

numpy.polynomial.hermite.hermone

numpy.polynomial.hermite.hermzero

numpy.polynomial.hermite.hermzero = array([0])


numpy.polynomial.hermite.hermone

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermzero

Next topic

numpy.polynomial.hermite.hermx

numpy.polynomial.hermite.hermone

numpy.polynomial.hermite.hermone = array([1])


numpy.polynomial.hermite.hermx

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermone

Next topic

numpy.polynomial.hermite.hermtrim

numpy.polynomial.hermite.hermx

numpy.polynomial.hermite.hermx = array([ 0. , 0.5])


numpy.polynomial.hermite.hermtrim

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermx

Next topic

numpy.polynomial.hermite.hermline

numpy.polynomial.hermite.hermtrim

numpy.polynomial.hermite.hermtrim(c, tol=0) [source]

Remove “small” “trailing” coefficients from a polynomial.

“Small” means “small in absolute value” and is controlled by the parameter tol; “trailing” means highest order coefficient(s), e.g., in [0, 1, 1, 0, 0] (which represents 0 + x + x**2 + 0*x**3 + 0*x**4) both the 3-rd and 4-th order coefficients would be “trimmed.”

Parameters:

c : array_like

1-d array of coefficients, ordered from lowest order to highest.

tol : number, optional

Trailing (i.e., highest order) elements with absolute value less than or equal to tol (default value is zero) are removed.
Returns:

trimmed : ndarray

1-d array with trailing zeros removed. If the resulting series would be empty, a series containing a single zero is returned.
Raises:

ValueError

If tol < 0

See also

trimseq

Examples

>>> from numpy import polynomial as P
>>> P.trimcoef((0,0,3,0,5,0,0))
array([ 0.,  0.,  3.,  0.,  5.])
>>> P.trimcoef((0,0,1e-3,0,1e-5,0,0),1e-3) # item == tol is trimmed
array([ 0.])
>>> i = complex(0,1) # works for complex
>>> P.trimcoef((3e-4,1e-3*(1-i),5e-4,2e-5*(1+i)), 1e-3)
array([ 0.0003+0.j   ,  0.0010-0.001j])


numpy.polynomial.hermite.hermline

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermtrim

Next topic

numpy.polynomial.hermite.herm2poly

numpy.polynomial.hermite.hermline

numpy.polynomial.hermite.hermline(off, scl) [source]

Hermite series whose graph is a straight line.

Parameters:

off, scl : scalars

The specified line is given by off + scl*x.
Returns:

y : ndarray

This module’s representation of the Hermite series for off + scl*x.

See also

polyline, chebline

Examples

>>> from numpy.polynomial.hermite import hermline, hermval
>>> hermval(0,hermline(3, 2))
3.0
>>> hermval(1,hermline(3, 2))
5.0


numpy.polynomial.hermite.herm2poly

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.hermline

Next topic

numpy.polynomial.hermite.poly2herm

numpy.polynomial.hermite.herm2poly

numpy.polynomial.hermite.herm2poly(c) [source]

Convert a Hermite series to a polynomial.

Convert an array representing the coefficients of a Hermite series, ordered from lowest degree to highest, to an array of the coefficients of the equivalent polynomial (relative to the “standard” basis) ordered from lowest to highest degree.

Parameters:

c : array_like

1-D array containing the Hermite series coefficients, ordered from lowest order term to highest.
Returns:

pol : ndarray

1-D array containing the coefficients of the equivalent polynomial (relative to the “standard” basis) ordered from lowest order term to highest.

See also

poly2herm

Notes

The easy way to do conversions between polynomial basis sets is to use the convert method of a class instance.

Examples

>>> from numpy.polynomial.hermite import herm2poly
>>> herm2poly([ 1.   ,  2.75 ,  0.5  ,  0.375])
array([ 0.,  1.,  2.,  3.])


numpy.polynomial.hermite.poly2herm

  • Polynomials
  • Polynomial Package
  • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite.herm2poly

Next topic

HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)

numpy.polynomial.hermite.poly2herm

numpy.polynomial.hermite.poly2herm(pol) [source]

Convert a polynomial to a Hermite series.

Convert an array representing the coefficients of a polynomial (relative to the “standard” basis) ordered from lowest degree to highest, to an array of the coefficients of the equivalent Hermite series, ordered from lowest to highest degree.

Parameters:

pol : array_like

1-D array containing the polynomial coefficients
Returns:

c : ndarray

1-D array containing the coefficients of the equivalent Hermite series.

See also

herm2poly

Notes

The easy way to do conversions between polynomial basis sets is to use the convert method of a class instance.

Examples

>>> from numpy.polynomial.hermite import poly2herm
>>> poly2herm(np.arange(4))
array([ 1.   ,  2.75 ,  0.5  ,  0.375])


HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)

  • Polynomials
  • Polynomial Package
  • index
  • next
  • previous

Table Of Contents

  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
    • HermiteE Class
    • Basics
    • Fitting
    • Calculus
    • Algebra
    • Quadrature
    • Miscellaneous

Previous topic

numpy.polynomial.hermite.poly2herm

Next topic

numpy.polynomial.hermite_e.HermiteE

HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)

New in version 1.6.0.

This module provides a number of objects (mostly functions) useful for dealing with HermiteE series, including a HermiteE class that encapsulates the usual arithmetic operations. (General information on how this module represents and works with such polynomials is in the docstring for its “parent” sub-package, numpy.polynomial).

HermiteE Class

HermiteE(coef[, domain, window]) An HermiteE series class.

Basics

hermeval(x, c[, tensor]) | Evaluate an HermiteE series at points x.
hermeval2d(x, y, c) | Evaluate a 2-D HermiteE series at points (x, y).
hermeval3d(x, y, z, c) | Evaluate a 3-D Hermite_e series at points (x, y, z).
hermegrid2d(x, y, c) | Evaluate a 2-D HermiteE series on the Cartesian product of x and y.
hermegrid3d(x, y, z, c) | Evaluate a 3-D HermiteE series on the Cartesian product of x, y, and z.
hermeroots(c) | Compute the roots of a HermiteE series.
hermefromroots(roots) | Generate a HermiteE series with given roots.

Fitting

hermefit(x, y, deg[, rcond, full, w]) | Least squares fit of Hermite series to data.
hermevander(x, deg) | Pseudo-Vandermonde matrix of given degree.
hermevander2d(x, y, deg) | Pseudo-Vandermonde matrix of given degrees.
hermevander3d(x, y, z, deg) | Pseudo-Vandermonde matrix of given degrees.

Calculus

hermeder(c[, m, scl, axis]) | Differentiate a Hermite_e series.
hermeint(c[, m, k, lbnd, scl, axis]) | Integrate a Hermite_e series.

Algebra

hermeadd(c1, c2) | Add one Hermite series to another.
hermesub(c1, c2) | Subtract one Hermite series from another.
hermemul(c1, c2) | Multiply one Hermite series by another.
hermemulx(c) | Multiply a Hermite series by x.
hermediv(c1, c2) | Divide one Hermite series by another.
hermepow(c, pow[, maxpower]) | Raise a Hermite series to a power.

Quadrature

hermegauss(deg) | Gauss-HermiteE quadrature.
hermeweight(x) | Weight function of the Hermite_e polynomials.

Miscellaneous

hermecompanion(c) | Return the scaled companion matrix of c.
hermedomain |
hermezero |
hermeone |
hermex |
hermetrim(c[, tol]) | Remove “small” “trailing” coefficients from a polynomial.
hermeline(off, scl) | Hermite series whose graph is a straight line.
herme2poly(c) | Convert a Hermite series to a polynomial.
poly2herme(pol) | Convert a polynomial to a Hermite series.


numpy.polynomial.hermite_e.HermiteE

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.poly2herme

Next topic

numpy.polynomial.hermite_e.HermiteE.__call__

numpy.polynomial.hermite_e.HermiteE

class numpy.polynomial.hermite_e.HermiteE(coef, domain=None, window=None) [source]

An HermiteE series class.

The HermiteE class provides the standard Python numerical methods ‘+’, ‘-‘, ‘*’, ‘//’, ‘%’, ‘divmod’, ‘**’, and ‘()’ as well as the attributes and methods listed in the ABCPolyBase documentation.

Parameters:

coef : array_like

Laguerre coefficients in order of increasing degree, i.e, (1, 2, 3) gives 1*He_0(x) + 2*He_1(X) + 3*He_2(x).

domain : (2,) array_like, optional

Domain to use. The interval [domain[0], domain[1]] is mapped to the interval [window[0], window[1]] by shifting and scaling. The default value is [-1, 1].

window : (2,) array_like, optional

Window, see domain for its use. The default value is [-1, 1].

New in version 1.6.0.

Methods

__call__(arg)
basis(deg[, domain, window]) | Series basis polynomial of degree deg.
cast(series[, domain, window]) | Convert series to series of this class.
convert([domain, kind, window]) | Convert series to a different kind and/or domain and/or window.
copy() | Return a copy.
cutdeg(deg) | Truncate series to the given degree.
degree() | The degree of the series.
deriv([m]) | Differentiate.
fit(x, y, deg[, domain, rcond, full, w, window]) | Least squares fit to data.
fromroots(roots[, domain, window]) | Return series instance that has the specified roots.
has_samecoef(other) | Check if coefficients match.
has_samedomain(other) | Check if domains match.
has_sametype(other) | Check if types match.
has_samewindow(other) | Check if windows match.
identity([domain, window]) | Identity function.
integ([m, k, lbnd]) | Integrate.
linspace([n, domain]) | Return x, y values at equally spaced points in domain.
mapparms() | Return the mapping parameters.
roots() | Return the roots of the series polynomial.
trim([tol]) | Remove trailing coefficients
truncate(size) | Truncate series to length size.


numpy.polynomial.hermite_e.HermiteE.__call__

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE

Next topic

numpy.polynomial.hermite_e.HermiteE.basis

numpy.polynomial.hermite_e.HermiteE.__call__

HermiteE.__call__(arg) [source]


numpy.polynomial.hermite_e.HermiteE.basis

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.__call__

Next topic

numpy.polynomial.hermite_e.HermiteE.cast

numpy.polynomial.hermite_e.HermiteE.basis

classmethod HermiteE.basis(deg, domain=None, window=None) [source]

Series basis polynomial of degree deg.

Returns the series representing the basis polynomial of degree deg.

New in version 1.7.0.

Parameters:

deg : int

Degree of the basis polynomial for the series. Must be >= 0.

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

A series with the coefficient of the deg term set to one and all others zero.


numpy.polynomial.hermite_e.HermiteE.cast

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.basis

Next topic

numpy.polynomial.hermite_e.HermiteE.convert

numpy.polynomial.hermite_e.HermiteE.cast

classmethod HermiteE.cast(series, domain=None, window=None) [source]

Convert series to series of this class.

The series is expected to be an instance of some polynomial series of one of the types supported by by the numpy.polynomial module, but could be some other class that supports the convert method.

New in version 1.7.0.

Parameters:

series : series

The series instance to be converted.

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

A series of the same kind as the calling class and equal to series when evaluated.

See also

convert
similar instance method


numpy.polynomial.hermite_e.HermiteE.convert

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.cast

Next topic

numpy.polynomial.hermite_e.HermiteE.copy

numpy.polynomial.hermite_e.HermiteE.convert

HermiteE.convert(domain=None, kind=None, window=None) [source]

Convert series to a different kind and/or domain and/or window.

Parameters:

domain : array_like, optional

The domain of the converted series. If the value is None, the default domain of kind is used.

kind : class, optional

The polynomial series type class to which the current instance should be converted. If kind is None, then the class of the current instance is used.

window : array_like, optional

The window of the converted series. If the value is None, the default window of kind is used.
Returns:

new_series : series

The returned class can be of different type than the current instance and/or have a different domain and/or different window.

Notes

Conversion between domains and class types can result in numerically ill defined series.


numpy.polynomial.hermite_e.HermiteE.copy

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.convert

Next topic

numpy.polynomial.hermite_e.HermiteE.cutdeg

numpy.polynomial.hermite_e.HermiteE.copy

HermiteE.copy() [source]

Return a copy.

Returns:

new_series : series

Copy of self.


numpy.polynomial.hermite_e.HermiteE.cutdeg

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.copy

Next topic

numpy.polynomial.hermite_e.HermiteE.degree

numpy.polynomial.hermite_e.HermiteE.cutdeg

HermiteE.cutdeg(deg) [source]

Truncate series to the given degree.

Reduce the degree of the series to deg by discarding the high order terms. If deg is greater than the current degree a copy of the current series is returned. This can be useful in least squares where the coefficients of the high degree terms may be very small.

New in version 1.5.0.

Parameters:

deg : non-negative int

The series is reduced to degree deg by discarding the high order terms. The value of deg must be a non-negative integer.
Returns:

new_series : series

New instance of series with reduced degree.


numpy.polynomial.hermite_e.HermiteE.degree

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.cutdeg

Next topic

numpy.polynomial.hermite_e.HermiteE.deriv

numpy.polynomial.hermite_e.HermiteE.degree

HermiteE.degree() [source]

The degree of the series.

New in version 1.5.0.

Returns:

degree : int

Degree of the series, one less than the number of coefficients.


numpy.polynomial.hermite_e.HermiteE.deriv

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.degree

Next topic

numpy.polynomial.hermite_e.HermiteE.fit

numpy.polynomial.hermite_e.HermiteE.deriv

HermiteE.deriv(m=1) [source]

Differentiate.

Return a series instance of that is the derivative of the current series.

Parameters:

m : non-negative int

The number of integrations to perform.
Returns:

new_series : series

A new series representing the derivative. The domain is the same as the domain of the differentiated series.


numpy.polynomial.hermite_e.HermiteE.fit

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.deriv

Next topic

numpy.polynomial.hermite_e.HermiteE.fromroots

numpy.polynomial.hermite_e.HermiteE.fit

classmethod HermiteE.fit(x, y, deg, domain=None, rcond=None, full=False, w=None, window=None) [source]

Least squares fit to data.

Return a series instance that is the least squares fit to the data y sampled at x. The domain of the returned instance can be specified and this will often result in a superior fit with less chance of ill conditioning.

Parameters:

x : array_like, shape (M,)

x-coordinates of the M sample points (x[i], y[i]).

y : array_like, shape (M,) or (M, K)

y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column.

deg : int

Degree of the fitting polynomial.

domain : {None, [beg, end], []}, optional

Domain to use for the returned series. If None, then a minimal domain that covers the points x is chosen. If [] the class domain is used. The default value was the class domain in NumPy 1.4 and None in later versions. The [] option was added in numpy 1.5.0.

rcond : float, optional

Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)*eps, where eps is the relative precision of the float type, about 2e-16 in most cases.

full : bool, optional

Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned.

w : array_like, shape (M,), optional

Weights. If not None the contribution of each point (x[i],y[i]) to the fit is weighted by w[i]. Ideally the weights are chosen so that the errors of the products w[i]*y[i] all have the same variance. The default value is None.

New in version 1.5.0.

window : {[beg, end]}, optional

Window to use for the returned series. The default value is the default class domain

New in version 1.6.0.
Returns:

new_series : series

A series that represents the least squares fit to the data and has the domain specified in the call.

[resid, rank, sv, rcond] : list

These values are only returned if full = True

resid – sum of squared residuals of the least squares fit rank – the numerical rank of the scaled Vandermonde matrix sv – singular values of the scaled Vandermonde matrix rcond – value of rcond.

For more details, see linalg.lstsq.


numpy.polynomial.hermite_e.HermiteE.fromroots

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.fit

Next topic

numpy.polynomial.hermite_e.HermiteE.has_samecoef

numpy.polynomial.hermite_e.HermiteE.fromroots

classmethod HermiteE.fromroots(roots, domain=[], window=None) [source]

Return series instance that has the specified roots.

Returns a series representing the product (x - r[0])*(x - r[1])*...*(x - r[n-1]), where r is a list of roots.

Parameters:

roots : array_like

List of roots.

domain : {[], None, array_like}, optional

Domain for the resulting series. If None the domain is the interval from the smallest root to the largest. If [] the domain is the class domain. The default is [].

window : {None, array_like}, optional

Window for the returned series. If None the class window is used. The default is None.
Returns:

new_series : series

Series with the specified roots.


numpy.polynomial.hermite_e.HermiteE.has_samecoef

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.fromroots

Next topic

numpy.polynomial.hermite_e.HermiteE.has_samedomain

numpy.polynomial.hermite_e.HermiteE.has_samecoef

HermiteE.has_samecoef(other) [source]

Check if coefficients match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the coef attribute.
Returns:

bool : boolean

True if the coefficients are the same, False otherwise.


numpy.polynomial.hermite_e.HermiteE.has_samedomain

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.has_samecoef

Next topic

numpy.polynomial.hermite_e.HermiteE.has_sametype

numpy.polynomial.hermite_e.HermiteE.has_samedomain

HermiteE.has_samedomain(other) [source]

Check if domains match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the domain attribute.
Returns:

bool : boolean

True if the domains are the same, False otherwise.


numpy.polynomial.hermite_e.HermiteE.has_sametype

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.has_samedomain

Next topic

numpy.polynomial.hermite_e.HermiteE.has_samewindow

numpy.polynomial.hermite_e.HermiteE.has_sametype

HermiteE.has_sametype(other) [source]

Check if types match.

New in version 1.7.0.

Parameters:

other : object

Class instance.
Returns:

bool : boolean

True if other is same class as self


numpy.polynomial.hermite_e.HermiteE.has_samewindow

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.has_sametype

Next topic

numpy.polynomial.hermite_e.HermiteE.identity

numpy.polynomial.hermite_e.HermiteE.has_samewindow

HermiteE.has_samewindow(other) [source]

Check if windows match.

New in version 1.6.0.

Parameters:

other : class instance

The other class must have the window attribute.
Returns:

bool : boolean

True if the windows are the same, False otherwise.


numpy.polynomial.hermite_e.HermiteE.identity

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.has_samewindow

Next topic

numpy.polynomial.hermite_e.HermiteE.integ

numpy.polynomial.hermite_e.HermiteE.identity

classmethod HermiteE.identity(domain=None, window=None) [source]

Identity function.

If p is the returned series, then p(x) == x for all values of x.

Parameters:

domain : {None, array_like}, optional

If given, the array must be of the form [beg, end], where beg and end are the endpoints of the domain. If None is given then the class domain is used. The default is None.

window : {None, array_like}, optional

If given, the resulting array must be if the form [beg, end], where beg and end are the endpoints of the window. If None is given then the class window is used. The default is None.
Returns:

new_series : series

Series of representing the identity.


numpy.polynomial.hermite_e.HermiteE.integ

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.identity

Next topic

numpy.polynomial.hermite_e.HermiteE.linspace

numpy.polynomial.hermite_e.HermiteE.integ

HermiteE.integ(m=1, k=[], lbnd=None) [source]

Integrate.

Return a series instance that is the definite integral of the current series.

Parameters:

m : non-negative int

The number of integrations to perform.

k : array_like

Integration constants. The first constant is applied to the first integration, the second to the second, and so on. The list of values must less than or equal to m in length and any missing values are set to zero.

lbnd : Scalar

The lower bound of the definite integral.
Returns:

new_series : series

A new series representing the integral. The domain is the same as the domain of the integrated series.


numpy.polynomial.hermite_e.HermiteE.linspace

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.integ

Next topic

numpy.polynomial.hermite_e.HermiteE.mapparms

numpy.polynomial.hermite_e.HermiteE.linspace

HermiteE.linspace(n=100, domain=None) [source]

Return x, y values at equally spaced points in domain.

Returns the x, y values at n linearly spaced points across the domain. Here y is the value of the polynomial at the points x. By default the domain is the same as that of the series instance. This method is intended mostly as a plotting aid.

New in version 1.5.0.

Parameters:

n : int, optional

Number of point pairs to return. The default value is 100.

domain : {None, array_like}, optional

If not None, the specified domain is used instead of that of the calling instance. It should be of the form [beg,end]. The default is None which case the class domain is used.
Returns:

x, y : ndarray

x is equal to linspace(self.domain[0], self.domain[1], n) and y is the series evaluated at element of x.


numpy.polynomial.hermite_e.HermiteE.mapparms

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.linspace

Next topic

numpy.polynomial.hermite_e.HermiteE.roots

numpy.polynomial.hermite_e.HermiteE.mapparms

HermiteE.mapparms() [source]

Return the mapping parameters.

The returned values define a linear map off + scl*x that is applied to the input arguments before the series is evaluated. The map depends on the domain and window; if the current domain is equal to the window the resulting map is the identity. If the coefficients of the series instance are to be used by themselves outside this class, then the linear function must be substituted for the x in the standard representation of the base polynomials.

Returns:

off, scl : float or complex

The mapping function is defined by off + scl*x.

Notes

If the current domain is the interval [l1, r1] and the window is [l2, r2], then the linear mapping function L is defined by the equations:

L(l1) = l2
L(r1) = r2


numpy.polynomial.hermite_e.HermiteE.roots

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.mapparms

Next topic

numpy.polynomial.hermite_e.HermiteE.trim

numpy.polynomial.hermite_e.HermiteE.roots

HermiteE.roots() [source]

Return the roots of the series polynomial.

Compute the roots for the series. Note that the accuracy of the roots decrease the further outside the domain they lie.

Returns:

roots : ndarray

Array containing the roots of the series.


numpy.polynomial.hermite_e.HermiteE.trim

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.roots

Next topic

numpy.polynomial.hermite_e.HermiteE.truncate

numpy.polynomial.hermite_e.HermiteE.trim

HermiteE.trim(tol=0) [source]

Remove trailing coefficients

Remove trailing coefficients until a coefficient is reached whose absolute value greater than tol or the beginning of the series is reached. If all the coefficients would be removed the series is set to [0]. A new series instance is returned with the new coefficients. The current instance remains unchanged.

Parameters:

tol : non-negative number.

All trailing coefficients less than tol will be removed.
Returns:

new_series : series

Contains the new set of coefficients.


numpy.polynomial.hermite_e.HermiteE.truncate

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • numpy.polynomial.hermite_e.HermiteE
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.trim

Next topic

numpy.polynomial.hermite_e.hermeval

numpy.polynomial.hermite_e.HermiteE.truncate

HermiteE.truncate(size) [source]

Truncate series to length size.

Reduce the series to length size by discarding the high degree terms. The value of size must be a positive integer. This can be useful in least squares where the coefficients of the high degree terms may be very small.

Parameters:

size : positive int

The series is reduced to length size by discarding the high degree terms. The value of size must be a positive integer.
Returns:

new_series : series

New instance of series with truncated coefficients.


numpy.polynomial.hermite_e.hermeval

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.HermiteE.truncate

Next topic

numpy.polynomial.hermite_e.hermeval2d

numpy.polynomial.hermite_e.hermeval

numpy.polynomial.hermite_e.hermeval(x, c, tensor=True) [source]

Evaluate an HermiteE series at points x.

If c is of length n + 1, this function returns the value:

p(x) = c_0 * He_0(x) + c_1 * He_1(x) + ... + c_n * He_n(x)

The parameter x is converted to an array only if it is a tuple or a list, otherwise it is treated as a scalar. In either case, either x or its elements must support multiplication and addition both with themselves and with the elements of c.

If c is a 1-D array, then p(x) will have the same shape as x. If c is multidimensional, then the shape of the result depends on the value of tensor. If tensor is true the shape will be c.shape[1:] + x.shape. If tensor is false the shape will be c.shape[1:]. Note that scalars have shape (,).

Trailing zeros in the coefficients will be used in the evaluation, so they should be avoided if efficiency is a concern.

Parameters:

x : array_like, compatible object

If x is a list or tuple, it is converted to an ndarray, otherwise it is left unchanged and treated as a scalar. In either case, x or its elements must support addition and multiplication with with themselves and with the elements of c.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree n are contained in c[n]. If c is multidimensional the remaining indices enumerate multiple polynomials. In the two dimensional case the coefficients may be thought of as stored in the columns of c.

tensor : boolean, optional

If True, the shape of the coefficient array is extended with ones on the right, one for each dimension of x. Scalars have dimension 0 for this action. The result is that every column of coefficients in c is evaluated for every element of x. If False, x is broadcast over the columns of c for the evaluation. This keyword is useful when c is multidimensional. The default value is True.

New in version 1.7.0.
Returns:

values : ndarray, algebra_like

The shape of the return value is described above.

See also

hermeval2d, hermegrid2d, hermeval3d, hermegrid3d

Notes

The evaluation uses Clenshaw recursion, aka synthetic division.

Examples

>>> from numpy.polynomial.hermite_e import hermeval
>>> coef = [1,2,3]
>>> hermeval(1, coef)
3.0
>>> hermeval([[1,2],[3,4]], coef)
array([[  3.,  14.],
       [ 31.,  54.]])


numpy.polynomial.hermite_e.hermeval2d

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermeval

Next topic

numpy.polynomial.hermite_e.hermeval3d

numpy.polynomial.hermite_e.hermeval2d

numpy.polynomial.hermite_e.hermeval2d(x, y, c) [source]

Evaluate a 2-D HermiteE series at points (x, y).

This function returns the values:

The parameters x and y are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars and they must have the same shape after conversion. In either case, either x and y or their elements must support multiplication and addition both with themselves and with the elements of c.

If c is a 1-D array a one is implicitly appended to its shape to make it 2-D. The shape of the result will be c.shape[2:] + x.shape.

Parameters:

x, y : array_like, compatible objects

The two dimensional series is evaluated at the points (x, y), where x and y must have the same shape. If x or y is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and if it isn’t an ndarray it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j is contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional polynomial at points formed with pairs of corresponding values from x and y.

See also

hermeval, hermegrid2d, hermeval3d, hermegrid3d

Notes


numpy.polynomial.hermite_e.hermeval3d

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermeval2d

Next topic

numpy.polynomial.hermite_e.hermegrid2d

numpy.polynomial.hermite_e.hermeval3d

numpy.polynomial.hermite_e.hermeval3d(x, y, z, c) [source]

Evaluate a 3-D Hermite_e series at points (x, y, z).

This function returns the values:

The parameters x, y, and z are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars and they must have the same shape after conversion. In either case, either x, y, and z or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than 3 dimensions, ones are implicitly appended to its shape to make it 3-D. The shape of the result will be c.shape[3:] + x.shape.

Parameters:

x, y, z : array_like, compatible object

The three dimensional series is evaluated at the points (x, y, z), where x, y, and z must have the same shape. If any of x, y, or z is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and if it isn’t an ndarray it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficient of the term of multi-degree i,j,k is contained in c[i,j,k]. If c has dimension greater than 3 the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the multidimensional polynomial on points formed with triples of corresponding values from x, y, and z.

See also

hermeval, hermeval2d, hermegrid2d, hermegrid3d

Notes


numpy.polynomial.hermite_e.hermegrid2d

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermeval3d

Next topic

numpy.polynomial.hermite_e.hermegrid3d

numpy.polynomial.hermite_e.hermegrid2d

numpy.polynomial.hermite_e.hermegrid2d(x, y, c) [source]

Evaluate a 2-D HermiteE series on the Cartesian product of x and y.

This function returns the values:

where the points (a, b) consist of all pairs formed by taking a from x and b from y. The resulting points form a grid with x in the first dimension and y in the second.

The parameters x and y are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars. In either case, either x and y or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than two dimensions, ones are implicitly appended to its shape to make it 2-D. The shape of the result will be c.shape[2:] + x.shape.

Parameters:

x, y : array_like, compatible objects

The two dimensional series is evaluated at the points in the Cartesian product of x and y. If x or y is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and, if it isn’t an ndarray, it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree i,j are contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional polynomial at points in the Cartesian product of x and y.

See also

hermeval, hermeval2d, hermeval3d, hermegrid3d

Notes


numpy.polynomial.hermite_e.hermegrid3d

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermegrid2d

Next topic

numpy.polynomial.hermite_e.hermeroots

numpy.polynomial.hermite_e.hermegrid3d

numpy.polynomial.hermite_e.hermegrid3d(x, y, z, c) [source]

Evaluate a 3-D HermiteE series on the Cartesian product of x, y, and z.

This function returns the values:

where the points (a, b, c) consist of all triples formed by taking a from x, b from y, and c from z. The resulting points form a grid with x in the first dimension, y in the second, and z in the third.

The parameters x, y, and z are converted to arrays only if they are tuples or a lists, otherwise they are treated as a scalars. In either case, either x, y, and z or their elements must support multiplication and addition both with themselves and with the elements of c.

If c has fewer than three dimensions, ones are implicitly appended to its shape to make it 3-D. The shape of the result will be c.shape[3:] + x.shape + y.shape + z.shape.

Parameters:

x, y, z : array_like, compatible objects

The three dimensional series is evaluated at the points in the Cartesian product of x, y, and z. If x,`y`, or z is a list or tuple, it is first converted to an ndarray, otherwise it is left unchanged and, if it isn’t an ndarray, it is treated as a scalar.

c : array_like

Array of coefficients ordered so that the coefficients for terms of degree i,j are contained in c[i,j]. If c has dimension greater than two the remaining indices enumerate multiple sets of coefficients.
Returns:

values : ndarray, compatible object

The values of the two dimensional polynomial at points in the Cartesian product of x and y.

See also

hermeval, hermeval2d, hermegrid2d, hermeval3d

Notes


numpy.polynomial.hermite_e.hermeroots

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermegrid3d

Next topic

numpy.polynomial.hermite_e.hermefromroots

numpy.polynomial.hermite_e.hermeroots

numpy.polynomial.hermite_e.hermeroots(c) [source]

Compute the roots of a HermiteE series.

Return the roots (a.k.a. “zeros”) of the polynomial

Parameters:

c : 1-D array_like

1-D array of coefficients.
Returns:

out : ndarray

Array of the roots of the series. If all the roots are real, then out is also real, otherwise it is complex.

See also

polyroots, legroots, lagroots, hermroots, chebroots

Notes

The root estimates are obtained as the eigenvalues of the companion matrix, Roots far from the origin of the complex plane may have large errors due to the numerical instability of the series for such values. Roots with multiplicity greater than 1 will also show larger errors as the value of the series near such points is relatively insensitive to errors in the roots. Isolated roots near the origin can be improved by a few iterations of Newton’s method.

The HermiteE series basis polynomials aren’t powers of x so the results of this function may seem unintuitive.

Examples

>>> from numpy.polynomial.hermite_e import hermeroots, hermefromroots
>>> coef = hermefromroots([-1, 0, 1])
>>> coef
array([ 0.,  2.,  0.,  1.])
>>> hermeroots(coef)
array([-1.,  0.,  1.])


numpy.polynomial.hermite_e.hermefromroots

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermeroots

Next topic

numpy.polynomial.hermite_e.hermefit

numpy.polynomial.hermite_e.hermefromroots

numpy.polynomial.hermite_e.hermefromroots(roots) [source]

Generate a HermiteE series with given roots.

The function returns the coefficients of the polynomial

p(x) = (x - r_0) * (x - r_1) * ... * (x - r_n),

in HermiteE form, where the r_n are the roots specified in roots. If a zero has multiplicity n, then it must appear in roots n times. For instance, if 2 is a root of multiplicity three and 3 is a root of multiplicity 2, then roots looks something like [2, 2, 2, 3, 3]. The roots can appear in any order.

If the returned coefficients are c, then

p(x) = c_0 + c_1 * He_1(x) + ... + c_n * He_n(x)

The coefficient of the last term is not generally 1 for monic polynomials in HermiteE form.

Parameters:

roots : array_like

Sequence containing the roots.
Returns:

out : ndarray

1-D array of coefficients. If all roots are real then out is a real array, if some of the roots are complex, then out is complex even if all the coefficients in the result are real (see Examples below).

See also

polyfromroots, legfromroots, lagfromroots, hermfromroots, chebfromroots.

Examples

>>> from numpy.polynomial.hermite_e import hermefromroots, hermeval
>>> coef = hermefromroots((-1, 0, 1))
>>> hermeval((-1, 0, 1), coef)
array([ 0.,  0.,  0.])
>>> coef = hermefromroots((-1j, 1j))
>>> hermeval((-1j, 1j), coef)
array([ 0.+0.j,  0.+0.j])


numpy.polynomial.hermite_e.hermefit

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermefromroots

Next topic

numpy.polynomial.hermite_e.hermevander

numpy.polynomial.hermite_e.hermefit

numpy.polynomial.hermite_e.hermefit(x, y, deg, rcond=None, full=False, w=None) [source]

Least squares fit of Hermite series to data.

Return the coefficients of a HermiteE series of degree deg that is the least squares fit to the data values y given at points x. If y is 1-D the returned coefficients will also be 1-D. If y is 2-D multiple fits are done, one for each column of y, and the resulting coefficients are stored in the corresponding columns of a 2-D return. The fitted polynomial(s) are in the form

p(x) = c_0 + c_1 * He_1(x) + ... + c_n * He_n(x),

where n is deg.

Parameters:

x : array_like, shape (M,)

x-coordinates of the M sample points (x[i], y[i]).

y : array_like, shape (M,) or (M, K)

y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column.

deg : int

Degree of the fitting polynomial

rcond : float, optional

Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)*eps, where eps is the relative precision of the float type, about 2e-16 in most cases.

full : bool, optional

Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned.

w : array_like, shape (M,), optional

Weights. If not None, the contribution of each point (x[i],y[i]) to the fit is weighted by w[i]. Ideally the weights are chosen so that the errors of the products w[i]*y[i] all have the same variance. The default value is None.
Returns:

coef : ndarray, shape (M,) or (M, K)

Hermite coefficients ordered from low to high. If y was 2-D, the coefficients for the data in column k of y are in column k.

[residuals, rank, singular_values, rcond] : list

These values are only returned if full = True

resid – sum of squared residuals of the least squares fit rank – the numerical rank of the scaled Vandermonde matrix sv – singular values of the scaled Vandermonde matrix rcond – value of rcond.

For more details, see linalg.lstsq.
Warns:

RankWarning

The rank of the coefficient matrix in the least-squares fit is deficient. The warning is only raised if full = False. The warnings can be turned off by

>>> import warnings
>>> warnings.simplefilter('ignore', RankWarning)

See also

chebfit, legfit, polyfit, hermfit, polyfit

hermeval
Evaluates a Hermite series.
hermevander
pseudo Vandermonde matrix of Hermite series.
hermeweight
HermiteE weight function.
linalg.lstsq
Computes a least-squares fit from the matrix.
scipy.interpolate.UnivariateSpline
Computes spline fits.

Notes

The solution is the coefficients of the HermiteE series p that minimizes the sum of the weighted squared errors

where the [image] are the weights. This problem is solved by setting up the (typically) overdetermined matrix equation

V(x) * c = w * y,

where V is the pseudo Vandermonde matrix of x, the elements of c are the coefficients to be solved for, and the elements of y are the observed values. This equation is then solved using the singular value decomposition of V.

If some of the singular values of V are so small that they are neglected, then a RankWarning will be issued. This means that the coefficient values may be poorly determined. Using a lower order fit will usually get rid of the warning. The rcond parameter can also be set to a value smaller than its default, but the resulting fit may be spurious and have large contributions from roundoff error.

Fits using HermiteE series are probably most useful when the data can be approximated by sqrt(w(x)) * p(x), where w(x) is the HermiteE weight. In that case the weight sqrt(w(x[i]) should be used together with data values y[i]/sqrt(w(x[i]). The weight function is available as hermeweight.

References

[R62] Wikipedia, “Curve fitting”, http://en.wikipedia.org/wiki/Curve_fitting

Examples

>>> from numpy.polynomial.hermite_e import hermefik, hermeval
>>> x = np.linspace(-10, 10)
>>> err = np.random.randn(len(x))/10
>>> y = hermeval(x, [1, 2, 3]) + err
>>> hermefit(x, y, 2)
array([ 1.01690445,  1.99951418,  2.99948696])


numpy.polynomial.hermite_e.hermevander

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermefit

Next topic

numpy.polynomial.hermite_e.hermevander2d

numpy.polynomial.hermite_e.hermevander

numpy.polynomial.hermite_e.hermevander(x, deg) [source]

Pseudo-Vandermonde matrix of given degree.

Returns the pseudo-Vandermonde matrix of degree deg and sample points x. The pseudo-Vandermonde matrix is defined by

V[..., i] = He_i(x),

where 0 <= i <= deg. The leading indices of V index the elements of x and the last index is the degree of the HermiteE polynomial.

If c is a 1-D array of coefficients of length n + 1 and V is the array V = hermevander(x, n), then np.dot(V, c) and hermeval(x, c) are the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of HermiteE series of the same degree and sample points.

Parameters:

x : array_like

Array of points. The dtype is converted to float64 or complex128 depending on whether any of the elements are complex. If x is scalar it is converted to a 1-D array.

deg : int

Degree of the resulting matrix.
Returns:

vander : ndarray

The pseudo-Vandermonde matrix. The shape of the returned matrix is x.shape + (deg + 1,), where The last index is the degree of the corresponding HermiteE polynomial. The dtype will be the same as the converted x.

Examples

>>> from numpy.polynomial.hermite_e import hermevander
>>> x = np.array([-1, 0, 1])
>>> hermevander(x, 3)
array([[ 1., -1.,  0.,  2.],
       [ 1.,  0., -1., -0.],
       [ 1.,  1.,  0., -2.]])


numpy.polynomial.hermite_e.hermevander2d

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermevander

Next topic

numpy.polynomial.hermite_e.hermevander3d

numpy.polynomial.hermite_e.hermevander2d

numpy.polynomial.hermite_e.hermevander2d(x, y, deg) [source]

Pseudo-Vandermonde matrix of given degrees.

Returns the pseudo-Vandermonde matrix of degrees deg and sample points (x, y). The pseudo-Vandermonde matrix is defined by

V[..., deg[1]*i + j] = He_i(x) * He_j(y),

where 0 <= i <= deg[0] and 0 <= j <= deg[1]. The leading indices of V index the points (x, y) and the last index encodes the degrees of the HermiteE polynomials.

If V = hermevander2d(x, y, [xdeg, ydeg]), then the columns of V correspond to the elements of a 2-D coefficient array c of shape (xdeg + 1, ydeg + 1) in the order

c_{00}, c_{01}, c_{02} ... , c_{10}, c_{11}, c_{12} ...

and np.dot(V, c.flat) and hermeval2d(x, y, c) will be the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of 2-D HermiteE series of the same degrees and sample points.

Parameters:

x, y : array_like

Arrays of point coordinates, all of the same shape. The dtypes will be converted to either float64 or complex128 depending on whether any of the elements are complex. Scalars are converted to 1-D arrays.

deg : list of ints

List of maximum degrees of the form [x_deg, y_deg].
Returns:

vander2d : ndarray

The shape of the returned matrix is x.shape + (order,), where order = (deg[0]+1)*(deg([1]+1). The dtype will be the same as the converted x and y.

See also

hermevander, hermevander3d., hermeval3d

Notes


numpy.polynomial.hermite_e.hermevander3d

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermevander2d

Next topic

numpy.polynomial.hermite_e.hermeder

numpy.polynomial.hermite_e.hermevander3d

numpy.polynomial.hermite_e.hermevander3d(x, y, z, deg) [source]

Pseudo-Vandermonde matrix of given degrees.

Returns the pseudo-Vandermonde matrix of degrees deg and sample points (x, y, z). If l, m, n are the given degrees in x, y, z, then Hehe pseudo-Vandermonde matrix is defined by

V[..., (m+1)(n+1)i + (n+1)j + k] = He_i(x)*He_j(y)*He_k(z),

where 0 <= i <= l, 0 <= j <= m, and 0 <= j <= n. The leading indices of V index the points (x, y, z) and the last index encodes the degrees of the HermiteE polynomials.

If V = hermevander3d(x, y, z, [xdeg, ydeg, zdeg]), then the columns of V correspond to the elements of a 3-D coefficient array c of shape (xdeg + 1, ydeg + 1, zdeg + 1) in the order

c_{000}, c_{001}, c_{002},... , c_{010}, c_{011}, c_{012},...

and np.dot(V, c.flat) and hermeval3d(x, y, z, c) will be the same up to roundoff. This equivalence is useful both for least squares fitting and for the evaluation of a large number of 3-D HermiteE series of the same degrees and sample points.

Parameters:

x, y, z : array_like

Arrays of point coordinates, all of the same shape. The dtypes will be converted to either float64 or complex128 depending on whether any of the elements are complex. Scalars are converted to 1-D arrays.

deg : list of ints

List of maximum degrees of the form [x_deg, y_deg, z_deg].
Returns:

vander3d : ndarray

The shape of the returned matrix is x.shape + (order,), where order = (deg[0]+1)*(deg([1]+1)*(deg[2]+1). The dtype will be the same as the converted x, y, and z.

See also

hermevander, hermevander3d., hermeval3d

Notes


numpy.polynomial.hermite_e.hermeder

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermevander3d

Next topic

numpy.polynomial.hermite_e.hermeint

numpy.polynomial.hermite_e.hermeder

numpy.polynomial.hermite_e.hermeder(c, m=1, scl=1, axis=0) [source]

Differentiate a Hermite_e series.

Returns the series coefficients c differentiated m times along axis. At each iteration the result is multiplied by scl (the scaling factor is for use in a linear change of variable). The argument c is an array of coefficients from low to high degree along each axis, e.g., [1,2,3] represents the series 1*He_0 + 2*He_1 + 3*He_2 while [[1,2],[1,2]] represents 1*He_0(x)*He_0(y) + 1*He_1(x)*He_0(y) + 2*He_0(x)*He_1(y) + 2*He_1(x)*He_1(y) if axis=0 is x and axis=1 is y.

Parameters:

c : array_like

Array of Hermite_e series coefficients. If c is multidimensional the different axis correspond to different variables with the degree in each axis given by the corresponding index.

m : int, optional

Number of derivatives taken, must be non-negative. (Default: 1)

scl : scalar, optional

Each differentiation is multiplied by scl. The end result is multiplication by scl**m. This is for use in a linear change of variable. (Default: 1)

axis : int, optional

Axis over which the derivative is taken. (Default: 0).

New in version 1.7.0.
Returns:

der : ndarray

Hermite series of the derivative.

See also

hermeint

Notes

In general, the result of differentiating a Hermite series does not resemble the same operation on a power series. Thus the result of this function may be “unintuitive,” albeit correct; see Examples section below.

Examples

>>> from numpy.polynomial.hermite_e import hermeder
>>> hermeder([ 1.,  1.,  1.,  1.])
array([ 1.,  2.,  3.])
>>> hermeder([-0.25,  1.,  1./2.,  1./3.,  1./4 ], m=2)
array([ 1.,  2.,  3.])


numpy.polynomial.hermite_e.hermeint

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermeder

Next topic

numpy.polynomial.hermite_e.hermeadd

numpy.polynomial.hermite_e.hermeint

numpy.polynomial.hermite_e.hermeint(c, m=1, k=[], lbnd=0, scl=1, axis=0) [source]

Integrate a Hermite_e series.

Returns the Hermite_e series coefficients c integrated m times from lbnd along axis. At each iteration the resulting series is multiplied by scl and an integration constant, k, is added. The scaling factor is for use in a linear change of variable. (“Buyer beware”: note that, depending on what one is doing, one may want scl to be the reciprocal of what one might expect; for more information, see the Notes section below.) The argument c is an array of coefficients from low to high degree along each axis, e.g., [1,2,3] represents the series H_0 + 2*H_1 + 3*H_2 while [[1,2],[1,2]] represents 1*H_0(x)*H_0(y) + 1*H_1(x)*H_0(y) + 2*H_0(x)*H_1(y) + 2*H_1(x)*H_1(y) if axis=0 is x and axis=1 is y.

Parameters:

c : array_like

Array of Hermite_e series coefficients. If c is multidimensional the different axis correspond to different variables with the degree in each axis given by the corresponding index.

m : int, optional

Order of integration, must be positive. (Default: 1)

k : {[], list, scalar}, optional

Integration constant(s). The value of the first integral at lbnd is the first value in the list, the value of the second integral at lbnd is the second value, etc. If k == [] (the default), all constants are set to zero. If m == 1, a single scalar can be given instead of a list.

lbnd : scalar, optional

The lower bound of the integral. (Default: 0)

scl : scalar, optional

Following each integration the result is multiplied by scl before the integration constant is added. (Default: 1)

axis : int, optional

Axis over which the integral is taken. (Default: 0).

New in version 1.7.0.
Returns:

S : ndarray

Hermite_e series coefficients of the integral.
Raises:

ValueError

If m < 0, len(k) > m, np.isscalar(lbnd) == False, or np.isscalar(scl) == False.

See also

hermeder

Notes

Note that the result of each integration is multiplied by scl. Why is this important to note? Say one is making a linear change of variable u = ax + b in an integral relative to x. Then .. math::dx = du/a, so one will need to set scl equal to 1/a - perhaps not what one would have first thought.

Also note that, in general, the result of integrating a C-series needs to be “reprojected” onto the C-series basis set. Thus, typically, the result of this function is “unintuitive,” albeit correct; see Examples section below.

Examples

>>> from numpy.polynomial.hermite_e import hermeint
>>> hermeint([1, 2, 3]) # integrate once, value 0 at 0.
array([ 1.,  1.,  1.,  1.])
>>> hermeint([1, 2, 3], m=2) # integrate twice, value & deriv 0 at 0
array([-0.25      ,  1.        ,  0.5       ,  0.33333333,  0.25      ])
>>> hermeint([1, 2, 3], k=1) # integrate once, value 1 at 0.
array([ 2.,  1.,  1.,  1.])
>>> hermeint([1, 2, 3], lbnd=-1) # integrate once, value 0 at -1
array([-1.,  1.,  1.,  1.])
>>> hermeint([1, 2, 3], m=2, k=[1, 2], lbnd=-1)
array([ 1.83333333,  0.        ,  0.5       ,  0.33333333,  0.25      ])


numpy.polynomial.hermite_e.hermeadd

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermeint

Next topic

numpy.polynomial.hermite_e.hermesub

numpy.polynomial.hermite_e.hermeadd

numpy.polynomial.hermite_e.hermeadd(c1, c2) [source]

Add one Hermite series to another.

Returns the sum of two Hermite series c1 + c2. The arguments are sequences of coefficients ordered from lowest order term to highest, i.e., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Hermite series coefficients ordered from low to high.
Returns:

out : ndarray

Array representing the Hermite series of their sum.

See also

hermesub, hermemul, hermediv, hermepow

Notes

Unlike multiplication, division, etc., the sum of two Hermite series is a Hermite series (without having to “reproject” the result onto the basis set) so addition, just like that of “standard” polynomials, is simply “component-wise.”

Examples

>>> from numpy.polynomial.hermite_e import hermeadd
>>> hermeadd([1, 2, 3], [1, 2, 3, 4])
array([ 2.,  4.,  6.,  4.])


numpy.polynomial.hermite_e.hermesub

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermeadd

Next topic

numpy.polynomial.hermite_e.hermemul

numpy.polynomial.hermite_e.hermesub

numpy.polynomial.hermite_e.hermesub(c1, c2) [source]

Subtract one Hermite series from another.

Returns the difference of two Hermite series c1 - c2. The sequences of coefficients are from lowest order term to highest, i.e., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Hermite series coefficients ordered from low to high.
Returns:

out : ndarray

Of Hermite series coefficients representing their difference.

See also

hermeadd, hermemul, hermediv, hermepow

Notes

Unlike multiplication, division, etc., the difference of two Hermite series is a Hermite series (without having to “reproject” the result onto the basis set) so subtraction, just like that of “standard” polynomials, is simply “component-wise.”

Examples

>>> from numpy.polynomial.hermite_e import hermesub
>>> hermesub([1, 2, 3, 4], [1, 2, 3])
array([ 0.,  0.,  0.,  4.])


numpy.polynomial.hermite_e.hermemul

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermesub

Next topic

numpy.polynomial.hermite_e.hermemulx

numpy.polynomial.hermite_e.hermemul

numpy.polynomial.hermite_e.hermemul(c1, c2) [source]

Multiply one Hermite series by another.

Returns the product of two Hermite series c1 * c2. The arguments are sequences of coefficients, from lowest order “term” to highest, e.g., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Hermite series coefficients ordered from low to high.
Returns:

out : ndarray

Of Hermite series coefficients representing their product.

See also

hermeadd, hermesub, hermediv, hermepow

Notes

In general, the (polynomial) product of two C-series results in terms that are not in the Hermite polynomial basis set. Thus, to express the product as a Hermite series, it is necessary to “reproject” the product onto said basis set, which may produce “unintuitive” (but correct) results; see Examples section below.

Examples

>>> from numpy.polynomial.hermite_e import hermemul
>>> hermemul([1, 2, 3], [0, 1, 2])
array([ 14.,  15.,  28.,   7.,   6.])


numpy.polynomial.hermite_e.hermemulx

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermemul

Next topic

numpy.polynomial.hermite_e.hermediv

numpy.polynomial.hermite_e.hermemulx

numpy.polynomial.hermite_e.hermemulx(c) [source]

Multiply a Hermite series by x.

Multiply the Hermite series c by x, where x is the independent variable.

Parameters:

c : array_like

1-D array of Hermite series coefficients ordered from low to high.
Returns:

out : ndarray

Array representing the result of the multiplication.

Notes

The multiplication uses the recursion relationship for Hermite polynomials in the form

xP_i(x) = (P_{i + 1}(x) + iP_{i - 1}(x)))

Examples

>>> from numpy.polynomial.hermite_e import hermemulx
>>> hermemulx([1, 2, 3])
array([ 2.,  7.,  2.,  3.])


numpy.polynomial.hermite_e.hermediv

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermemulx

Next topic

numpy.polynomial.hermite_e.hermepow

numpy.polynomial.hermite_e.hermediv

numpy.polynomial.hermite_e.hermediv(c1, c2) [source]

Divide one Hermite series by another.

Returns the quotient-with-remainder of two Hermite series c1 / c2. The arguments are sequences of coefficients from lowest order “term” to highest, e.g., [1,2,3] represents the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c1, c2 : array_like

1-D arrays of Hermite series coefficients ordered from low to high.
Returns:

[quo, rem] : ndarrays

Of Hermite series coefficients representing the quotient and remainder.

See also

hermeadd, hermesub, hermemul, hermepow

Notes

In general, the (polynomial) division of one Hermite series by another results in quotient and remainder terms that are not in the Hermite polynomial basis set. Thus, to express these results as a Hermite series, it is necessary to “reproject” the results onto the Hermite basis set, which may produce “unintuitive” (but correct) results; see Examples section below.

Examples

>>> from numpy.polynomial.hermite_e import hermediv
>>> hermediv([ 14.,  15.,  28.,   7.,   6.], [0, 1, 2])
(array([ 1.,  2.,  3.]), array([ 0.]))
>>> hermediv([ 15.,  17.,  28.,   7.,   6.], [0, 1, 2])
(array([ 1.,  2.,  3.]), array([ 1.,  2.]))


numpy.polynomial.hermite_e.hermepow

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermediv

Next topic

numpy.polynomial.hermite_e.hermegauss

numpy.polynomial.hermite_e.hermepow

numpy.polynomial.hermite_e.hermepow(c, pow, maxpower=16) [source]

Raise a Hermite series to a power.

Returns the Hermite series c raised to the power pow. The argument c is a sequence of coefficients ordered from low to high. i.e., [1,2,3] is the series P_0 + 2*P_1 + 3*P_2.

Parameters:

c : array_like

1-D array of Hermite series coefficients ordered from low to high.

pow : integer

Power to which the series will be raised

maxpower : integer, optional

Maximum power allowed. This is mainly to limit growth of the series to unmanageable size. Default is 16
Returns:

coef : ndarray

Hermite series of power.

See also

hermeadd, hermesub, hermemul, hermediv

Examples

>>> from numpy.polynomial.hermite_e import hermepow
>>> hermepow([1, 2, 3], 2)
array([ 23.,  28.,  46.,  12.,   9.])


numpy.polynomial.hermite_e.hermegauss

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermepow

Next topic

numpy.polynomial.hermite_e.hermeweight

numpy.polynomial.hermite_e.hermegauss

numpy.polynomial.hermite_e.hermegauss(deg) [source]

Gauss-HermiteE quadrature.

Computes the sample points and weights for Gauss-HermiteE quadrature. These sample points and weights will correctly integrate polynomials of degree 2*deg - 1 or less over the interval [image] with the weight function [image].

Parameters:

deg : int

Number of sample points and weights. It must be >= 1.
Returns:

x : ndarray

1-D ndarray containing the sample points.

y : ndarray

1-D ndarray containing the weights.

Notes

The results have only been tested up to degree 100, higher degrees may be problematic. The weights are determined by using the fact that

w_k = c / (He'_n(x_k) * He_{n-1}(x_k))

where c is a constant independent of k and [image] is the k’th root of [image], and then scaling the results to get the right value when integrating 1.


numpy.polynomial.hermite_e.hermeweight

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermegauss

Next topic

numpy.polynomial.hermite_e.hermecompanion

numpy.polynomial.hermite_e.hermeweight

numpy.polynomial.hermite_e.hermeweight(x) [source]

Weight function of the Hermite_e polynomials.

The weight function is [image] and the interval of integration is [image]. the HermiteE polynomials are orthogonal, but not normalized, with respect to this weight function.

Parameters:

x : array_like

Values at which the weight function will be computed.
Returns:

w : ndarray

The weight function at x.

Notes


numpy.polynomial.hermite_e.hermecompanion

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermeweight

Next topic

numpy.polynomial.hermite_e.hermedomain

numpy.polynomial.hermite_e.hermecompanion

numpy.polynomial.hermite_e.hermecompanion(c) [source]

Return the scaled companion matrix of c.

The basis polynomials are scaled so that the companion matrix is symmetric when c is an HermiteE basis polynomial. This provides better eigenvalue estimates than the unscaled case and for basis polynomials the eigenvalues are guaranteed to be real if numpy.linalg.eigvalsh is used to obtain them.

Parameters:

c : array_like

1-D array of HermiteE series coefficients ordered from low to high degree.
Returns:

mat : ndarray

Scaled companion matrix of dimensions (deg, deg).

Notes


numpy.polynomial.hermite_e.hermedomain

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermecompanion

Next topic

numpy.polynomial.hermite_e.hermezero

numpy.polynomial.hermite_e.hermedomain

numpy.polynomial.hermite_e.hermedomain = array([-1, 1])


numpy.polynomial.hermite_e.hermezero

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermedomain

Next topic

numpy.polynomial.hermite_e.hermeone

numpy.polynomial.hermite_e.hermezero

numpy.polynomial.hermite_e.hermezero = array([0])


numpy.polynomial.hermite_e.hermeone

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermezero

Next topic

numpy.polynomial.hermite_e.hermex

numpy.polynomial.hermite_e.hermeone

numpy.polynomial.hermite_e.hermeone = array([1])


numpy.polynomial.hermite_e.hermex

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermeone

Next topic

numpy.polynomial.hermite_e.hermetrim

numpy.polynomial.hermite_e.hermex

numpy.polynomial.hermite_e.hermex = array([0, 1])


numpy.polynomial.hermite_e.hermetrim

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermex

Next topic

numpy.polynomial.hermite_e.hermeline

numpy.polynomial.hermite_e.hermetrim

numpy.polynomial.hermite_e.hermetrim(c, tol=0) [source]

Remove “small” “trailing” coefficients from a polynomial.

“Small” means “small in absolute value” and is controlled by the parameter tol; “trailing” means highest order coefficient(s), e.g., in [0, 1, 1, 0, 0] (which represents 0 + x + x**2 + 0*x**3 + 0*x**4) both the 3-rd and 4-th order coefficients would be “trimmed.”

Parameters:

c : array_like

1-d array of coefficients, ordered from lowest order to highest.

tol : number, optional

Trailing (i.e., highest order) elements with absolute value less than or equal to tol (default value is zero) are removed.
Returns:

trimmed : ndarray

1-d array with trailing zeros removed. If the resulting series would be empty, a series containing a single zero is returned.
Raises:

ValueError

If tol < 0

See also

trimseq

Examples

>>> from numpy import polynomial as P
>>> P.trimcoef((0,0,3,0,5,0,0))
array([ 0.,  0.,  3.,  0.,  5.])
>>> P.trimcoef((0,0,1e-3,0,1e-5,0,0),1e-3) # item == tol is trimmed
array([ 0.])
>>> i = complex(0,1) # works for complex
>>> P.trimcoef((3e-4,1e-3*(1-i),5e-4,2e-5*(1+i)), 1e-3)
array([ 0.0003+0.j   ,  0.0010-0.001j])


numpy.polynomial.hermite_e.hermeline

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermetrim

Next topic

numpy.polynomial.hermite_e.herme2poly

numpy.polynomial.hermite_e.hermeline

numpy.polynomial.hermite_e.hermeline(off, scl) [source]

Hermite series whose graph is a straight line.

Parameters:

off, scl : scalars

The specified line is given by off + scl*x.
Returns:

y : ndarray

This module’s representation of the Hermite series for off + scl*x.

See also

polyline, chebline

Examples

>>> from numpy.polynomial.hermite_e import hermeline
>>> from numpy.polynomial.hermite_e import hermeline, hermeval
>>> hermeval(0,hermeline(3, 2))
3.0
>>> hermeval(1,hermeline(3, 2))
5.0


numpy.polynomial.hermite_e.herme2poly

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.hermeline

Next topic

numpy.polynomial.hermite_e.poly2herme

numpy.polynomial.hermite_e.herme2poly

numpy.polynomial.hermite_e.herme2poly(c) [source]

Convert a Hermite series to a polynomial.

Convert an array representing the coefficients of a Hermite series, ordered from lowest degree to highest, to an array of the coefficients of the equivalent polynomial (relative to the “standard” basis) ordered from lowest to highest degree.

Parameters:

c : array_like

1-D array containing the Hermite series coefficients, ordered from lowest order term to highest.
Returns:

pol : ndarray

1-D array containing the coefficients of the equivalent polynomial (relative to the “standard” basis) ordered from lowest order term to highest.

See also

poly2herme

Notes

The easy way to do conversions between polynomial basis sets is to use the convert method of a class instance.

Examples

>>> from numpy.polynomial.hermite_e import herme2poly
>>> herme2poly([  2.,  10.,   2.,   3.])
array([ 0.,  1.,  2.,  3.])


numpy.polynomial.hermite_e.poly2herme

  • Polynomials
  • Polynomial Package
  • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
  • index
  • next
  • previous

Previous topic

numpy.polynomial.hermite_e.herme2poly

Next topic

Poly1d

numpy.polynomial.hermite_e.poly2herme

numpy.polynomial.hermite_e.poly2herme(pol) [source]

Convert a polynomial to a Hermite series.

Convert an array representing the coefficients of a polynomial (relative to the “standard” basis) ordered from lowest degree to highest, to an array of the coefficients of the equivalent Hermite series, ordered from lowest to highest degree.

Parameters:

pol : array_like

1-D array containing the polynomial coefficients
Returns:

c : ndarray

1-D array containing the coefficients of the equivalent Hermite series.

See also

herme2poly

Notes

The easy way to do conversions between polynomial basis sets is to use the convert method of a class instance.

Examples

>>> from numpy.polynomial.hermite_e import poly2herme
>>> poly2herme(np.arange(4))
array([  2.,  10.,   2.,   3.])


Poly1d

  • Polynomials
  • next
  • previous

Table Of Contents

  • Poly1d
    • Basics
    • Fitting
    • Calculus
    • Arithmetic
    • Warnings

Previous topic

numpy.polynomial.hermite_e.poly2herme

Next topic

numpy.poly1d

Poly1d

Basics

poly1d(c_or_r[, r, variable]) | A one-dimensional polynomial class.
polyval(p, x) | Evaluate a polynomial at specific values.
poly(seq_of_zeros) | Find the coefficients of a polynomial with the given sequence of roots.
roots(p) | Return the roots of a polynomial with coefficients given in p.

Fitting

polyfit(x, y, deg[, rcond, full, w, cov]) Least squares polynomial fit.

Calculus

polyder(p[, m]) | Return the derivative of the specified order of a polynomial.
polyint(p[, m, k]) | Return an antiderivative (indefinite integral) of a polynomial.

Arithmetic

polyadd(a1, a2) | Find the sum of two polynomials.
polydiv(u, v) | Returns the quotient and remainder of polynomial division.
polymul(a1, a2) | Find the product of two polynomials.
polysub(a1, a2) | Difference (subtraction) of two polynomials.

Warnings

RankWarning Issued by polyfit when the Vandermonde matrix is rank deficient.


numpy.poly1d

  • Polynomials
  • Poly1d
  • index
  • next
  • previous

Previous topic

numpy.RankWarning

Next topic

numpy.poly1d.__call__

numpy.poly1d

class numpy.poly1d(c_or_r, r=0, variable=None) [source]

A one-dimensional polynomial class.

A convenience class, used to encapsulate “natural” operations on polynomials so that said operations may take on their customary form in code (see Examples).

Parameters:

c_or_r : array_like

The polynomial’s coefficients, in decreasing powers, or if the value of the second parameter is True, the polynomial’s roots (values where the polynomial evaluates to 0). For example, poly1d([1, 2, 3]) returns an object that represents x^2 + 2x + 3, whereas poly1d([1, 2, 3], True) returns one that represents (x-1)(x-2)(x-3) = x^3 - 6x^2 + 11x -6.

r : bool, optional

If True, c_or_r specifies the polynomial’s roots; the default is False.

variable : str, optional

Changes the variable used when printing p from x to variable (see Examples).

Examples

Construct the polynomial x^2 + 2x + 3:

>>> p = np.poly1d([1, 2, 3])
>>> print np.poly1d(p)
   2
1 x + 2 x + 3

Evaluate the polynomial at x = 0.5:

>>> p(0.5)
4.25

Find the roots:

>>> p.r
array([-1.+1.41421356j, -1.-1.41421356j])
>>> p(p.r)
array([ -4.44089210e-16+0.j,  -4.44089210e-16+0.j])

These numbers in the previous line represent (0, 0) to machine precision

Show the coefficients:

>>> p.c
array([1, 2, 3])

Display the order (the leading zero-coefficients are removed):

>>> p.order
2

Show the coefficient of the k-th power in the polynomial (which is equivalent to p.c[-(i+1)]):

>>> p[1]
2

Polynomials can be added, subtracted, multiplied, and divided (returns quotient and remainder):

>>> p * p
poly1d([ 1,  4, 10, 12,  9])

>>> (p**3 + 4) / p
(poly1d([  1.,   4.,  10.,  12.,   9.]), poly1d([ 4.]))

asarray(p) gives the coefficient array, so polynomials can be used in all functions that accept arrays:

>>> p**2 # square of polynomial
poly1d([ 1,  4, 10, 12,  9])

>>> np.square(p) # square of individual coefficients
array([1, 4, 9])

The variable used in the string representation of p can be modified, using the variable parameter:

>>> p = np.poly1d([1,2,3], variable='z')
>>> print p
   2
1 z + 2 z + 3

Construct a polynomial from its roots:

>>> np.poly1d([1, 2], True)
poly1d([ 1, -3,  2])

This is the same polynomial as obtained by:

>>> np.poly1d([1, -1]) * np.poly1d([1, -2])
poly1d([ 1, -3,  2])

Attributes

coeffs
order
variable

Methods

__call__(val)
deriv([m]) | Return a derivative of this polynomial.
integ([m, k]) | Return an antiderivative (indefinite integral) of this polynomial.


numpy.poly1d.__call__

  • Polynomials
  • Poly1d
  • numpy.poly1d
  • index
  • next
  • previous

Previous topic

numpy.poly1d

Next topic

numpy.poly1d.deriv

numpy.poly1d.__call__

poly1d.__call__(val) [source]


numpy.poly1d.deriv

  • Polynomials
  • Poly1d
  • numpy.poly1d
  • index
  • next
  • previous

Previous topic

numpy.poly1d.__call__

Next topic

numpy.poly1d.integ

numpy.poly1d.deriv

poly1d.deriv(m=1) [source]

Return a derivative of this polynomial.

Refer to polyder for full documentation.

See also

polyder
equivalent function


numpy.poly1d.integ

  • Polynomials
  • Poly1d
  • numpy.poly1d
  • index
  • next
  • previous

Previous topic

numpy.poly1d.deriv

Next topic

numpy.polyval

numpy.poly1d.integ

poly1d.integ(m=1, k=0) [source]

Return an antiderivative (indefinite integral) of this polynomial.

Refer to polyint for full documentation.

See also

polyint
equivalent function


numpy.polyval

  • Polynomials
  • Poly1d
  • index
  • next
  • previous

Previous topic

numpy.poly1d.integ

Next topic

numpy.poly

numpy.polyval

numpy.polyval(p, x) [source]

Evaluate a polynomial at specific values.

If p is of length N, this function returns the value:

p[0]*x**(N-1) + p[1]*x**(N-2) + ... + p[N-2]*x + p[N-1]

If x is a sequence, then p(x) is returned for each element of x. If x is another polynomial then the composite polynomial p(x(t)) is returned.

Parameters:

p : array_like or poly1d object

1D array of polynomial coefficients (including coefficients equal to zero) from highest degree to the constant term, or an instance of poly1d.

x : array_like or poly1d object

A number, a 1D array of numbers, or an instance of poly1d, “at” which to evaluate p.
Returns:

values : ndarray or poly1d

If x is a poly1d instance, the result is the composition of the two polynomials, i.e., x is “substituted” in p and the simplified result is returned. In addition, the type of x - array_like or poly1d - governs the type of the output: x array_like => values array_like, x a poly1d object => values is also.

See also

poly1d
A polynomial class.

Notes

Horner’s scheme [R65] is used to evaluate the polynomial. Even so, for polynomials of high degree the values may be inaccurate due to rounding errors. Use carefully.

References

[R65] (1, 2) I. N. Bronshtein, K. A. Semendyayev, and K. A. Hirsch (Eng. trans. Ed.), Handbook of Mathematics, New York, Van Nostrand Reinhold Co., 1985, pg. 720.

Examples

>>> np.polyval([3,0,1], 5)  # 3 * 5**2 + 0 * 5**1 + 1
76
>>> np.polyval([3,0,1], np.poly1d(5))
poly1d([ 76.])
>>> np.polyval(np.poly1d([3,0,1]), 5)
76
>>> np.polyval(np.poly1d([3,0,1]), np.poly1d(5))
poly1d([ 76.])


numpy.poly

  • Polynomials
  • Poly1d
  • index
  • next
  • previous

Previous topic

numpy.polyval

Next topic

numpy.roots

numpy.poly

numpy.poly(seq_of_zeros) [source]

Find the coefficients of a polynomial with the given sequence of roots.

Returns the coefficients of the polynomial whose leading coefficient is one for the given sequence of zeros (multiple roots must be included in the sequence as many times as their multiplicity; see Examples). A square matrix (or array, which will be treated as a matrix) can also be given, in which case the coefficients of the characteristic polynomial of the matrix are returned.

Parameters:

seq_of_zeros : array_like, shape (N,) or (N, N)

A sequence of polynomial roots, or a square array or matrix object.
Returns:

c : ndarray

1D array of polynomial coefficients from highest to lowest degree:

c[0] * x**(N) + c[1] * x**(N-1) + ... + c[N-1] * x + c[N] where c[0] always equals 1.
Raises:

ValueError

If input is the wrong shape (the input must be a 1-D or square 2-D array).

See also

polyval
Evaluate a polynomial at a point.
roots
Return the roots of a polynomial.
polyfit
Least squares polynomial fit.
poly1d
A one-dimensional polynomial class.

Notes

Specifying the roots of a polynomial still leaves one degree of freedom, typically represented by an undetermined leading coefficient. [R56] In the case of this function, that coefficient - the first one in the returned array - is always taken as one. (If for some reason you have one other point, the only automatic way presently to leverage that information is to use polyfit.)

The characteristic polynomial, [image], of an n-by-n matrix A is given by

,

where I is the n-by-n identity matrix. [R57]

References

[R56] (1, 2) M. Sullivan and M. Sullivan, III, “Algebra and Trignometry, Enhanced With Graphing Utilities,” Prentice-Hall, pg. 318, 1996.
[R57] (1, 2) G. Strang, “Linear Algebra and Its Applications, 2nd Edition,” Academic Press, pg. 182, 1980.

Examples

Given a sequence of a polynomial’s zeros:

>>> np.poly((0, 0, 0)) # Multiple root example
array([1, 0, 0, 0])

The line above represents z**3 + 0*z**2 + 0*z + 0.

>>> np.poly((-1./2, 0, 1./2))
array([ 1.  ,  0.  , -0.25,  0.  ])

The line above represents z**3 - z/4

>>> np.poly((np.random.random(1.)[0], 0, np.random.random(1.)[0]))
array([ 1.        , -0.77086955,  0.08618131,  0.        ]) #random

Given a square array object:

>>> P = np.array([[0, 1./3], [-1./2, 0]])
>>> np.poly(P)
array([ 1.        ,  0.        ,  0.16666667])

Or a square matrix object:

>>> np.poly(np.matrix(P))
array([ 1.        ,  0.        ,  0.16666667])

Note how in all cases the leading coefficient is always 1.


numpy.roots

  • Polynomials
  • Poly1d
  • index
  • next
  • previous

Previous topic

numpy.poly

Next topic

numpy.polyfit

numpy.roots

numpy.roots(p) [source]

Return the roots of a polynomial with coefficients given in p.

The values in the rank-1 array p are coefficients of a polynomial. If the length of p is n+1 then the polynomial is described by:

p[0] * x**n + p[1] * x**(n-1) + ... + p[n-1]*x + p[n]
Parameters:

p : array_like

Rank-1 array of polynomial coefficients.
Returns:

out : ndarray

An array containing the complex roots of the polynomial.
Raises:

ValueError

When p cannot be converted to a rank-1 array.

See also

poly
Find the coefficients of a polynomial with a given sequence of roots.
polyval
Evaluate a polynomial at a point.
polyfit
Least squares polynomial fit.
poly1d
A one-dimensional polynomial class.

Notes

The algorithm relies on computing the eigenvalues of the companion matrix [R243].

References

[R243] (1, 2) R. A. Horn & C. R. Johnson, Matrix Analysis. Cambridge, UK: Cambridge University Press, 1999, pp. 146-7.

Examples

>>> coeff = [3.2, 2, 1]
>>> np.roots(coeff)
array([-0.3125+0.46351241j, -0.3125-0.46351241j])


numpy.polyfit

  • Polynomials
  • Poly1d
  • index
  • next
  • previous

Previous topic

numpy.roots

Next topic

numpy.polyder

numpy.polyfit

numpy.polyfit(x, y, deg, rcond=None, full=False, w=None, cov=False) [source]

Least squares polynomial fit.

Fit a polynomial p(x) = p[0] * x**deg + ... + p[deg] of degree deg to points (x, y). Returns a vector of coefficients p that minimises the squared error.

Parameters:

x : array_like, shape (M,)

x-coordinates of the M sample points (x[i], y[i]).

y : array_like, shape (M,) or (M, K)

y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column.

deg : int

Degree of the fitting polynomial

rcond : float, optional

Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)*eps, where eps is the relative precision of the float type, about 2e-16 in most cases.

full : bool, optional

Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned.

w : array_like, shape (M,), optional

weights to apply to the y-coordinates of the sample points.

cov : bool, optional

Return the estimate and the covariance matrix of the estimate If full is True, then cov is not returned.
Returns:

p : ndarray, shape (M,) or (M, K)

Polynomial coefficients, highest power first. If y was 2-D, the coefficients for k-th data set are in p[:,k].

residuals, rank, singular_values, rcond :

Present only if full = True. Residuals of the least-squares fit, the effective rank of the scaled Vandermonde coefficient matrix, its singular values, and the specified value of rcond. For more details, see linalg.lstsq.

V : ndarray, shape (M,M) or (M,M,K)

Present only if full = False and cov`=True. The covariance matrix of the polynomial coefficient estimates. The diagonal of this matrix are the variance estimates for each coefficient. If y is a 2-D array, then the covariance matrix for the `k-th data set are in V[:,:,k]
Warns:

RankWarning

The rank of the coefficient matrix in the least-squares fit is deficient. The warning is only raised if full = False.

The warnings can be turned off by

>>> import warnings
>>> warnings.simplefilter('ignore', np.RankWarning)

See also

polyval
Computes polynomial values.
linalg.lstsq
Computes a least-squares fit.
scipy.interpolate.UnivariateSpline
Computes spline fits.

Notes

The solution minimizes the squared error

in the equations:

x[0]**n * p[0] + ... + x[0] * p[n-1] + p[n] = y[0]
x[1]**n * p[0] + ... + x[1] * p[n-1] + p[n] = y[1]
...
x[k]**n * p[0] + ... + x[k] * p[n-1] + p[n] = y[k]

The coefficient matrix of the coefficients p is a Vandermonde matrix.

polyfit issues a RankWarning when the least-squares fit is badly conditioned. This implies that the best fit is not well-defined due to numerical error. The results may be improved by lowering the polynomial degree or by replacing x by x - x.mean(). The rcond parameter can also be set to a value smaller than its default, but the resulting fit may be spurious: including contributions from the small singular values can add numerical noise to the result.

Note that fitting polynomial coefficients is inherently badly conditioned when the degree of the polynomial is large or the interval of sample points is badly centered. The quality of the fit should always be checked in these cases. When polynomial fits are not satisfactory, splines may be a good alternative.

References

[R58] Wikipedia, “Curve fitting”, http://en.wikipedia.org/wiki/Curve_fitting
[R59] Wikipedia, “Polynomial interpolation”, http://en.wikipedia.org/wiki/Polynomial_interpolation

Examples

>>> x = np.array([0.0, 1.0, 2.0, 3.0,  4.0,  5.0])
>>> y = np.array([0.0, 0.8, 0.9, 0.1, -0.8, -1.0])
>>> z = np.polyfit(x, y, 3)
>>> z
array([ 0.08703704, -0.81349206,  1.69312169, -0.03968254])

It is convenient to use poly1d objects for dealing with polynomials:

>>> p = np.poly1d(z)
>>> p(0.5)
0.6143849206349179
>>> p(3.5)
-0.34732142857143039
>>> p(10)
22.579365079365115

High-order polynomials may oscillate wildly:

>>> p30 = np.poly1d(np.polyfit(x, y, 30))
/... RankWarning: Polyfit may be poorly conditioned...
>>> p30(4)
-0.80000000000000204
>>> p30(5)
-0.99999999999999445
>>> p30(4.5)
-0.10547061179440398

Illustration:

>>> import matplotlib.pyplot as plt
>>> xp = np.linspace(-2, 6, 100)
>>> _ = plt.plot(x, y, '.', xp, p(xp), '-', xp, p30(xp), '--')
>>> plt.ylim(-2,2)
(-2, 2)
>>> plt.show()

(Source code, png, pdf)


numpy.polyder

  • Polynomials
  • Poly1d
  • index
  • next
  • previous

Previous topic

numpy.polyfit

Next topic

numpy.polyint

numpy.polyder

numpy.polyder(p, m=1) [source]

Return the derivative of the specified order of a polynomial.

Parameters:

p : poly1d or sequence

Polynomial to differentiate. A sequence is interpreted as polynomial coefficients, see poly1d.

m : int, optional

Order of differentiation (default: 1)
Returns:

der : poly1d

A new polynomial representing the derivative.

See also

polyint
Anti-derivative of a polynomial.
poly1d
Class for one-dimensional polynomials.

Examples

The derivative of the polynomial x^3 + x^2 + x^1 + 1 is:

>>> p = np.poly1d([1,1,1,1])
>>> p2 = np.polyder(p)
>>> p2
poly1d([3, 2, 1])

which evaluates to:

>>> p2(2.)
17.0

We can verify this, approximating the derivative with (f(x + h) - f(x))/h:

>>> (p(2. + 0.001) - p(2.)) / 0.001
17.007000999997857

The fourth-order derivative of a 3rd-order polynomial is zero:

>>> np.polyder(p, 2)
poly1d([6, 2])
>>> np.polyder(p, 3)
poly1d([6])
>>> np.polyder(p, 4)
poly1d([ 0.])


numpy.polyint

  • Polynomials
  • Poly1d
  • index
  • next
  • previous

Previous topic

numpy.polyder

Next topic

numpy.polyadd

numpy.polyint

numpy.polyint(p, m=1, k=None) [source]

Return an antiderivative (indefinite integral) of a polynomial.

The returned order m antiderivative P of polynomial p satisfies [image] and is defined up to m - 1 integration constants k. The constants determine the low-order polynomial part

of P so that P^{(j)}(0) = k_{m-j-1}.

Parameters:

p : {array_like, poly1d}

Polynomial to differentiate. A sequence is interpreted as polynomial coefficients, see poly1d.

m : int, optional

Order of the antiderivative. (Default: 1)

k : {None, list of m scalars, scalar}, optional

Integration constants. They are given in the order of integration: those corresponding to highest-order terms come first.

If None (default), all constants are assumed to be zero. If m = 1, a single scalar can be given instead of a list.

See also

polyder
derivative of a polynomial
poly1d.integ
equivalent method

Examples

The defining property of the antiderivative:

>>> p = np.poly1d([1,1,1])
>>> P = np.polyint(p)
>>> P
poly1d([ 0.33333333,  0.5       ,  1.        ,  0.        ])
>>> np.polyder(P) == p
True

The integration constants default to zero, but can be specified:

>>> P = np.polyint(p, 3)
>>> P(0)
0.0
>>> np.polyder(P)(0)
0.0
>>> np.polyder(P, 2)(0)
0.0
>>> P = np.polyint(p, 3, k=[6,5,3])
>>> P
poly1d([ 0.01666667,  0.04166667,  0.16666667,  3. ,  5. ,  3. ])

Note that 3 = 6 / 2!, and that the constants are given in the order of integrations. Constant of the highest-order polynomial term comes first:

>>> np.polyder(P, 2)(0)
6.0
>>> np.polyder(P, 1)(0)
5.0
>>> P(0)
3.0


numpy.polyadd

  • Polynomials
  • Poly1d
  • index
  • next
  • previous

Previous topic

numpy.polyint

Next topic

numpy.polydiv

numpy.polyadd

numpy.polyadd(a1, a2) [source]

Find the sum of two polynomials.

Returns the polynomial resulting from the sum of two input polynomials. Each input must be either a poly1d object or a 1D sequence of polynomial coefficients, from highest to lowest degree.

Parameters:

a1, a2 : array_like or poly1d object

Input polynomials.
Returns:

out : ndarray or poly1d object

The sum of the inputs. If either input is a poly1d object, then the output is also a poly1d object. Otherwise, it is a 1D array of polynomial coefficients from highest to lowest degree.

See also

poly1d
A one-dimensional polynomial class.

poly, polyadd, polyder, polydiv, polyfit, polyint, polysub, polyval

Examples

>>> np.polyadd([1, 2], [9, 5, 4])
array([9, 6, 6])

Using poly1d objects:

>>> p1 = np.poly1d([1, 2])
>>> p2 = np.poly1d([9, 5, 4])
>>> print p1
1 x + 2
>>> print p2
   2
9 x + 5 x + 4
>>> print np.polyadd(p1, p2)
   2
9 x + 6 x + 6


numpy.polydiv

  • Polynomials
  • Poly1d
  • index
  • next
  • previous

Previous topic

numpy.polyadd

Next topic

numpy.polymul

numpy.polydiv

numpy.polydiv(u, v) [source]

Returns the quotient and remainder of polynomial division.

The input arrays are the coefficients (including any coefficients equal to zero) of the “numerator” (dividend) and “denominator” (divisor) polynomials, respectively.

Parameters:

u : array_like or poly1d

Dividend polynomial’s coefficients.

v : array_like or poly1d

Divisor polynomial’s coefficients.
Returns:

q : ndarray

Coefficients, including those equal to zero, of the quotient.

r : ndarray

Coefficients, including those equal to zero, of the remainder.

See also

poly, polyadd, polyder, polydiv, polyfit, polyint, polymul, polysub, polyval

Notes

Both u and v must be 0-d or 1-d (ndim = 0 or 1), but u.ndim need not equal v.ndim. In other words, all four possible combinations - u.ndim = v.ndim = 0, u.ndim = v.ndim = 1, u.ndim = 1, v.ndim = 0, and u.ndim = 0, v.ndim = 1 - work.

Examples

>>> x = np.array([3.0, 5.0, 2.0])
>>> y = np.array([2.0, 1.0])
>>> np.polydiv(x, y)
(array([ 1.5 ,  1.75]), array([ 0.25]))


numpy.polymul

  • Polynomials
  • Poly1d
  • index
  • next
  • previous

Previous topic

numpy.polydiv

Next topic

numpy.polysub

numpy.polymul

numpy.polymul(a1, a2) [source]

Find the product of two polynomials.

Finds the polynomial resulting from the multiplication of the two input polynomials. Each input must be either a poly1d object or a 1D sequence of polynomial coefficients, from highest to lowest degree.

Parameters:

a1, a2 : array_like or poly1d object

Input polynomials.
Returns:

out : ndarray or poly1d object

The polynomial resulting from the multiplication of the inputs. If either inputs is a poly1d object, then the output is also a poly1d object. Otherwise, it is a 1D array of polynomial coefficients from highest to lowest degree.

See also

poly1d
A one-dimensional polynomial class.

poly, polyadd, polyder, polydiv, polyfit, polyint, polysub, polyval

convolve
Array convolution. Same output as polymul, but has parameter for overlap mode.

Examples

>>> np.polymul([1, 2, 3], [9, 5, 1])
array([ 9, 23, 38, 17,  3])

Using poly1d objects:

>>> p1 = np.poly1d([1, 2, 3])
>>> p2 = np.poly1d([9, 5, 1])
>>> print p1
   2
1 x + 2 x + 3
>>> print p2
   2
9 x + 5 x + 1
>>> print np.polymul(p1, p2)
   4      3      2
9 x + 23 x + 38 x + 17 x + 3


numpy.polysub

  • Polynomials
  • Poly1d
  • index
  • next
  • previous

Previous topic

numpy.polymul

Next topic

numpy.RankWarning

numpy.polysub

numpy.polysub(a1, a2) [source]

Difference (subtraction) of two polynomials.

Given two polynomials a1 and a2, returns a1 - a2. a1 and a2 can be either array_like sequences of the polynomials’ coefficients (including coefficients equal to zero), or poly1d objects.

Parameters:

a1, a2 : array_like or poly1d

Minuend and subtrahend polynomials, respectively.
Returns:

out : ndarray or poly1d

Array or poly1d object of the difference polynomial’s coefficients.

See also

polyval, polydiv, polymul, polyadd

Examples

(2 x^2 + 10 x - 2) - (3 x^2 + 10 x -4) = (-x^2 + 2)

>>> np.polysub([2, 10, -2], [3, 10, -4])
array([-1,  0,  2])


numpy.RankWarning

  • Polynomials
  • Poly1d
  • index
  • next
  • previous

Previous topic

numpy.polysub

Next topic

Random sampling (numpy.random)

numpy.RankWarning

exception numpy.RankWarning [source]

Issued by polyfit when the Vandermonde matrix is rank deficient.

For more information, a way to suppress the warning, and an example of RankWarning being issued, see polyfit.


Random sampling (numpy.random)

  • next
  • previous

Table Of Contents

  • Random sampling (numpy.random)
    • Simple random data
    • Permutations
    • Distributions
    • Random generator

Previous topic

numpy.RankWarning

Next topic

numpy.random.rand

Random sampling (numpy.random)

Simple random data

rand(d0, d1, ..., dn) | Random values in a given shape.
randn(d0, d1, ..., dn) | Return a sample (or samples) from the “standard normal” distribution.
randint(low[, high, size]) | Return random integers from low (inclusive) to high (exclusive).
random_integers(low[, high, size]) | Return random integers between low and high, inclusive.
random_sample([size]) | Return random floats in the half-open interval [0.0, 1.0).
random([size]) | Return random floats in the half-open interval [0.0, 1.0).
ranf([size]) | Return random floats in the half-open interval [0.0, 1.0).
sample([size]) | Return random floats in the half-open interval [0.0, 1.0).
choice(a[, size, replace, p]) | Generates a random sample from a given 1-D array
bytes(length) | Return random bytes.

Permutations

shuffle(x) | Modify a sequence in-place by shuffling its contents.
permutation(x) | Randomly permute a sequence, or return a permuted range.

Distributions

beta(a, b[, size]) | The Beta distribution over [0, 1].
binomial(n, p[, size]) | Draw samples from a binomial distribution.
chisquare(df[, size]) | Draw samples from a chi-square distribution.
dirichlet(alpha[, size]) | Draw samples from the Dirichlet distribution.
exponential([scale, size]) | Exponential distribution.
f(dfnum, dfden[, size]) | Draw samples from a F distribution.
gamma(shape[, scale, size]) | Draw samples from a Gamma distribution.
geometric(p[, size]) | Draw samples from the geometric distribution.
gumbel([loc, scale, size]) | Gumbel distribution.
hypergeometric(ngood, nbad, nsample[, size]) | Draw samples from a Hypergeometric distribution.
laplace([loc, scale, size]) | Draw samples from the Laplace or double exponential distribution with specified location (or mean) and scale (decay).
logistic([loc, scale, size]) | Draw samples from a Logistic distribution.
lognormal([mean, sigma, size]) | Return samples drawn from a log-normal distribution.
logseries(p[, size]) | Draw samples from a Logarithmic Series distribution.
multinomial(n, pvals[, size]) | Draw samples from a multinomial distribution.
multivariate_normal(mean, cov[, size]) | Draw random samples from a multivariate normal distribution.
negative_binomial(n, p[, size]) | Draw samples from a negative_binomial distribution.
noncentral_chisquare(df, nonc[, size]) | Draw samples from a noncentral chi-square distribution.
noncentral_f(dfnum, dfden, nonc[, size]) | Draw samples from the noncentral F distribution.
normal([loc, scale, size]) | Draw random samples from a normal (Gaussian) distribution.
pareto(a[, size]) | Draw samples from a Pareto II or Lomax distribution with specified shape.
poisson([lam, size]) | Draw samples from a Poisson distribution.
power(a[, size]) | Draws samples in [0, 1] from a power distribution with positive exponent a - 1.
rayleigh([scale, size]) | Draw samples from a Rayleigh distribution.
standard_cauchy([size]) | Standard Cauchy distribution with mode = 0.
standard_exponential([size]) | Draw samples from the standard exponential distribution.
standard_gamma(shape[, size]) | Draw samples from a Standard Gamma distribution.
standard_normal([size]) | Returns samples from a Standard Normal distribution (mean=0, stdev=1).
standard_t(df[, size]) | Standard Student’s t distribution with df degrees of freedom.
triangular(left, mode, right[, size]) | Draw samples from the triangular distribution.
uniform([low, high, size]) | Draw samples from a uniform distribution.
vonmises(mu, kappa[, size]) | Draw samples from a von Mises distribution.
wald(mean, scale[, size]) | Draw samples from a Wald, or Inverse Gaussian, distribution.
weibull(a[, size]) | Weibull distribution.
zipf(a[, size]) | Draw samples from a Zipf distribution.

Random generator

RandomState | Container for the Mersenne Twister pseudo-random number generator.
seed([seed]) | Seed the generator.
get_state() | Return a tuple representing the internal state of the generator.
set_state(state) | Set the internal state of the generator from a tuple.


numpy.random.rand

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.set_state

Next topic

numpy.random.randn

numpy.random.rand

numpy.random.rand(d0, d1, ..., dn)

Random values in a given shape.

Create an array of the given shape and propagate it with random samples from a uniform distribution over [0, 1).

Parameters:

d0, d1, ..., dn : int, optional

The dimensions of the returned array, should all be positive. If no argument is given a single Python float is returned.
Returns:

out : ndarray, shape (d0, d1, ..., dn)

Random values.

See also

random

Notes

This is a convenience function. If you want an interface that takes a shape-tuple as the first argument, refer to np.random.random_sample .

Examples

>>> np.random.rand(3,2)
array([[ 0.14022471,  0.96360618],  #random
       [ 0.37601032,  0.25528411],  #random
       [ 0.49313049,  0.94909878]]) #random


numpy.random.randn

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.rand

Next topic

numpy.random.randint

numpy.random.randn

numpy.random.randn(d0, d1, ..., dn)

Return a sample (or samples) from the “standard normal” distribution.

If positive, int_like or int-convertible arguments are provided, randn generates an array of shape (d0, d1, ..., dn), filled with random floats sampled from a univariate “normal” (Gaussian) distribution of mean 0 and variance 1 (if any of the [image] are floats, they are first converted to integers by truncation). A single float randomly sampled from the distribution is returned if no argument is provided.

This is a convenience function. If you want an interface that takes a tuple as the first argument, use numpy.random.standard_normal instead.

Parameters:

d0, d1, ..., dn : int, optional

The dimensions of the returned array, should be all positive. If no argument is given a single Python float is returned.
Returns:

Z : ndarray or float

A (d0, d1, ..., dn)-shaped array of floating-point samples from the standard normal distribution, or a single such float if no parameters were supplied.

See also

random.standard_normal
Similar, but takes a tuple as its argument.

Notes

For random samples from [image], use:

sigma * np.random.randn(...) + mu

Examples

>>> np.random.randn()
2.1923875335537315 #random

Two-by-four array of samples from N(3, 6.25):

>>> 2.5 * np.random.randn(2, 4) + 3
array([[-4.49401501,  4.00950034, -1.81814867,  7.29718677],  #random
       [ 0.39924804,  4.68456316,  4.99394529,  4.84057254]]) #random


numpy.random.randint

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.randn

Next topic

numpy.random.random_integers

numpy.random.randint

numpy.random.randint(low, high=None, size=None)

Return random integers from low (inclusive) to high (exclusive).

Return random integers from the “discrete uniform” distribution in the “half-open” interval [low, high). If high is None (the default), then results are from [0, low).

Parameters:

low : int

Lowest (signed) integer to be drawn from the distribution (unless high=None, in which case this parameter is the highest such integer).

high : int, optional

If provided, one above the largest (signed) integer to be drawn from the distribution (see above for behavior if high=None).

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : int or ndarray of ints

size-shaped array of random integers from the appropriate distribution, or a single such random int if size not provided.

See also

random.random_integers
similar to randint, only for the closed interval [low, high], and 1 is the lowest value if high is omitted. In particular, this other one is the one to use to generate uniformly distributed discrete non-integers.

Examples

>>> np.random.randint(2, size=10)
array([1, 0, 0, 0, 1, 1, 0, 0, 1, 0])
>>> np.random.randint(1, size=10)
array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0])

Generate a 2 x 4 array of ints between 0 and 4, inclusive:

>>> np.random.randint(5, size=(2, 4))
array([[4, 0, 2, 1],
       [3, 2, 2, 0]])


numpy.random.random_integers

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.randint

Next topic

numpy.random.random_sample

numpy.random.random_integers

numpy.random.random_integers(low, high=None, size=None)

Return random integers between low and high, inclusive.

Return random integers from the “discrete uniform” distribution in the closed interval [low, high]. If high is None (the default), then results are from [1, low].

Parameters:

low : int

Lowest (signed) integer to be drawn from the distribution (unless high=None, in which case this parameter is the highest such integer).

high : int, optional

If provided, the largest (signed) integer to be drawn from the distribution (see above for behavior if high=None).

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : int or ndarray of ints

size-shaped array of random integers from the appropriate distribution, or a single such random int if size not provided.

See also

random.randint
Similar to random_integers, only for the half-open interval [low, high), and 0 is the lowest value if high is omitted.

Notes

To sample from N evenly spaced floating-point numbers between a and b, use:

a + (b - a) * (np.random.random_integers(N) - 1) / (N - 1.)

Examples

>>> np.random.random_integers(5)
4
>>> type(np.random.random_integers(5))
<type 'int'>
>>> np.random.random_integers(5, size=(3.,2.))
array([[5, 4],
       [3, 3],
       [4, 5]])

Choose five random numbers from the set of five evenly-spaced numbers between 0 and 2.5, inclusive (i.e., from the set {0, 5/8, 10/8, 15/8, 20/8}):

>>> 2.5 * (np.random.random_integers(5, size=(5,)) - 1) / 4.
array([ 0.625,  1.25 ,  0.625,  0.625,  2.5  ])

Roll two six sided dice 1000 times and sum the results:

>>> d1 = np.random.random_integers(1, 6, 1000)
>>> d2 = np.random.random_integers(1, 6, 1000)
>>> dsums = d1 + d2

Display results as a histogram:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(dsums, 11, normed=True)
>>> plt.show()

(Source code, png, pdf)


numpy.random.random_sample

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.random_integers

Next topic

numpy.random.random

numpy.random.random_sample

numpy.random.random_sample(size=None)

Return random floats in the half-open interval [0.0, 1.0).

Results are from the “continuous uniform” distribution over the stated interval. To sample Unif[a, b), b > a multiply the output of random_sample by (b-a) and add a:

(b - a) * random_sample() + a
Parameters:

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : float or ndarray of floats

Array of random floats of shape size (unless size=None, in which case a single float is returned).

Examples

>>> np.random.random_sample()
0.47108547995356098
>>> type(np.random.random_sample())
<type 'float'>
>>> np.random.random_sample((5,))
array([ 0.30220482,  0.86820401,  0.1654503 ,  0.11659149,  0.54323428])

Three-by-two array of random numbers from [-5, 0):

>>> 5 * np.random.random_sample((3, 2)) - 5
array([[-3.99149989, -0.52338984],
       [-2.99091858, -0.79479508],
       [-1.23204345, -1.75224494]])


numpy.random.random

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.random_sample

Next topic

numpy.random.ranf

numpy.random.random

numpy.random.random(size=None)

Return random floats in the half-open interval [0.0, 1.0).

Results are from the “continuous uniform” distribution over the stated interval. To sample Unif[a, b), b > a multiply the output of random_sample by (b-a) and add a:

(b - a) * random_sample() + a
Parameters:

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : float or ndarray of floats

Array of random floats of shape size (unless size=None, in which case a single float is returned).

Examples

>>> np.random.random_sample()
0.47108547995356098
>>> type(np.random.random_sample())
<type 'float'>
>>> np.random.random_sample((5,))
array([ 0.30220482,  0.86820401,  0.1654503 ,  0.11659149,  0.54323428])

Three-by-two array of random numbers from [-5, 0):

>>> 5 * np.random.random_sample((3, 2)) - 5
array([[-3.99149989, -0.52338984],
       [-2.99091858, -0.79479508],
       [-1.23204345, -1.75224494]])


numpy.random.ranf

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.random

Next topic

numpy.random.sample

numpy.random.ranf

numpy.random.ranf(size=None)

Return random floats in the half-open interval [0.0, 1.0).

Results are from the “continuous uniform” distribution over the stated interval. To sample Unif[a, b), b > a multiply the output of random_sample by (b-a) and add a:

(b - a) * random_sample() + a
Parameters:

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : float or ndarray of floats

Array of random floats of shape size (unless size=None, in which case a single float is returned).

Examples

>>> np.random.random_sample()
0.47108547995356098
>>> type(np.random.random_sample())
<type 'float'>
>>> np.random.random_sample((5,))
array([ 0.30220482,  0.86820401,  0.1654503 ,  0.11659149,  0.54323428])

Three-by-two array of random numbers from [-5, 0):

>>> 5 * np.random.random_sample((3, 2)) - 5
array([[-3.99149989, -0.52338984],
       [-2.99091858, -0.79479508],
       [-1.23204345, -1.75224494]])


numpy.random.sample

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.ranf

Next topic

numpy.random.choice

numpy.random.sample

numpy.random.sample(size=None)

Return random floats in the half-open interval [0.0, 1.0).

Results are from the “continuous uniform” distribution over the stated interval. To sample Unif[a, b), b > a multiply the output of random_sample by (b-a) and add a:

(b - a) * random_sample() + a
Parameters:

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : float or ndarray of floats

Array of random floats of shape size (unless size=None, in which case a single float is returned).

Examples

>>> np.random.random_sample()
0.47108547995356098
>>> type(np.random.random_sample())
<type 'float'>
>>> np.random.random_sample((5,))
array([ 0.30220482,  0.86820401,  0.1654503 ,  0.11659149,  0.54323428])

Three-by-two array of random numbers from [-5, 0):

>>> 5 * np.random.random_sample((3, 2)) - 5
array([[-3.99149989, -0.52338984],
       [-2.99091858, -0.79479508],
       [-1.23204345, -1.75224494]])


numpy.random.choice

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.sample

Next topic

numpy.random.bytes

numpy.random.choice

numpy.random.choice(a, size=None, replace=True, p=None)

Generates a random sample from a given 1-D array

New in version 1.7.0.

Parameters:

a : 1-D array-like or int

If an ndarray, a random sample is generated from its elements. If an int, the random sample is generated as if a was np.arange(n)

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

replace : boolean, optional

Whether the sample is with or without replacement

p : 1-D array-like, optional

The probabilities associated with each entry in a. If not given the sample assumes a uniform distribution over all entries in a.
Returns:

samples : 1-D ndarray, shape (size,)

The generated random samples
Raises:

ValueError

If a is an int and less than zero, if a or p are not 1-dimensional, if a is an array-like of size 0, if p is not a vector of probabilities, if a and p have different lengths, or if replace=False and the sample size is greater than the population size

See also

randint, shuffle, permutation

Examples

Generate a uniform random sample from np.arange(5) of size 3:

>>> np.random.choice(5, 3)
array([0, 3, 4])
>>> #This is equivalent to np.random.randint(0,5,3)

Generate a non-uniform random sample from np.arange(5) of size 3:

>>> np.random.choice(5, 3, p=[0.1, 0, 0.3, 0.6, 0])
array([3, 3, 0])

Generate a uniform random sample from np.arange(5) of size 3 without replacement:

>>> np.random.choice(5, 3, replace=False)
array([3,1,0])
>>> #This is equivalent to np.random.permutation(np.arange(5))[:3]

Generate a non-uniform random sample from np.arange(5) of size 3 without replacement:

>>> np.random.choice(5, 3, replace=False, p=[0.1, 0, 0.3, 0.6, 0])
array([2, 3, 0])

Any of the above can be repeated with an arbitrary array-like instead of just integers. For instance:

>>> aa_milne_arr = ['pooh', 'rabbit', 'piglet', 'Christopher']
>>> np.random.choice(aa_milne_arr, 5, p=[0.5, 0.1, 0.1, 0.3])
array(['pooh', 'pooh', 'pooh', 'Christopher', 'piglet'],
      dtype='|S11')


numpy.random.bytes

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.choice

Next topic

numpy.random.shuffle

numpy.random.bytes

numpy.random.bytes(length)

Return random bytes.

Parameters:

length : int

Number of random bytes.
Returns:

out : str

String of length length.

Examples

>>> np.random.bytes(10)
' eh\x85\x022SZ\xbf\xa4' #random


numpy.random.shuffle

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.bytes

Next topic

numpy.random.permutation

numpy.random.shuffle

numpy.random.shuffle(x)

Modify a sequence in-place by shuffling its contents.

Parameters:

x : array_like

The array or list to be shuffled.
Returns:

None

Examples

>>> arr = np.arange(10)
>>> np.random.shuffle(arr)
>>> arr
[1 7 5 2 9 4 3 6 0 8]

This function only shuffles the array along the first index of a multi-dimensional array:

>>> arr = np.arange(9).reshape((3, 3))
>>> np.random.shuffle(arr)
>>> arr
array([[3, 4, 5],
       [6, 7, 8],
       [0, 1, 2]])


numpy.random.permutation

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.shuffle

Next topic

numpy.random.beta

numpy.random.permutation

numpy.random.permutation(x)

Randomly permute a sequence, or return a permuted range.

If x is a multi-dimensional array, it is only shuffled along its first index.

Parameters:

x : int or array_like

If x is an integer, randomly permute np.arange(x). If x is an array, make a copy and shuffle the elements randomly.
Returns:

out : ndarray

Permuted sequence or array range.

Examples

>>> np.random.permutation(10)
array([1, 7, 4, 3, 0, 9, 2, 5, 8, 6])

>>> np.random.permutation([1, 4, 9, 12, 15])
array([15,  1,  9,  4, 12])

>>> arr = np.arange(9).reshape((3, 3))
>>> np.random.permutation(arr)
array([[6, 7, 8],
       [0, 1, 2],
       [3, 4, 5]])


numpy.random.beta

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.permutation

Next topic

numpy.random.binomial

numpy.random.beta

numpy.random.beta(a, b, size=None)

The Beta distribution over [0, 1].

The Beta distribution is a special case of the Dirichlet distribution, and is related to the Gamma distribution. It has the probability distribution function

where the normalisation, B, is the beta function,

It is often seen in Bayesian inference and order statistics.

Parameters:

a : float

Alpha, non-negative.

b : float

Beta, non-negative.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : ndarray

Array of the given shape, containing values drawn from a Beta distribution.


numpy.random.binomial

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.beta

Next topic

numpy.random.chisquare

numpy.random.binomial

numpy.random.binomial(n, p, size=None)

Draw samples from a binomial distribution.

Samples are drawn from a Binomial distribution with specified parameters, n trials and p probability of success where n an integer >= 0 and p is in the interval [0,1]. (n may be input as a float, but it is truncated to an integer in use)

Parameters:

n : float (but truncated to an integer)

parameter, >= 0.

p : float

parameter, >= 0 and <=1.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : {ndarray, scalar}

where the values are all integers in [0, n].

See also

scipy.stats.distributions.binom
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Binomial distribution is

where n is the number of trials, p is the probability of success, and N is the number of successes.

When estimating the standard error of a proportion in a population by using a random sample, the normal distribution works well unless the product p*n <=5, where p = population proportion estimate, and n = number of samples, in which case the binomial distribution is used instead. For example, a sample of 15 people shows 4 who are left handed, and 11 who are right handed. Then p = 4/15 = 27%. 0.27*15 = 4, so the binomial distribution should be used in this case.

References

[R184] Dalgaard, Peter, “Introductory Statistics with R”, Springer-Verlag, 2002.
[R185] Glantz, Stanton A. “Primer of Biostatistics.”, McGraw-Hill, Fifth Edition, 2002.
[R186] Lentner, Marvin, “Elementary Applied Statistics”, Bogden and Quigley, 1972.
[R187] Weisstein, Eric W. “Binomial Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/BinomialDistribution.html
[R188] Wikipedia, “Binomial-distribution”, http://en.wikipedia.org/wiki/Binomial_distribution

Examples

Draw samples from the distribution:

>>> n, p = 10, .5 # number of trials, probability of each trial
>>> s = np.random.binomial(n, p, 1000)
# result of flipping a coin 10 times, tested 1000 times.

A real world example. A company drills 9 wild-cat oil exploration wells, each with an estimated probability of success of 0.1. All nine wells fail. What is the probability of that happening?

Let’s do 20,000 trials of the model, and count the number that generate zero positive results.

>>> sum(np.random.binomial(9,0.1,20000)==0)/20000.
answer = 0.38885, or 38%.


numpy.random.chisquare

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.binomial

Next topic

numpy.random.dirichlet

numpy.random.chisquare

numpy.random.chisquare(df, size=None)

Draw samples from a chi-square distribution.

When df independent random variables, each with standard normal distributions (mean 0, variance 1), are squared and summed, the resulting distribution is chi-square (see Notes). This distribution is often used in hypothesis testing.

Parameters:

df : int

Number of degrees of freedom.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

output : ndarray

Samples drawn from the distribution, packed in a size-shaped array.
Raises:

ValueError

When df <= 0 or when an inappropriate size (e.g. size=-1) is given.

Notes

The variable obtained by summing the squares of df independent, standard normally distributed random variables:

is chi-square distributed, denoted

The probability density function of the chi-squared distribution is

where [image] is the gamma function,

References

NIST/SEMATECH e-Handbook of Statistical Methods

Examples

>>> np.random.chisquare(2,4)
array([ 1.89920014,  9.00867716,  3.13710533,  5.62318272])


numpy.random.dirichlet

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.chisquare

Next topic

numpy.random.exponential

numpy.random.dirichlet

numpy.random.dirichlet(alpha, size=None)

Draw samples from the Dirichlet distribution.

Draw size samples of dimension k from a Dirichlet distribution. A Dirichlet-distributed random variable can be seen as a multivariate generalization of a Beta distribution. Dirichlet pdf is the conjugate prior of a multinomial in Bayesian inference.

Parameters:

alpha : array

Parameter of the distribution (k dimension for sample of dimension k).

size : array

Number of samples to draw.
Returns:

samples : ndarray,

The drawn samples, of shape (alpha.ndim, size).

Notes

Uses the following property for computation: for each dimension, draw a random sample y_i from a standard gamma generator of shape alpha_i, then [image] is Dirichlet distributed.

References

[R189] David McKay, “Information Theory, Inference and Learning Algorithms,” chapter 23, http://www.inference.phy.cam.ac.uk/mackay/
[R190] Wikipedia, “Dirichlet distribution”, http://en.wikipedia.org/wiki/Dirichlet_distribution

Examples

Taking an example cited in Wikipedia, this distribution can be used if one wanted to cut strings (each of initial length 1.0) into K pieces with different lengths, where each piece had, on average, a designated average length, but allowing some variation in the relative sizes of the pieces.

>>> s = np.random.dirichlet((10, 5, 3), 20).transpose()

>>> plt.barh(range(20), s[0])
>>> plt.barh(range(20), s[1], left=s[0], color='g')
>>> plt.barh(range(20), s[2], left=s[0]+s[1], color='r')
>>> plt.title("Lengths of Strings")


numpy.random.exponential

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.dirichlet

Next topic

numpy.random.f

numpy.random.exponential

numpy.random.exponential(scale=1.0, size=None)

Exponential distribution.

Its probability density function is

for x > 0 and 0 elsewhere. is the scale parameter, which is the inverse of the rate parameter [image]. The rate parameter is an alternative, widely used parameterization of the exponential distribution [R193].

The exponential distribution is a continuous analogue of the geometric distribution. It describes many common situations, such as the size of raindrops measured over many rainstorms [R191], or the time between page requests to Wikipedia [R192].

Parameters:

scale : float

The scale parameter, [image].

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

References

[R191] (1, 2) Peyton Z. Peebles Jr., “Probability, Random Variables and Random Signal Principles”, 4th ed, 2001, p. 57.
[R192] (1, 2) “Poisson Process”, Wikipedia, http://en.wikipedia.org/wiki/Poisson_process
[R193] (1, 2) “Exponential Distribution, Wikipedia, http://en.wikipedia.org/wiki/Exponential_distribution


numpy.random.f

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.exponential

Next topic

numpy.random.gamma

numpy.random.f

numpy.random.f(dfnum, dfden, size=None)

Draw samples from a F distribution.

Samples are drawn from an F distribution with specified parameters, dfnum (degrees of freedom in numerator) and dfden (degrees of freedom in denominator), where both parameters should be greater than zero.

The random variate of the F distribution (also known as the Fisher distribution) is a continuous probability distribution that arises in ANOVA tests, and is the ratio of two chi-square variates.

Parameters:

dfnum : float

Degrees of freedom in numerator. Should be greater than zero.

dfden : float

Degrees of freedom in denominator. Should be greater than zero.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : {ndarray, scalar}

Samples from the Fisher distribution.

See also

scipy.stats.distributions.f
probability density function, distribution or cumulative density function, etc.

Notes

The F statistic is used to compare in-group variances to between-group variances. Calculating the distribution depends on the sampling, and so it is a function of the respective degrees of freedom in the problem. The variable dfnum is the number of samples minus one, the between-groups degrees of freedom, while dfden is the within-groups degrees of freedom, the sum of the number of samples in each group minus the number of groups.

References

[R194] Glantz, Stanton A. “Primer of Biostatistics.”, McGraw-Hill, Fifth Edition, 2002.
[R195] Wikipedia, “F-distribution”, http://en.wikipedia.org/wiki/F-distribution

Examples

An example from Glantz[1], pp 47-40. Two groups, children of diabetics (25 people) and children from people without diabetes (25 controls). Fasting blood glucose was measured, case group had a mean value of 86.1, controls had a mean value of 82.2. Standard deviations were 2.09 and 2.49 respectively. Are these data consistent with the null hypothesis that the parents diabetic status does not affect their children’s blood glucose levels? Calculating the F statistic from the data gives a value of 36.01.

Draw samples from the distribution:

>>> dfnum = 1. # between group degrees of freedom
>>> dfden = 48. # within groups degrees of freedom
>>> s = np.random.f(dfnum, dfden, 1000)

The lower bound for the top 1% of the samples is :

>>> sort(s)[-10]
7.61988120985

So there is about a 1% chance that the F statistic will exceed 7.62, the measured value is 36, so the null hypothesis is rejected at the 1% level.


numpy.random.gamma

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.f

Next topic

numpy.random.geometric

numpy.random.gamma

numpy.random.gamma(shape, scale=1.0, size=None)

Draw samples from a Gamma distribution.

Samples are drawn from a Gamma distribution with specified parameters, shape (sometimes designated “k”) and scale (sometimes designated “theta”), where both parameters are > 0.

Parameters:

shape : scalar > 0

The shape of the gamma distribution.

scale : scalar > 0, optional

The scale of the gamma distribution. Default is equal to 1.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : ndarray, float

Returns one sample unless size parameter is specified.

See also

scipy.stats.distributions.gamma
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Gamma distribution is

where k is the shape and [image] the scale, and [image] is the Gamma function.

The Gamma distribution is often used to model the times to failure of electronic components, and arises naturally in processes for which the waiting times between Poisson distributed events are relevant.

References

[R196] Weisstein, Eric W. “Gamma Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/GammaDistribution.html
[R197] Wikipedia, “Gamma-distribution”, http://en.wikipedia.org/wiki/Gamma-distribution

Examples

Draw samples from the distribution:

>>> shape, scale = 2., 2. # mean and dispersion
>>> s = np.random.gamma(shape, scale, 1000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> import scipy.special as sps
>>> count, bins, ignored = plt.hist(s, 50, normed=True)
>>> y = bins**(shape-1)*(np.exp(-bins/scale) /
...                      (sps.gamma(shape)*scale**shape))
>>> plt.plot(bins, y, linewidth=2, color='r')
>>> plt.show()

(Source code, png, pdf)


numpy.random.geometric

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.gamma

Next topic

numpy.random.gumbel

numpy.random.geometric

numpy.random.geometric(p, size=None)

Draw samples from the geometric distribution.

Bernoulli trials are experiments with one of two outcomes: success or failure (an example of such an experiment is flipping a coin). The geometric distribution models the number of trials that must be run in order to achieve success. It is therefore supported on the positive integers, k = 1, 2, ....

The probability mass function of the geometric distribution is

f(k) = (1 - p)^{k - 1} p

where p is the probability of success of an individual trial.

Parameters:

p : float

The probability of success of an individual trial.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : ndarray

Samples from the geometric distribution, shaped according to size.

Examples

Draw ten thousand values from the geometric distribution, with the probability of an individual success equal to 0.35:

>>> z = np.random.geometric(p=0.35, size=10000)

How many trials succeeded after a single run?

>>> (z == 1).sum() / 10000.
0.34889999999999999 #random


numpy.random.gumbel

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.geometric

Next topic

numpy.random.hypergeometric

numpy.random.gumbel

numpy.random.gumbel(loc=0.0, scale=1.0, size=None)

Gumbel distribution.

Draw samples from a Gumbel distribution with specified location and scale. For more information on the Gumbel distribution, see Notes and References below.

Parameters:

loc : float

The location of the mode of the distribution.

scale : float

The scale parameter of the distribution.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : ndarray

The samples

See also

scipy.stats.gumbel_l, scipy.stats.gumbel_r

scipy.stats.genextreme
probability density function, distribution, or cumulative density function, etc. for each of the above

weibull

Notes

The Gumbel (or Smallest Extreme Value (SEV) or the Smallest Extreme Value Type I) distribution is one of a class of Generalized Extreme Value (GEV) distributions used in modeling extreme value problems. The Gumbel is a special case of the Extreme Value Type I distribution for maximums from distributions with “exponential-like” tails.

The probability density for the Gumbel distribution is

where [image] is the mode, a location parameter, and [image] is the scale parameter.

The Gumbel (named for German mathematician Emil Julius Gumbel) was used very early in the hydrology literature, for modeling the occurrence of flood events. It is also used for modeling maximum wind speed and rainfall rates. It is a “fat-tailed” distribution - the probability of an event in the tail of the distribution is larger than if one used a Gaussian, hence the surprisingly frequent occurrence of 100-year floods. Floods were initially modeled as a Gaussian process, which underestimated the frequency of extreme events.

It is one of a class of extreme value distributions, the Generalized Extreme Value (GEV) distributions, which also includes the Weibull and Frechet.

The function has a mean of [image] and a variance of [image].

References

Gumbel, E. J., Statistics of Extremes, New York: Columbia University Press, 1958.

Reiss, R.-D. and Thomas, M., Statistical Analysis of Extreme Values from Insurance, Finance, Hydrology and Other Fields, Basel: Birkhauser Verlag, 2001.

Examples

Draw samples from the distribution:

>>> mu, beta = 0, 0.1 # location and scale
>>> s = np.random.gumbel(mu, beta, 1000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 30, normed=True)
>>> plt.plot(bins, (1/beta)*np.exp(-(bins - mu)/beta)
...          * np.exp( -np.exp( -(bins - mu) /beta) ),
...          linewidth=2, color='r')
>>> plt.show()

(Source code, png, pdf)

Show how an extreme value distribution can arise from a Gaussian process and compare to a Gaussian:

>>> means = []
>>> maxima = []
>>> for i in range(0,1000) :
...    a = np.random.normal(mu, beta, 1000)
...    means.append(a.mean())
...    maxima.append(a.max())
>>> count, bins, ignored = plt.hist(maxima, 30, normed=True)
>>> beta = np.std(maxima)*np.pi/np.sqrt(6)
>>> mu = np.mean(maxima) - 0.57721*beta
>>> plt.plot(bins, (1/beta)*np.exp(-(bins - mu)/beta)
...          * np.exp(-np.exp(-(bins - mu)/beta)),
...          linewidth=2, color='r')
>>> plt.plot(bins, 1/(beta * np.sqrt(2 * np.pi))
...          * np.exp(-(bins - mu)**2 / (2 * beta**2)),
...          linewidth=2, color='g')
>>> plt.show()

(png, pdf)


numpy.random.hypergeometric

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.gumbel

Next topic

numpy.random.laplace

numpy.random.hypergeometric

numpy.random.hypergeometric(ngood, nbad, nsample, size=None)

Draw samples from a Hypergeometric distribution.

Samples are drawn from a Hypergeometric distribution with specified parameters, ngood (ways to make a good selection), nbad (ways to make a bad selection), and nsample = number of items sampled, which is less than or equal to the sum ngood + nbad.

Parameters:

ngood : int or array_like

Number of ways to make a good selection. Must be nonnegative.

nbad : int or array_like

Number of ways to make a bad selection. Must be nonnegative.

nsample : int or array_like

Number of items sampled. Must be at least 1 and at most ngood + nbad.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : ndarray or scalar

The values are all integers in [0, n].

See also

scipy.stats.distributions.hypergeom
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Hypergeometric distribution is

where [image] and

for P(x) the probability of x successes, n = ngood, m = nbad, and N = number of samples.

Consider an urn with black and white marbles in it, ngood of them black and nbad are white. If you draw nsample balls without replacement, then the Hypergeometric distribution describes the distribution of black balls in the drawn sample.

Note that this distribution is very similar to the Binomial distribution, except that in this case, samples are drawn without replacement, whereas in the Binomial case samples are drawn with replacement (or the sample space is infinite). As the sample space becomes large, this distribution approaches the Binomial.

References

[R198] Lentner, Marvin, “Elementary Applied Statistics”, Bogden and Quigley, 1972.
[R199] Weisstein, Eric W. “Hypergeometric Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/HypergeometricDistribution.html
[R200] Wikipedia, “Hypergeometric-distribution”, http://en.wikipedia.org/wiki/Hypergeometric-distribution

Examples

Draw samples from the distribution:

>>> ngood, nbad, nsamp = 100, 2, 10
# number of good, number of bad, and number of samples
>>> s = np.random.hypergeometric(ngood, nbad, nsamp, 1000)
>>> hist(s)
#   note that it is very unlikely to grab both bad items

Suppose you have an urn with 15 white and 15 black marbles. If you pull 15 marbles at random, how likely is it that 12 or more of them are one color?

>>> s = np.random.hypergeometric(15, 15, 15, 100000)
>>> sum(s>=12)/100000. + sum(s<=3)/100000.
#   answer = 0.003 ... pretty unlikely!


numpy.random.laplace

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.hypergeometric

Next topic

numpy.random.logistic

numpy.random.laplace

numpy.random.laplace(loc=0.0, scale=1.0, size=None)

Draw samples from the Laplace or double exponential distribution with specified location (or mean) and scale (decay).

The Laplace distribution is similar to the Gaussian/normal distribution, but is sharper at the peak and has fatter tails. It represents the difference between two independent, identically distributed exponential random variables.

Parameters:

loc : float

The position, [image], of the distribution peak.

scale : float

, the exponential decay.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

Notes

It has the probability density function

The first law of Laplace, from 1774, states that the frequency of an error can be expressed as an exponential function of the absolute magnitude of the error, which leads to the Laplace distribution. For many problems in Economics and Health sciences, this distribution seems to model the data better than the standard Gaussian distribution

References

[R201] Abramowitz, M. and Stegun, I. A. (Eds.). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables, 9th printing. New York: Dover, 1972.
[R202] The Laplace distribution and generalizations By Samuel Kotz, Tomasz J. Kozubowski, Krzysztof Podgorski, Birkhauser, 2001.
[R203] Weisstein, Eric W. “Laplace Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/LaplaceDistribution.html
[R204] Wikipedia, “Laplace distribution”, http://en.wikipedia.org/wiki/Laplace_distribution

Examples

Draw samples from the distribution

>>> loc, scale = 0., 1.
>>> s = np.random.laplace(loc, scale, 1000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 30, normed=True)
>>> x = np.arange(-8., 8., .01)
>>> pdf = np.exp(-abs(x-loc)/scale)/(2.*scale)
>>> plt.plot(x, pdf)

Plot Gaussian for comparison:

>>> g = (1/(scale * np.sqrt(2 * np.pi)) *
...      np.exp(-(x - loc)**2 / (2 * scale**2)))
>>> plt.plot(x,g)

(Source code, png, pdf)


numpy.random.logistic

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.laplace

Next topic

numpy.random.lognormal

numpy.random.logistic

numpy.random.logistic(loc=0.0, scale=1.0, size=None)

Draw samples from a Logistic distribution.

Samples are drawn from a Logistic distribution with specified parameters, loc (location or mean, also median), and scale (>0).

Parameters:

loc : float

scale : float > 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : {ndarray, scalar}

where the values are all integers in [0, n].

See also

scipy.stats.distributions.logistic
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Logistic distribution is

where [image] = location and s = scale.

The Logistic distribution is used in Extreme Value problems where it can act as a mixture of Gumbel distributions, in Epidemiology, and by the World Chess Federation (FIDE) where it is used in the Elo ranking system, assuming the performance of each player is a logistically distributed random variable.

References

[R205] Reiss, R.-D. and Thomas M. (2001), Statistical Analysis of Extreme Values, from Insurance, Finance, Hydrology and Other Fields, Birkhauser Verlag, Basel, pp 132-133.
[R206] Weisstein, Eric W. “Logistic Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/LogisticDistribution.html
[R207] Wikipedia, “Logistic-distribution”, http://en.wikipedia.org/wiki/Logistic-distribution

Examples

Draw samples from the distribution:

>>> loc, scale = 10, 1
>>> s = np.random.logistic(loc, scale, 10000)
>>> count, bins, ignored = plt.hist(s, bins=50)

# plot against distribution

>>> def logist(x, loc, scale):
...     return exp((loc-x)/scale)/(scale*(1+exp((loc-x)/scale))**2)
>>> plt.plot(bins, logist(bins, loc, scale)*count.max()/\
... logist(bins, loc, scale).max())
>>> plt.show()


numpy.random.lognormal

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.logistic

Next topic

numpy.random.logseries

numpy.random.lognormal

numpy.random.lognormal(mean=0.0, sigma=1.0, size=None)

Return samples drawn from a log-normal distribution.

Draw samples from a log-normal distribution with specified mean, standard deviation, and array shape. Note that the mean and standard deviation are not the values for the distribution itself, but of the underlying normal distribution it is derived from.

Parameters:

mean : float

Mean value of the underlying normal distribution

sigma : float, > 0.

Standard deviation of the underlying normal distribution

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : ndarray or float

The desired samples. An array of the same shape as size if given, if size is None a float is returned.

See also

scipy.stats.lognorm
probability density function, distribution, cumulative density function, etc.

Notes

A variable x has a log-normal distribution if log(x) is normally distributed. The probability density function for the log-normal distribution is:

where [image] is the mean and [image] is the standard deviation of the normally distributed logarithm of the variable. A log-normal distribution results if a random variable is the product of a large number of independent, identically-distributed variables in the same way that a normal distribution results if the variable is the sum of a large number of independent, identically-distributed variables.

References

Limpert, E., Stahel, W. A., and Abbt, M., “Log-normal Distributions across the Sciences: Keys and Clues,” BioScience, Vol. 51, No. 5, May, 2001. http://stat.ethz.ch/~stahel/lognormal/bioscience.pdf

Reiss, R.D. and Thomas, M., Statistical Analysis of Extreme Values, Basel: Birkhauser Verlag, 2001, pp. 31-32.

Examples

Draw samples from the distribution:

>>> mu, sigma = 3., 1. # mean and standard deviation
>>> s = np.random.lognormal(mu, sigma, 1000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 100, normed=True, align='mid')

>>> x = np.linspace(min(bins), max(bins), 10000)
>>> pdf = (np.exp(-(np.log(x) - mu)**2 / (2 * sigma**2))
...        / (x * sigma * np.sqrt(2 * np.pi)))

>>> plt.plot(x, pdf, linewidth=2, color='r')
>>> plt.axis('tight')
>>> plt.show()

Demonstrate that taking the products of random samples from a uniform distribution can be fit well by a log-normal probability density function.

>>> # Generate a thousand samples: each is the product of 100 random
>>> # values, drawn from a normal distribution.
>>> b = []
>>> for i in range(1000):
...    a = 10. + np.random.random(100)
...    b.append(np.product(a))

>>> b = np.array(b) / np.min(b) # scale values to be positive
>>> count, bins, ignored = plt.hist(b, 100, normed=True, align='center')
>>> sigma = np.std(np.log(b))
>>> mu = np.mean(np.log(b))

>>> x = np.linspace(min(bins), max(bins), 10000)
>>> pdf = (np.exp(-(np.log(x) - mu)**2 / (2 * sigma**2))
...        / (x * sigma * np.sqrt(2 * np.pi)))

>>> plt.plot(x, pdf, color='r', linewidth=2)
>>> plt.show()

(Source code)


numpy.random.logseries

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.lognormal

Next topic

numpy.random.multinomial

numpy.random.logseries

numpy.random.logseries(p, size=None)

Draw samples from a Logarithmic Series distribution.

Samples are drawn from a Log Series distribution with specified parameter, p (probability, 0 < p < 1).

Parameters:

loc : float

scale : float > 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : {ndarray, scalar}

where the values are all integers in [0, n].

See also

scipy.stats.distributions.logser
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Log Series distribution is

where p = probability.

The Log Series distribution is frequently used to represent species richness and occurrence, first proposed by Fisher, Corbet, and Williams in 1943 [2]. It may also be used to model the numbers of occupants seen in cars [3].

References

[R208] Buzas, Martin A.; Culver, Stephen J., Understanding regional species diversity through the log series distribution of occurrences: BIODIVERSITY RESEARCH Diversity & Distributions, Volume 5, Number 5, September 1999 , pp. 187-195(9).
[R209] Fisher, R.A,, A.S. Corbet, and C.B. Williams. 1943. The relation between the number of species and the number of individuals in a random sample of an animal population. Journal of Animal Ecology, 12:42-58.
[R210] D. J. Hand, F. Daly, D. Lunn, E. Ostrowski, A Handbook of Small Data Sets, CRC Press, 1994.
[R211] Wikipedia, “Logarithmic-distribution”, http://en.wikipedia.org/wiki/Logarithmic-distribution

Examples

Draw samples from the distribution:

>>> a = .6
>>> s = np.random.logseries(a, 10000)
>>> count, bins, ignored = plt.hist(s)

# plot against distribution

>>> def logseries(k, p):
...     return -p**k/(k*log(1-p))
>>> plt.plot(bins, logseries(bins, a)*count.max()/
             logseries(bins, a).max(), 'r')
>>> plt.show()


numpy.random.multinomial

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.logseries

Next topic

numpy.random.multivariate_normal

numpy.random.multinomial

numpy.random.multinomial(n, pvals, size=None)

Draw samples from a multinomial distribution.

The multinomial distribution is a multivariate generalisation of the binomial distribution. Take an experiment with one of p possible outcomes. An example of such an experiment is throwing a dice, where the outcome can be 1 through 6. Each sample drawn from the distribution represents n such experiments. Its values, X_i = [X_0, X_1, ..., X_p], represent the number of times the outcome was i.

Parameters:

n : int

Number of experiments.

pvals : sequence of floats, length p

Probabilities of each of the p different outcomes. These should sum to 1 (however, the last element is always assumed to account for the remaining probability, as long as sum(pvals[:-1]) <= 1).

size : tuple of ints

Given a size of (M, N, K), then M*N*K samples are drawn, and the output shape becomes (M, N, K, p), since each sample has shape (p,).

Examples

Throw a dice 20 times:

>>> np.random.multinomial(20, [1/6.]*6, size=1)
array([[4, 1, 7, 5, 2, 1]])

It landed 4 times on 1, once on 2, etc.

Now, throw the dice 20 times, and 20 times again:

>>> np.random.multinomial(20, [1/6.]*6, size=2)
array([[3, 4, 3, 3, 4, 3],
       [2, 4, 3, 4, 0, 7]])

For the first run, we threw 3 times 1, 4 times 2, etc. For the second, we threw 2 times 1, 4 times 2, etc.

A loaded dice is more likely to land on number 6:

>>> np.random.multinomial(100, [1/7.]*5)
array([13, 16, 13, 16, 42])


numpy.random.multivariate_normal

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.multinomial

Next topic

numpy.random.negative_binomial

numpy.random.multivariate_normal

numpy.random.multivariate_normal(mean, cov[, size])

Draw random samples from a multivariate normal distribution.

The multivariate normal, multinormal or Gaussian distribution is a generalization of the one-dimensional normal distribution to higher dimensions. Such a distribution is specified by its mean and covariance matrix. These parameters are analogous to the mean (average or “center”) and variance (standard deviation, or “width,” squared) of the one-dimensional normal distribution.

Parameters:

mean : 1-D array_like, of length N

Mean of the N-dimensional distribution.

cov : 2-D array_like, of shape (N, N)

Covariance matrix of the distribution. Must be symmetric and positive-semidefinite for “physically meaningful” results.

size : int or tuple of ints, optional

Given a shape of, for example, (m,n,k), m*n*k samples are generated, and packed in an m-by-n-by-k arrangement. Because each sample is N-dimensional, the output shape is (m,n,k,N). If no shape is specified, a single (N-D) sample is returned.
Returns:

out : ndarray

The drawn samples, of shape size, if that was provided. If not, the shape is (N,).

In other words, each entry out[i,j,...,:] is an N-dimensional value drawn from the distribution.

Notes

The mean is a coordinate in N-dimensional space, which represents the location where samples are most likely to be generated. This is analogous to the peak of the bell curve for the one-dimensional or univariate normal distribution.

Covariance indicates the level to which two variables vary together. From the multivariate normal distribution, we draw N-dimensional samples, X = [x_1, x_2, ... x_N]. The covariance matrix element [image] is the covariance of [image] and [image]. The element [image] is the variance of [image] (i.e. its “spread”).

Instead of specifying the full covariance matrix, popular approximations include:

  • Spherical covariance (cov is a multiple of the identity matrix)
  • Diagonal covariance (cov has non-negative elements, and only on the diagonal)

This geometrical property can be seen in two dimensions by plotting generated data-points:

>>> mean = [0,0]
>>> cov = [[1,0],[0,100]] # diagonal covariance, points lie on x or y-axis

>>> import matplotlib.pyplot as plt
>>> x,y = np.random.multivariate_normal(mean,cov,5000).T
>>> plt.plot(x,y,'x'); plt.axis('equal'); plt.show()

Note that the covariance matrix must be non-negative definite.

References

Papoulis, A., Probability, Random Variables, and Stochastic Processes, 3rd ed., New York: McGraw-Hill, 1991.

Duda, R. O., Hart, P. E., and Stork, D. G., Pattern Classification, 2nd ed., New York: Wiley, 2001.

Examples

>>> mean = (1,2)
>>> cov = [[1,0],[1,0]]
>>> x = np.random.multivariate_normal(mean,cov,(3,3))
>>> x.shape
(3, 3, 2)

The following is probably true, given that 0.6 is roughly twice the standard deviation:

>>> print list( (x[0,0,:] - mean) < 0.6 )
[True, True]


numpy.random.negative_binomial

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.multivariate_normal

Next topic

numpy.random.noncentral_chisquare

numpy.random.negative_binomial

numpy.random.negative_binomial(n, p, size=None)

Draw samples from a negative_binomial distribution.

Samples are drawn from a negative_Binomial distribution with specified parameters, n trials and p probability of success where n is an integer > 0 and p is in the interval [0, 1].

Parameters:

n : int

Parameter, > 0.

p : float

Parameter, >= 0 and <=1.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : int or ndarray of ints

Drawn samples.

Notes

The probability density for the Negative Binomial distribution is

where n-1 is the number of successes, p is the probability of success, and N+n-1 is the number of trials.

The negative binomial distribution gives the probability of n-1 successes and N failures in N+n-1 trials, and success on the (N+n)th trial.

If one throws a die repeatedly until the third time a “1” appears, then the probability distribution of the number of non-“1”s that appear before the third “1” is a negative binomial distribution.

References

[R212] Weisstein, Eric W. “Negative Binomial Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/NegativeBinomialDistribution.html
[R213] Wikipedia, “Negative binomial distribution”, http://en.wikipedia.org/wiki/Negative_binomial_distribution

Examples

Draw samples from the distribution:

A real world example. A company drills wild-cat oil exploration wells, each with an estimated probability of success of 0.1. What is the probability of having one success for each successive well, that is what is the probability of a single success after drilling 5 wells, after 6 wells, etc.?

>>> s = np.random.negative_binomial(1, 0.1, 100000)
>>> for i in range(1, 11):
...    probability = sum(s<i) / 100000.
...    print i, "wells drilled, probability of one success =", probability


numpy.random.noncentral_chisquare

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.negative_binomial

Next topic

numpy.random.noncentral_f

numpy.random.noncentral_chisquare

numpy.random.noncentral_chisquare(df, nonc, size=None)

Draw samples from a noncentral chi-square distribution.

The noncentral [image] distribution is a generalisation of the [image] distribution.

Parameters:

df : int

Degrees of freedom, should be >= 1.

nonc : float

Non-centrality, should be > 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

Notes

The probability density function for the noncentral Chi-square distribution is

where [image] is the Chi-square with q degrees of freedom.

In Delhi (2007), it is noted that the noncentral chi-square is useful in bombing and coverage problems, the probability of killing the point target given by the noncentral chi-squared distribution.

References

[R214] Delhi, M.S. Holla, “On a noncentral chi-square distribution in the analysis of weapon systems effectiveness”, Metrika, Volume 15, Number 1 / December, 1970.
[R215] Wikipedia, “Noncentral chi-square distribution” http://en.wikipedia.org/wiki/Noncentral_chi-square_distribution

Examples

Draw values from the distribution and plot the histogram

>>> import matplotlib.pyplot as plt
>>> values = plt.hist(np.random.noncentral_chisquare(3, 20, 100000),
...                   bins=200, normed=True)
>>> plt.show()

(Source code, png, pdf)

Draw values from a noncentral chisquare with very small noncentrality, and compare to a chisquare.

>>> plt.figure()
>>> values = plt.hist(np.random.noncentral_chisquare(3, .0000001, 100000),
...                   bins=np.arange(0., 25, .1), normed=True)
>>> values2 = plt.hist(np.random.chisquare(3, 100000),
...                    bins=np.arange(0., 25, .1), normed=True)
>>> plt.plot(values[1][0:-1], values[0]-values2[0], 'ob')
>>> plt.show()

(png, pdf)

Demonstrate how large values of non-centrality lead to a more symmetric distribution.

>>> plt.figure()
>>> values = plt.hist(np.random.noncentral_chisquare(3, 20, 100000),
...                   bins=200, normed=True)
>>> plt.show()

(png, pdf)


numpy.random.noncentral_f

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.noncentral_chisquare

Next topic

numpy.random.normal

numpy.random.noncentral_f

numpy.random.noncentral_f(dfnum, dfden, nonc, size=None)

Draw samples from the noncentral F distribution.

Samples are drawn from an F distribution with specified parameters, dfnum (degrees of freedom in numerator) and dfden (degrees of freedom in denominator), where both parameters > 1. nonc is the non-centrality parameter.

Parameters:

dfnum : int

Parameter, should be > 1.

dfden : int

Parameter, should be > 1.

nonc : float

Parameter, should be >= 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : scalar or ndarray

Drawn samples.

Notes

When calculating the power of an experiment (power = probability of rejecting the null hypothesis when a specific alternative is true) the non-central F statistic becomes important. When the null hypothesis is true, the F statistic follows a central F distribution. When the null hypothesis is not true, then it follows a non-central F statistic.

References

Weisstein, Eric W. “Noncentral F-Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/NoncentralF-Distribution.html

Wikipedia, “Noncentral F distribution”, http://en.wikipedia.org/wiki/Noncentral_F-distribution

Examples

In a study, testing for a specific alternative to the null hypothesis requires use of the Noncentral F distribution. We need to calculate the area in the tail of the distribution that exceeds the value of the F distribution for the null hypothesis. We’ll plot the two probability distributions for comparison.

>>> dfnum = 3 # between group deg of freedom
>>> dfden = 20 # within groups degrees of freedom
>>> nonc = 3.0
>>> nc_vals = np.random.noncentral_f(dfnum, dfden, nonc, 1000000)
>>> NF = np.histogram(nc_vals, bins=50, normed=True)
>>> c_vals = np.random.f(dfnum, dfden, 1000000)
>>> F = np.histogram(c_vals, bins=50, normed=True)
>>> plt.plot(F[1][1:], F[0])
>>> plt.plot(NF[1][1:], NF[0])
>>> plt.show()


numpy.random.normal

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.noncentral_f

Next topic

numpy.random.pareto

numpy.random.normal

numpy.random.normal(loc=0.0, scale=1.0, size=None)

Draw random samples from a normal (Gaussian) distribution.

The probability density function of the normal distribution, first derived by De Moivre and 200 years later by both Gauss and Laplace independently [R217], is often called the bell curve because of its characteristic shape (see the example below).

The normal distributions occurs often in nature. For example, it describes the commonly occurring distribution of samples influenced by a large number of tiny, random disturbances, each with its own unique distribution [R217].

Parameters:

loc : float

Mean (“centre”) of the distribution.

scale : float

Standard deviation (spread or “width”) of the distribution.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

See also

scipy.stats.distributions.norm
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Gaussian distribution is

where [image] is the mean and [image] the standard deviation. The square of the standard deviation, [image], is called the variance.

The function has its peak at the mean, and its “spread” increases with the standard deviation (the function reaches 0.607 times its maximum at [image] and [image] [R217]). This implies that numpy.random.normal is more likely to return samples lying close to the mean, rather than those far away.

References

[R216] Wikipedia, “Normal distribution”, http://en.wikipedia.org/wiki/Normal_distribution
[R217] (1, 2, 3, 4) P. R. Peebles Jr., “Central Limit Theorem” in “Probability, Random Variables and Random Signal Principles”, 4th ed., 2001, pp. 51, 51, 125.

Examples

Draw samples from the distribution:

>>> mu, sigma = 0, 0.1 # mean and standard deviation
>>> s = np.random.normal(mu, sigma, 1000)

Verify the mean and the variance:

>>> abs(mu - np.mean(s)) < 0.01
True

>>> abs(sigma - np.std(s, ddof=1)) < 0.01
True

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 30, normed=True)
>>> plt.plot(bins, 1/(sigma * np.sqrt(2 * np.pi)) *
...                np.exp( - (bins - mu)**2 / (2 * sigma**2) ),
...          linewidth=2, color='r')
>>> plt.show()

(Source code, png, pdf)


numpy.random.pareto

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.normal

Next topic

numpy.random.poisson

numpy.random.pareto

numpy.random.pareto(a, size=None)

Draw samples from a Pareto II or Lomax distribution with specified shape.

The Lomax or Pareto II distribution is a shifted Pareto distribution. The classical Pareto distribution can be obtained from the Lomax distribution by adding the location parameter m, see below. The smallest value of the Lomax distribution is zero while for the classical Pareto distribution it is m, where the standard Pareto distribution has location m=1. Lomax can also be considered as a simplified version of the Generalized Pareto distribution (available in SciPy), with the scale set to one and the location set to zero.

The Pareto distribution must be greater than zero, and is unbounded above. It is also known as the “80-20 rule”. In this distribution, 80 percent of the weights are in the lowest 20 percent of the range, while the other 20 percent fill the remaining 80 percent of the range.

Parameters:

shape : float, > 0.

Shape of the distribution.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

See also

scipy.stats.distributions.lomax.pdf
probability density function, distribution or cumulative density function, etc.
scipy.stats.distributions.genpareto.pdf
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Pareto distribution is

where a is the shape and m the location

The Pareto distribution, named after the Italian economist Vilfredo Pareto, is a power law probability distribution useful in many real world problems. Outside the field of economics it is generally referred to as the Bradford distribution. Pareto developed the distribution to describe the distribution of wealth in an economy. It has also found use in insurance, web page access statistics, oil field sizes, and many other problems, including the download frequency for projects in Sourceforge [1]. It is one of the so-called “fat-tailed” distributions.

References

[R218] Francis Hunt and Paul Johnson, On the Pareto Distribution of Sourceforge projects.
[R219] Pareto, V. (1896). Course of Political Economy. Lausanne.
[R220] Reiss, R.D., Thomas, M.(2001), Statistical Analysis of Extreme Values, Birkhauser Verlag, Basel, pp 23-30.
[R221] Wikipedia, “Pareto distribution”, http://en.wikipedia.org/wiki/Pareto_distribution

Examples

Draw samples from the distribution:

>>> a, m = 3., 1. # shape and mode
>>> s = np.random.pareto(a, 1000) + m

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 100, normed=True, align='center')
>>> fit = a*m**a/bins**(a+1)
>>> plt.plot(bins, max(count)*fit/max(fit),linewidth=2, color='r')
>>> plt.show()

(Source code)


numpy.random.poisson

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.pareto

Next topic

numpy.random.power

numpy.random.poisson

numpy.random.poisson(lam=1.0, size=None)

Draw samples from a Poisson distribution.

The Poisson distribution is the limit of the Binomial distribution for large N.

Parameters:

lam : float or sequence of float

Expectation of interval, should be >= 0. A sequence of expectation intervals must be broadcastable over the requested size.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

Notes

The Poisson distribution

For events with an expected separation [image] the Poisson distribution [image] describes the probability of k events occurring within the observed interval [image].

Because the output is limited to the range of the C long type, a ValueError is raised when lam is within 10 sigma of the maximum representable value.

References

[R222] Weisstein, Eric W. “Poisson Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/PoissonDistribution.html
[R223] Wikipedia, “Poisson distribution”, http://en.wikipedia.org/wiki/Poisson_distribution

Examples

Draw samples from the distribution:

>>> import numpy as np
>>> s = np.random.poisson(5, 10000)

Display histogram of the sample:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 14, normed=True)
>>> plt.show()

(Source code, png, pdf)

Draw each 100 values for lambda 100 and 500:

>>> s = np.random.poisson(lam=(100., 500.), size=(100, 2))

()


numpy.random.power

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.poisson

Next topic

numpy.random.rayleigh

numpy.random.power

numpy.random.power(a, size=None)

Draws samples in [0, 1] from a power distribution with positive exponent a - 1.

Also known as the power function distribution.

Parameters:

a : float

parameter, > 0

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : {ndarray, scalar}

The returned samples lie in [0, 1].
Raises:

ValueError

If a<1.

Notes

The probability density function is

The power function distribution is just the inverse of the Pareto distribution. It may also be seen as a special case of the Beta distribution.

It is used, for example, in modeling the over-reporting of insurance claims.

References

[R224] Christian Kleiber, Samuel Kotz, “Statistical size distributions in economics and actuarial sciences”, Wiley, 2003.
[R225] Heckert, N. A. and Filliben, James J. (2003). NIST Handbook 148: Dataplot Reference Manual, Volume 2: Let Subcommands and Library Functions”, National Institute of Standards and Technology Handbook Series, June 2003. http://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/powpdf.pdf

Examples

Draw samples from the distribution:

>>> a = 5. # shape
>>> samples = 1000
>>> s = np.random.power(a, samples)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, bins=30)
>>> x = np.linspace(0, 1, 100)
>>> y = a*x**(a-1.)
>>> normed_y = samples*np.diff(bins)[0]*y
>>> plt.plot(x, normed_y)
>>> plt.show()

(Source code, png, pdf)

Compare the power function distribution to the inverse of the Pareto.

>>> from scipy import stats
>>> rvs = np.random.power(5, 1000000)
>>> rvsp = np.random.pareto(5, 1000000)
>>> xx = np.linspace(0,1,100)
>>> powpdf = stats.powerlaw.pdf(xx,5)

>>> plt.figure()
>>> plt.hist(rvs, bins=50, normed=True)
>>> plt.plot(xx,powpdf,'r-')
>>> plt.title('np.random.power(5)')

>>> plt.figure()
>>> plt.hist(1./(1.+rvsp), bins=50, normed=True)
>>> plt.plot(xx,powpdf,'r-')
>>> plt.title('inverse of 1 + np.random.pareto(5)')

>>> plt.figure()
>>> plt.hist(1./(1.+rvsp), bins=50, normed=True)
>>> plt.plot(xx,powpdf,'r-')
>>> plt.title('inverse of stats.pareto(5)')

(png, pdf)

(png, pdf)

(png, pdf)


numpy.random.rayleigh

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.power

Next topic

numpy.random.standard_cauchy

numpy.random.rayleigh

numpy.random.rayleigh(scale=1.0, size=None)

Draw samples from a Rayleigh distribution.

The [image] and Weibull distributions are generalizations of the Rayleigh.

Parameters:

scale : scalar

Scale, also equals the mode. Should be >= 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

Notes

The probability density function for the Rayleigh distribution is

The Rayleigh distribution arises if the wind speed and wind direction are both gaussian variables, then the vector wind velocity forms a Rayleigh distribution. The Rayleigh distribution is used to model the expected output from wind turbines.

References

[R226] Brighton Webs Ltd., Rayleigh Distribution, http://www.brighton-webs.co.uk/distributions/rayleigh.asp
[R227] Wikipedia, “Rayleigh distribution” http://en.wikipedia.org/wiki/Rayleigh_distribution

Examples

Draw values from the distribution and plot the histogram

>>> values = hist(np.random.rayleigh(3, 100000), bins=200, normed=True)

Wave heights tend to follow a Rayleigh distribution. If the mean wave height is 1 meter, what fraction of waves are likely to be larger than 3 meters?

>>> meanvalue = 1
>>> modevalue = np.sqrt(2 / np.pi) * meanvalue
>>> s = np.random.rayleigh(modevalue, 1000000)

The percentage of waves larger than 3 meters is:

>>> 100.*sum(s>3)/1000000.
0.087300000000000003


numpy.random.standard_cauchy

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.rayleigh

Next topic

numpy.random.standard_exponential

numpy.random.standard_cauchy

numpy.random.standard_cauchy(size=None)

Standard Cauchy distribution with mode = 0.

Also known as the Lorentz distribution.

Parameters:

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : ndarray or scalar

The drawn samples.

Notes

The probability density function for the full Cauchy distribution is

and the Standard Cauchy distribution just sets [image] and

The Cauchy distribution arises in the solution to the driven harmonic oscillator problem, and also describes spectral line broadening. It also describes the distribution of values at which a line tilted at a random angle will cut the x axis.

When studying hypothesis tests that assume normality, seeing how the tests perform on data from a Cauchy distribution is a good indicator of their sensitivity to a heavy-tailed distribution, since the Cauchy looks very much like a Gaussian distribution, but with heavier tails.

References

[R229] NIST/SEMATECH e-Handbook of Statistical Methods, “Cauchy Distribution”, http://www.itl.nist.gov/div898/handbook/eda/section3/eda3663.htm
[R230] Weisstein, Eric W. “Cauchy Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/CauchyDistribution.html
[R231] Wikipedia, “Cauchy distribution” http://en.wikipedia.org/wiki/Cauchy_distribution

Examples

Draw samples and plot the distribution:

>>> s = np.random.standard_cauchy(1000000)
>>> s = s[(s>-25) & (s<25)]  # truncate distribution so it plots well
>>> plt.hist(s, bins=100)
>>> plt.show()


numpy.random.standard_exponential

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.standard_cauchy

Next topic

numpy.random.standard_gamma

numpy.random.standard_exponential

numpy.random.standard_exponential(size=None)

Draw samples from the standard exponential distribution.

standard_exponential is identical to the exponential distribution with a scale parameter of 1.

Parameters:

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : float or ndarray

Drawn samples.

Examples

Output a 3x8000 array:

>>> n = np.random.standard_exponential((3, 8000))


numpy.random.standard_gamma

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.standard_exponential

Next topic

numpy.random.standard_normal

numpy.random.standard_gamma

numpy.random.standard_gamma(shape, size=None)

Draw samples from a Standard Gamma distribution.

Samples are drawn from a Gamma distribution with specified parameters, shape (sometimes designated “k”) and scale=1.

Parameters:

shape : float

Parameter, should be > 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : ndarray or scalar

The drawn samples.

See also

scipy.stats.distributions.gamma
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Gamma distribution is

where k is the shape and [image] the scale, and [image] is the Gamma function.

The Gamma distribution is often used to model the times to failure of electronic components, and arises naturally in processes for which the waiting times between Poisson distributed events are relevant.

References

[R232] Weisstein, Eric W. “Gamma Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/GammaDistribution.html
[R233] Wikipedia, “Gamma-distribution”, http://en.wikipedia.org/wiki/Gamma-distribution

Examples

Draw samples from the distribution:

>>> shape, scale = 2., 1. # mean and width
>>> s = np.random.standard_gamma(shape, 1000000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> import scipy.special as sps
>>> count, bins, ignored = plt.hist(s, 50, normed=True)
>>> y = bins**(shape-1) * ((np.exp(-bins/scale))/ \
...                       (sps.gamma(shape) * scale**shape))
>>> plt.plot(bins, y, linewidth=2, color='r')
>>> plt.show()

(Source code, png, pdf)


numpy.random.standard_normal

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.standard_gamma

Next topic

numpy.random.standard_t

numpy.random.standard_normal

numpy.random.standard_normal(size=None)

Returns samples from a Standard Normal distribution (mean=0, stdev=1).

Parameters:

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : float or ndarray

Drawn samples.

Examples

>>> s = np.random.standard_normal(8000)
>>> s
array([ 0.6888893 ,  0.78096262, -0.89086505, ...,  0.49876311, #random
       -0.38672696, -0.4685006 ])                               #random
>>> s.shape
(8000,)
>>> s = np.random.standard_normal(size=(3, 4, 2))
>>> s.shape
(3, 4, 2)


numpy.random.standard_t

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.standard_normal

Next topic

numpy.random.triangular

numpy.random.standard_t

numpy.random.standard_t(df, size=None)

Standard Student’s t distribution with df degrees of freedom.

A special case of the hyperbolic distribution. As df gets large, the result resembles that of the standard normal distribution (standard_normal).

Parameters:

df : int

Degrees of freedom, should be > 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : ndarray or scalar

Drawn samples.

Notes

The probability density function for the t distribution is

The t test is based on an assumption that the data come from a Normal distribution. The t test provides a way to test whether the sample mean (that is the mean calculated from the data) is a good estimate of the true mean.

The derivation of the t-distribution was forst published in 1908 by William Gisset while working for the Guinness Brewery in Dublin. Due to proprietary issues, he had to publish under a pseudonym, and so he used the name Student.

References

[R234] (1, 2) Dalgaard, Peter, “Introductory Statistics With R”, Springer, 2002.
[R235] Wikipedia, “Student’s t-distribution” http://en.wikipedia.org/wiki/Student’s_t-distribution

Examples

From Dalgaard page 83 [R234], suppose the daily energy intake for 11 women in Kj is:

>>> intake = np.array([5260., 5470, 5640, 6180, 6390, 6515, 6805, 7515, \
...                    7515, 8230, 8770])

Does their energy intake deviate systematically from the recommended value of 7725 kJ?

We have 10 degrees of freedom, so is the sample mean within 95% of the recommended value?

>>> s = np.random.standard_t(10, size=100000)
>>> np.mean(intake)
6753.636363636364
>>> intake.std(ddof=1)
1142.1232221373727

Calculate the t statistic, setting the ddof parameter to the unbiased value so the divisor in the standard deviation will be degrees of freedom, N-1.

>>> t = (np.mean(intake)-7725)/(intake.std(ddof=1)/np.sqrt(len(intake)))
>>> import matplotlib.pyplot as plt
>>> h = plt.hist(s, bins=100, normed=True)

For a one-sided t-test, how far out in the distribution does the t statistic appear?

>>> >>> np.sum(s<t) / float(len(s))
0.0090699999999999999  #random

So the p-value is about 0.009, which says the null hypothesis has a probability of about 99% of being true.

(Source code)


numpy.random.triangular

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.standard_t

Next topic

numpy.random.uniform

numpy.random.triangular

numpy.random.triangular(left, mode, right, size=None)

Draw samples from the triangular distribution.

The triangular distribution is a continuous probability distribution with lower limit left, peak at mode, and upper limit right. Unlike the other distributions, these parameters directly define the shape of the pdf.

Parameters:

left : scalar

Lower limit.

mode : scalar

The value where the peak of the distribution occurs. The value should fulfill the condition left <= mode <= right.

right : scalar

Upper limit, should be larger than left.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : ndarray or scalar

The returned samples all lie in the interval [left, right].

Notes

The probability density function for the Triangular distribution is

The triangular distribution is often used in ill-defined problems where the underlying distribution is not known, but some knowledge of the limits and mode exists. Often it is used in simulations.

References

[R236] Wikipedia, “Triangular distribution” http://en.wikipedia.org/wiki/Triangular_distribution

Examples

Draw values from the distribution and plot the histogram:

>>> import matplotlib.pyplot as plt
>>> h = plt.hist(np.random.triangular(-3, 0, 8, 100000), bins=200,
...              normed=True)
>>> plt.show()

(Source code, png, pdf)


numpy.random.uniform

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.triangular

Next topic

numpy.random.vonmises

numpy.random.uniform

numpy.random.uniform(low=0.0, high=1.0, size=None)

Draw samples from a uniform distribution.

Samples are uniformly distributed over the half-open interval [low, high) (includes low, but excludes high). In other words, any value within the given interval is equally likely to be drawn by uniform.

Parameters:

low : float, optional

Lower boundary of the output interval. All values generated will be greater than or equal to low. The default value is 0.

high : float

Upper boundary of the output interval. All values generated will be less than high. The default value is 1.0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : ndarray

Drawn samples, with shape size.

See also

randint
Discrete uniform distribution, yielding integers.
random_integers
Discrete uniform distribution over the closed interval [low, high].
random_sample
Floats uniformly distributed over [0, 1).
random
Alias for random_sample.
rand
Convenience function that accepts dimensions as input, e.g., rand(2,2) would generate a 2-by-2 array of floats, uniformly distributed over [0, 1).

Notes

The probability density function of the uniform distribution is

anywhere within the interval [a, b), and zero elsewhere.

Examples

Draw samples from the distribution:

>>> s = np.random.uniform(-1,0,1000)

All values are within the given interval:

>>> np.all(s >= -1)
True
>>> np.all(s < 0)
True

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 15, normed=True)
>>> plt.plot(bins, np.ones_like(bins), linewidth=2, color='r')
>>> plt.show()

(Source code, png, pdf)


numpy.random.vonmises

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.uniform

Next topic

numpy.random.wald

numpy.random.vonmises

numpy.random.vonmises(mu, kappa, size=None)

Draw samples from a von Mises distribution.

Samples are drawn from a von Mises distribution with specified mode (mu) and dispersion (kappa), on the interval [-pi, pi].

The von Mises distribution (also known as the circular normal distribution) is a continuous probability distribution on the unit circle. It may be thought of as the circular analogue of the normal distribution.

Parameters:

mu : float

Mode (“center”) of the distribution.

kappa : float

Dispersion of the distribution, has to be >=0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : scalar or ndarray

The returned samples, which are in the interval [-pi, pi].

See also

scipy.stats.distributions.vonmises
probability density function, distribution, or cumulative density function, etc.

Notes

The probability density for the von Mises distribution is

where [image] is the mode and [image] the dispersion, and [image] is the modified Bessel function of order 0.

The von Mises is named for Richard Edler von Mises, who was born in Austria-Hungary, in what is now the Ukraine. He fled to the United States in 1939 and became a professor at Harvard. He worked in probability theory, aerodynamics, fluid mechanics, and philosophy of science.

References

Abramowitz, M. and Stegun, I. A. (ed.), Handbook of Mathematical Functions, New York: Dover, 1965.

von Mises, R., Mathematical Theory of Probability and Statistics, New York: Academic Press, 1964.

Examples

Draw samples from the distribution:

>>> mu, kappa = 0.0, 4.0 # mean and dispersion
>>> s = np.random.vonmises(mu, kappa, 1000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> import scipy.special as sps
>>> count, bins, ignored = plt.hist(s, 50, normed=True)
>>> x = np.arange(-np.pi, np.pi, 2*np.pi/50.)
>>> y = -np.exp(kappa*np.cos(x-mu))/(2*np.pi*sps.jn(0,kappa))
>>> plt.plot(x, y/max(y), linewidth=2, color='r')
>>> plt.show()

(Source code, png, pdf)


numpy.random.wald

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.vonmises

Next topic

numpy.random.weibull

numpy.random.wald

numpy.random.wald(mean, scale, size=None)

Draw samples from a Wald, or Inverse Gaussian, distribution.

As the scale approaches infinity, the distribution becomes more like a Gaussian.

Some references claim that the Wald is an Inverse Gaussian with mean=1, but this is by no means universal.

The Inverse Gaussian distribution was first studied in relationship to Brownian motion. In 1956 M.C.K. Tweedie used the name Inverse Gaussian because there is an inverse relationship between the time to cover a unit distance and distance covered in unit time.

Parameters:

mean : scalar

Distribution mean, should be > 0.

scale : scalar

Scale parameter, should be >= 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : ndarray or scalar

Drawn sample, all greater than zero.

Notes

The probability density function for the Wald distribution is

As noted above the Inverse Gaussian distribution first arise from attempts to model Brownian Motion. It is also a competitor to the Weibull for use in reliability modeling and modeling stock returns and interest rate processes.

References

[R237] Brighton Webs Ltd., Wald Distribution, http://www.brighton-webs.co.uk/distributions/wald.asp
[R238] Chhikara, Raj S., and Folks, J. Leroy, “The Inverse Gaussian Distribution: Theory : Methodology, and Applications”, CRC Press, 1988.
[R239] Wikipedia, “Wald distribution” http://en.wikipedia.org/wiki/Wald_distribution

Examples

Draw values from the distribution and plot the histogram:

>>> import matplotlib.pyplot as plt
>>> h = plt.hist(np.random.wald(3, 2, 100000), bins=200, normed=True)
>>> plt.show()

(Source code, png, pdf)


numpy.random.weibull

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.wald

Next topic

numpy.random.zipf

numpy.random.weibull

numpy.random.weibull(a, size=None)

Weibull distribution.

Draw samples from a 1-parameter Weibull distribution with the given shape parameter a.

X = (-ln(U))^{1/a}

Here, U is drawn from the uniform distribution over (0,1].

The more common 2-parameter Weibull, including a scale parameter [image] is just [image].

Parameters:

a : float

Shape of the distribution.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

See also

scipy.stats.distributions.weibull_max, scipy.stats.distributions.weibull_min, scipy.stats.distributions.genextreme, gumbel

Notes

The Weibull (or Type III asymptotic extreme value distribution for smallest values, SEV Type III, or Rosin-Rammler distribution) is one of a class of Generalized Extreme Value (GEV) distributions used in modeling extreme value problems. This class includes the Gumbel and Frechet distributions.

The probability density for the Weibull distribution is

where a is the shape and [image] the scale.

The function has its peak (the mode) at [image].

When a = 1, the Weibull distribution reduces to the exponential distribution.

References

[R240] Waloddi Weibull, Professor, Royal Technical University, Stockholm, 1939 “A Statistical Theory Of The Strength Of Materials”, Ingeniorsvetenskapsakademiens Handlingar Nr 151, 1939, Generalstabens Litografiska Anstalts Forlag, Stockholm.
[R241] Waloddi Weibull, 1951 “A Statistical Distribution Function of Wide Applicability”, Journal Of Applied Mechanics ASME Paper.
[R242] Wikipedia, “Weibull distribution”, http://en.wikipedia.org/wiki/Weibull_distribution

Examples

Draw samples from the distribution:

>>> a = 5. # shape
>>> s = np.random.weibull(a, 1000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> x = np.arange(1,100.)/50.
>>> def weib(x,n,a):
...     return (a / n) * (x / n)**(a - 1) * np.exp(-(x / n)**a)

>>> count, bins, ignored = plt.hist(np.random.weibull(5.,1000))
>>> x = np.arange(1,100.)/50.
>>> scale = count.max()/weib(x, 1., 5.).max()
>>> plt.plot(x, weib(x, 1., 5.)*scale)
>>> plt.show()

(Source code, png, pdf)


numpy.random.zipf

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.weibull

Next topic

numpy.random.RandomState

numpy.random.zipf

numpy.random.zipf(a, size=None)

Draw samples from a Zipf distribution.

Samples are drawn from a Zipf distribution with specified parameter a > 1.

The Zipf distribution (also known as the zeta distribution) is a continuous probability distribution that satisfies Zipf’s law: the frequency of an item is inversely proportional to its rank in a frequency table.

Parameters:

a : float > 1

Distribution parameter.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : scalar or ndarray

The returned samples are greater than or equal to one.

See also

scipy.stats.distributions.zipf
probability density function, distribution, or cumulative density function, etc.

Notes

The probability density for the Zipf distribution is

where [image] is the Riemann Zeta function.

It is named for the American linguist George Kingsley Zipf, who noted that the frequency of any word in a sample of a language is inversely proportional to its rank in the frequency table.

References

Zipf, G. K., Selected Studies of the Principle of Relative Frequency in Language, Cambridge, MA: Harvard Univ. Press, 1932.

Examples

Draw samples from the distribution:

>>> a = 2. # parameter
>>> s = np.random.zipf(a, 1000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> import scipy.special as sps
Truncate s values at 50 so plot is interesting
>>> count, bins, ignored = plt.hist(s[s<50], 50, normed=True)
>>> x = np.arange(1., 50.)
>>> y = x**(-a)/sps.zetac(a)
>>> plt.plot(x, y/max(y), linewidth=2, color='r')
>>> plt.show()

(Source code, png, pdf)


numpy.random.RandomState

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.zipf

Next topic

numpy.random.RandomState.beta

numpy.random.RandomState

class numpy.random.RandomState

Container for the Mersenne Twister pseudo-random number generator.

RandomState exposes a number of methods for generating random numbers drawn from a variety of probability distributions. In addition to the distribution-specific arguments, each method takes a keyword argument size that defaults to None. If size is None, then a single value is generated and returned. If size is an integer, then a 1-D array filled with generated values is returned. If size is a tuple, then an array with that shape is filled and returned.

Parameters:

seed : {None, int, array_like}, optional

Random seed initializing the pseudo-random number generator. Can be an integer, an array (or other sequence) of integers of any length, or None (the default). If seed is None, then RandomState will try to read data from /dev/urandom (or the Windows analogue) if available or seed from the clock otherwise.

Notes

The Python stdlib module “random” also contains a Mersenne Twister pseudo-random number generator with a number of methods that are similar to the ones available in RandomState. RandomState, besides being NumPy-aware, has the advantage that it provides a much larger number of probability distributions to choose from.

Methods

beta(a, b[, size]) | The Beta distribution over [0, 1].
binomial(n, p[, size]) | Draw samples from a binomial distribution.
bytes(length) | Return random bytes.
chisquare(df[, size]) | Draw samples from a chi-square distribution.
choice(a[, size, replace, p]) | Generates a random sample from a given 1-D array
dirichlet(alpha[, size]) | Draw samples from the Dirichlet distribution.
exponential([scale, size]) | Exponential distribution.
f(dfnum, dfden[, size]) | Draw samples from a F distribution.
gamma(shape[, scale, size]) | Draw samples from a Gamma distribution.
geometric(p[, size]) | Draw samples from the geometric distribution.
get_state() | Return a tuple representing the internal state of the generator.
gumbel([loc, scale, size]) | Gumbel distribution.
hypergeometric(ngood, nbad, nsample[, size]) | Draw samples from a Hypergeometric distribution.
laplace([loc, scale, size]) | Draw samples from the Laplace or double exponential distribution with specified location (or mean) and scale (decay).
logistic([loc, scale, size]) | Draw samples from a Logistic distribution.
lognormal([mean, sigma, size]) | Return samples drawn from a log-normal distribution.
logseries(p[, size]) | Draw samples from a Logarithmic Series distribution.
multinomial(n, pvals[, size]) | Draw samples from a multinomial distribution.
multivariate_normal(mean, cov[, size]) | Draw random samples from a multivariate normal distribution.
negative_binomial(n, p[, size]) | Draw samples from a negative_binomial distribution.
noncentral_chisquare(df, nonc[, size]) | Draw samples from a noncentral chi-square distribution.
noncentral_f(dfnum, dfden, nonc[, size]) | Draw samples from the noncentral F distribution.
normal([loc, scale, size]) | Draw random samples from a normal (Gaussian) distribution.
pareto(a[, size]) | Draw samples from a Pareto II or Lomax distribution with specified shape.
permutation(x) | Randomly permute a sequence, or return a permuted range.
poisson([lam, size]) | Draw samples from a Poisson distribution.
power(a[, size]) | Draws samples in [0, 1] from a power distribution with positive exponent a - 1.
rand(d0, d1, ..., dn) | Random values in a given shape.
randint(low[, high, size]) | Return random integers from low (inclusive) to high (exclusive).
randn(d0, d1, ..., dn) | Return a sample (or samples) from the “standard normal” distribution.
random_integers(low[, high, size]) | Return random integers between low and high, inclusive.
random_sample([size]) | Return random floats in the half-open interval [0.0, 1.0).
rayleigh([scale, size]) | Draw samples from a Rayleigh distribution.
seed([seed]) | Seed the generator.
set_state(state) | Set the internal state of the generator from a tuple.
shuffle(x) | Modify a sequence in-place by shuffling its contents.
standard_cauchy([size]) | Standard Cauchy distribution with mode = 0.
standard_exponential([size]) | Draw samples from the standard exponential distribution.
standard_gamma(shape[, size]) | Draw samples from a Standard Gamma distribution.
standard_normal([size]) | Returns samples from a Standard Normal distribution (mean=0, stdev=1).
standard_t(df[, size]) | Standard Student’s t distribution with df degrees of freedom.
tomaxint([size]) | Random integers between 0 and sys.maxint, inclusive.
triangular(left, mode, right[, size]) | Draw samples from the triangular distribution.
uniform([low, high, size]) | Draw samples from a uniform distribution.
vonmises(mu, kappa[, size]) | Draw samples from a von Mises distribution.
wald(mean, scale[, size]) | Draw samples from a Wald, or Inverse Gaussian, distribution.
weibull(a[, size]) | Weibull distribution.
zipf(a[, size]) | Draw samples from a Zipf distribution.


numpy.random.RandomState.beta

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState

Next topic

numpy.random.RandomState.binomial

numpy.random.RandomState.beta

RandomState.beta(a, b, size=None)

The Beta distribution over [0, 1].

The Beta distribution is a special case of the Dirichlet distribution, and is related to the Gamma distribution. It has the probability distribution function

where the normalisation, B, is the beta function,

It is often seen in Bayesian inference and order statistics.

Parameters:

a : float

Alpha, non-negative.

b : float

Beta, non-negative.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : ndarray

Array of the given shape, containing values drawn from a Beta distribution.


numpy.random.RandomState.binomial

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.beta

Next topic

numpy.random.RandomState.bytes

numpy.random.RandomState.binomial

RandomState.binomial(n, p, size=None)

Draw samples from a binomial distribution.

Samples are drawn from a Binomial distribution with specified parameters, n trials and p probability of success where n an integer >= 0 and p is in the interval [0,1]. (n may be input as a float, but it is truncated to an integer in use)

Parameters:

n : float (but truncated to an integer)

parameter, >= 0.

p : float

parameter, >= 0 and <=1.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : {ndarray, scalar}

where the values are all integers in [0, n].

See also

scipy.stats.distributions.binom
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Binomial distribution is

where n is the number of trials, p is the probability of success, and N is the number of successes.

When estimating the standard error of a proportion in a population by using a random sample, the normal distribution works well unless the product p*n <=5, where p = population proportion estimate, and n = number of samples, in which case the binomial distribution is used instead. For example, a sample of 15 people shows 4 who are left handed, and 11 who are right handed. Then p = 4/15 = 27%. 0.27*15 = 4, so the binomial distribution should be used in this case.

References

[R125] Dalgaard, Peter, “Introductory Statistics with R”, Springer-Verlag, 2002.
[R126] Glantz, Stanton A. “Primer of Biostatistics.”, McGraw-Hill, Fifth Edition, 2002.
[R127] Lentner, Marvin, “Elementary Applied Statistics”, Bogden and Quigley, 1972.
[R128] Weisstein, Eric W. “Binomial Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/BinomialDistribution.html
[R129] Wikipedia, “Binomial-distribution”, http://en.wikipedia.org/wiki/Binomial_distribution

Examples

Draw samples from the distribution:

>>> n, p = 10, .5 # number of trials, probability of each trial
>>> s = np.random.binomial(n, p, 1000)
# result of flipping a coin 10 times, tested 1000 times.

A real world example. A company drills 9 wild-cat oil exploration wells, each with an estimated probability of success of 0.1. All nine wells fail. What is the probability of that happening?

Let’s do 20,000 trials of the model, and count the number that generate zero positive results.

>>> sum(np.random.binomial(9,0.1,20000)==0)/20000.
answer = 0.38885, or 38%.


numpy.random.RandomState.bytes

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.binomial

Next topic

numpy.random.RandomState.chisquare

numpy.random.RandomState.bytes

RandomState.bytes(length)

Return random bytes.

Parameters:

length : int

Number of random bytes.
Returns:

out : str

String of length length.

Examples

>>> np.random.bytes(10)
' eh\x85\x022SZ\xbf\xa4' #random


numpy.random.RandomState.chisquare

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.bytes

Next topic

numpy.random.RandomState.choice

numpy.random.RandomState.chisquare

RandomState.chisquare(df, size=None)

Draw samples from a chi-square distribution.

When df independent random variables, each with standard normal distributions (mean 0, variance 1), are squared and summed, the resulting distribution is chi-square (see Notes). This distribution is often used in hypothesis testing.

Parameters:

df : int

Number of degrees of freedom.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

output : ndarray

Samples drawn from the distribution, packed in a size-shaped array.
Raises:

ValueError

When df <= 0 or when an inappropriate size (e.g. size=-1) is given.

Notes

The variable obtained by summing the squares of df independent, standard normally distributed random variables:

is chi-square distributed, denoted

The probability density function of the chi-squared distribution is

where [image] is the gamma function,

References

NIST/SEMATECH e-Handbook of Statistical Methods

Examples

>>> np.random.chisquare(2,4)
array([ 1.89920014,  9.00867716,  3.13710533,  5.62318272])


numpy.random.RandomState.choice

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.chisquare

Next topic

numpy.random.RandomState.dirichlet

numpy.random.RandomState.choice

RandomState.choice(a, size=None, replace=True, p=None)

Generates a random sample from a given 1-D array

New in version 1.7.0.

Parameters:

a : 1-D array-like or int

If an ndarray, a random sample is generated from its elements. If an int, the random sample is generated as if a was np.arange(n)

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

replace : boolean, optional

Whether the sample is with or without replacement

p : 1-D array-like, optional

The probabilities associated with each entry in a. If not given the sample assumes a uniform distribution over all entries in a.
Returns:

samples : 1-D ndarray, shape (size,)

The generated random samples
Raises:

ValueError

If a is an int and less than zero, if a or p are not 1-dimensional, if a is an array-like of size 0, if p is not a vector of probabilities, if a and p have different lengths, or if replace=False and the sample size is greater than the population size

See also

randint, shuffle, permutation

Examples

Generate a uniform random sample from np.arange(5) of size 3:

>>> np.random.choice(5, 3)
array([0, 3, 4])
>>> #This is equivalent to np.random.randint(0,5,3)

Generate a non-uniform random sample from np.arange(5) of size 3:

>>> np.random.choice(5, 3, p=[0.1, 0, 0.3, 0.6, 0])
array([3, 3, 0])

Generate a uniform random sample from np.arange(5) of size 3 without replacement:

>>> np.random.choice(5, 3, replace=False)
array([3,1,0])
>>> #This is equivalent to np.random.permutation(np.arange(5))[:3]

Generate a non-uniform random sample from np.arange(5) of size 3 without replacement:

>>> np.random.choice(5, 3, replace=False, p=[0.1, 0, 0.3, 0.6, 0])
array([2, 3, 0])

Any of the above can be repeated with an arbitrary array-like instead of just integers. For instance:

>>> aa_milne_arr = ['pooh', 'rabbit', 'piglet', 'Christopher']
>>> np.random.choice(aa_milne_arr, 5, p=[0.5, 0.1, 0.1, 0.3])
array(['pooh', 'pooh', 'pooh', 'Christopher', 'piglet'],
      dtype='|S11')


numpy.random.RandomState.dirichlet

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.choice

Next topic

numpy.random.RandomState.exponential

numpy.random.RandomState.dirichlet

RandomState.dirichlet(alpha, size=None)

Draw samples from the Dirichlet distribution.

Draw size samples of dimension k from a Dirichlet distribution. A Dirichlet-distributed random variable can be seen as a multivariate generalization of a Beta distribution. Dirichlet pdf is the conjugate prior of a multinomial in Bayesian inference.

Parameters:

alpha : array

Parameter of the distribution (k dimension for sample of dimension k).

size : array

Number of samples to draw.
Returns:

samples : ndarray,

The drawn samples, of shape (alpha.ndim, size).

Notes

Uses the following property for computation: for each dimension, draw a random sample y_i from a standard gamma generator of shape alpha_i, then [image] is Dirichlet distributed.

References

[R130] David McKay, “Information Theory, Inference and Learning Algorithms,” chapter 23, http://www.inference.phy.cam.ac.uk/mackay/
[R131] Wikipedia, “Dirichlet distribution”, http://en.wikipedia.org/wiki/Dirichlet_distribution

Examples

Taking an example cited in Wikipedia, this distribution can be used if one wanted to cut strings (each of initial length 1.0) into K pieces with different lengths, where each piece had, on average, a designated average length, but allowing some variation in the relative sizes of the pieces.

>>> s = np.random.dirichlet((10, 5, 3), 20).transpose()

>>> plt.barh(range(20), s[0])
>>> plt.barh(range(20), s[1], left=s[0], color='g')
>>> plt.barh(range(20), s[2], left=s[0]+s[1], color='r')
>>> plt.title("Lengths of Strings")


numpy.random.RandomState.exponential

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.dirichlet

Next topic

numpy.random.RandomState.f

numpy.random.RandomState.exponential

RandomState.exponential(scale=1.0, size=None)

Exponential distribution.

Its probability density function is

for x > 0 and 0 elsewhere. is the scale parameter, which is the inverse of the rate parameter [image]. The rate parameter is an alternative, widely used parameterization of the exponential distribution [R134].

The exponential distribution is a continuous analogue of the geometric distribution. It describes many common situations, such as the size of raindrops measured over many rainstorms [R132], or the time between page requests to Wikipedia [R133].

Parameters:

scale : float

The scale parameter, [image].

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

References

[R132] (1, 2) Peyton Z. Peebles Jr., “Probability, Random Variables and Random Signal Principles”, 4th ed, 2001, p. 57.
[R133] (1, 2) “Poisson Process”, Wikipedia, http://en.wikipedia.org/wiki/Poisson_process
[R134] (1, 2) “Exponential Distribution, Wikipedia, http://en.wikipedia.org/wiki/Exponential_distribution


numpy.random.RandomState.f

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.exponential

Next topic

numpy.random.RandomState.gamma

numpy.random.RandomState.f

RandomState.f(dfnum, dfden, size=None)

Draw samples from a F distribution.

Samples are drawn from an F distribution with specified parameters, dfnum (degrees of freedom in numerator) and dfden (degrees of freedom in denominator), where both parameters should be greater than zero.

The random variate of the F distribution (also known as the Fisher distribution) is a continuous probability distribution that arises in ANOVA tests, and is the ratio of two chi-square variates.

Parameters:

dfnum : float

Degrees of freedom in numerator. Should be greater than zero.

dfden : float

Degrees of freedom in denominator. Should be greater than zero.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : {ndarray, scalar}

Samples from the Fisher distribution.

See also

scipy.stats.distributions.f
probability density function, distribution or cumulative density function, etc.

Notes

The F statistic is used to compare in-group variances to between-group variances. Calculating the distribution depends on the sampling, and so it is a function of the respective degrees of freedom in the problem. The variable dfnum is the number of samples minus one, the between-groups degrees of freedom, while dfden is the within-groups degrees of freedom, the sum of the number of samples in each group minus the number of groups.

References

[R135] Glantz, Stanton A. “Primer of Biostatistics.”, McGraw-Hill, Fifth Edition, 2002.
[R136] Wikipedia, “F-distribution”, http://en.wikipedia.org/wiki/F-distribution

Examples

An example from Glantz[1], pp 47-40. Two groups, children of diabetics (25 people) and children from people without diabetes (25 controls). Fasting blood glucose was measured, case group had a mean value of 86.1, controls had a mean value of 82.2. Standard deviations were 2.09 and 2.49 respectively. Are these data consistent with the null hypothesis that the parents diabetic status does not affect their children’s blood glucose levels? Calculating the F statistic from the data gives a value of 36.01.

Draw samples from the distribution:

>>> dfnum = 1. # between group degrees of freedom
>>> dfden = 48. # within groups degrees of freedom
>>> s = np.random.f(dfnum, dfden, 1000)

The lower bound for the top 1% of the samples is :

>>> sort(s)[-10]
7.61988120985

So there is about a 1% chance that the F statistic will exceed 7.62, the measured value is 36, so the null hypothesis is rejected at the 1% level.


numpy.random.RandomState.gamma

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.f

Next topic

numpy.random.RandomState.geometric

numpy.random.RandomState.gamma

RandomState.gamma(shape, scale=1.0, size=None)

Draw samples from a Gamma distribution.

Samples are drawn from a Gamma distribution with specified parameters, shape (sometimes designated “k”) and scale (sometimes designated “theta”), where both parameters are > 0.

Parameters:

shape : scalar > 0

The shape of the gamma distribution.

scale : scalar > 0, optional

The scale of the gamma distribution. Default is equal to 1.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : ndarray, float

Returns one sample unless size parameter is specified.

See also

scipy.stats.distributions.gamma
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Gamma distribution is

where k is the shape and [image] the scale, and [image] is the Gamma function.

The Gamma distribution is often used to model the times to failure of electronic components, and arises naturally in processes for which the waiting times between Poisson distributed events are relevant.

References

[R137] Weisstein, Eric W. “Gamma Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/GammaDistribution.html
[R138] Wikipedia, “Gamma-distribution”, http://en.wikipedia.org/wiki/Gamma-distribution

Examples

Draw samples from the distribution:

>>> shape, scale = 2., 2. # mean and dispersion
>>> s = np.random.gamma(shape, scale, 1000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> import scipy.special as sps
>>> count, bins, ignored = plt.hist(s, 50, normed=True)
>>> y = bins**(shape-1)*(np.exp(-bins/scale) /
...                      (sps.gamma(shape)*scale**shape))
>>> plt.plot(bins, y, linewidth=2, color='r')
>>> plt.show()

(Source code, png, pdf)


numpy.random.RandomState.geometric

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.gamma

Next topic

numpy.random.RandomState.get_state

numpy.random.RandomState.geometric

RandomState.geometric(p, size=None)

Draw samples from the geometric distribution.

Bernoulli trials are experiments with one of two outcomes: success or failure (an example of such an experiment is flipping a coin). The geometric distribution models the number of trials that must be run in order to achieve success. It is therefore supported on the positive integers, k = 1, 2, ....

The probability mass function of the geometric distribution is

f(k) = (1 - p)^{k - 1} p

where p is the probability of success of an individual trial.

Parameters:

p : float

The probability of success of an individual trial.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : ndarray

Samples from the geometric distribution, shaped according to size.

Examples

Draw ten thousand values from the geometric distribution, with the probability of an individual success equal to 0.35:

>>> z = np.random.geometric(p=0.35, size=10000)

How many trials succeeded after a single run?

>>> (z == 1).sum() / 10000.
0.34889999999999999 #random


numpy.random.RandomState.get_state

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.geometric

Next topic

numpy.random.RandomState.gumbel

numpy.random.RandomState.get_state

RandomState.get_state()

Return a tuple representing the internal state of the generator.

For more details, see set_state.

Returns:

out : tuple(str, ndarray of 624 uints, int, int, float)

The returned tuple has the following items:

  1. the string ‘MT19937’.
  2. a 1-D array of 624 unsigned integer keys.
  3. an integer pos.
  4. an integer has_gauss.
  5. a float cached_gaussian.

See also

set_state

Notes

set_state and get_state are not needed to work with any of the random distributions in NumPy. If the internal state is manually altered, the user should know exactly what he/she is doing.


numpy.random.RandomState.gumbel

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.get_state

Next topic

numpy.random.RandomState.hypergeometric

numpy.random.RandomState.gumbel

RandomState.gumbel(loc=0.0, scale=1.0, size=None)

Gumbel distribution.

Draw samples from a Gumbel distribution with specified location and scale. For more information on the Gumbel distribution, see Notes and References below.

Parameters:

loc : float

The location of the mode of the distribution.

scale : float

The scale parameter of the distribution.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : ndarray

The samples

See also

scipy.stats.gumbel_l, scipy.stats.gumbel_r

scipy.stats.genextreme
probability density function, distribution, or cumulative density function, etc. for each of the above

weibull

Notes

The Gumbel (or Smallest Extreme Value (SEV) or the Smallest Extreme Value Type I) distribution is one of a class of Generalized Extreme Value (GEV) distributions used in modeling extreme value problems. The Gumbel is a special case of the Extreme Value Type I distribution for maximums from distributions with “exponential-like” tails.

The probability density for the Gumbel distribution is

where [image] is the mode, a location parameter, and [image] is the scale parameter.

The Gumbel (named for German mathematician Emil Julius Gumbel) was used very early in the hydrology literature, for modeling the occurrence of flood events. It is also used for modeling maximum wind speed and rainfall rates. It is a “fat-tailed” distribution - the probability of an event in the tail of the distribution is larger than if one used a Gaussian, hence the surprisingly frequent occurrence of 100-year floods. Floods were initially modeled as a Gaussian process, which underestimated the frequency of extreme events.

It is one of a class of extreme value distributions, the Generalized Extreme Value (GEV) distributions, which also includes the Weibull and Frechet.

The function has a mean of [image] and a variance of [image].

References

Gumbel, E. J., Statistics of Extremes, New York: Columbia University Press, 1958.

Reiss, R.-D. and Thomas, M., Statistical Analysis of Extreme Values from Insurance, Finance, Hydrology and Other Fields, Basel: Birkhauser Verlag, 2001.

Examples

Draw samples from the distribution:

>>> mu, beta = 0, 0.1 # location and scale
>>> s = np.random.gumbel(mu, beta, 1000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 30, normed=True)
>>> plt.plot(bins, (1/beta)*np.exp(-(bins - mu)/beta)
...          * np.exp( -np.exp( -(bins - mu) /beta) ),
...          linewidth=2, color='r')
>>> plt.show()

(Source code, png, pdf)

Show how an extreme value distribution can arise from a Gaussian process and compare to a Gaussian:

>>> means = []
>>> maxima = []
>>> for i in range(0,1000) :
...    a = np.random.normal(mu, beta, 1000)
...    means.append(a.mean())
...    maxima.append(a.max())
>>> count, bins, ignored = plt.hist(maxima, 30, normed=True)
>>> beta = np.std(maxima)*np.pi/np.sqrt(6)
>>> mu = np.mean(maxima) - 0.57721*beta
>>> plt.plot(bins, (1/beta)*np.exp(-(bins - mu)/beta)
...          * np.exp(-np.exp(-(bins - mu)/beta)),
...          linewidth=2, color='r')
>>> plt.plot(bins, 1/(beta * np.sqrt(2 * np.pi))
...          * np.exp(-(bins - mu)**2 / (2 * beta**2)),
...          linewidth=2, color='g')
>>> plt.show()

(png, pdf)


numpy.random.RandomState.hypergeometric

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.gumbel

Next topic

numpy.random.RandomState.laplace

numpy.random.RandomState.hypergeometric

RandomState.hypergeometric(ngood, nbad, nsample, size=None)

Draw samples from a Hypergeometric distribution.

Samples are drawn from a Hypergeometric distribution with specified parameters, ngood (ways to make a good selection), nbad (ways to make a bad selection), and nsample = number of items sampled, which is less than or equal to the sum ngood + nbad.

Parameters:

ngood : int or array_like

Number of ways to make a good selection. Must be nonnegative.

nbad : int or array_like

Number of ways to make a bad selection. Must be nonnegative.

nsample : int or array_like

Number of items sampled. Must be at least 1 and at most ngood + nbad.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : ndarray or scalar

The values are all integers in [0, n].

See also

scipy.stats.distributions.hypergeom
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Hypergeometric distribution is

where [image] and

for P(x) the probability of x successes, n = ngood, m = nbad, and N = number of samples.

Consider an urn with black and white marbles in it, ngood of them black and nbad are white. If you draw nsample balls without replacement, then the Hypergeometric distribution describes the distribution of black balls in the drawn sample.

Note that this distribution is very similar to the Binomial distribution, except that in this case, samples are drawn without replacement, whereas in the Binomial case samples are drawn with replacement (or the sample space is infinite). As the sample space becomes large, this distribution approaches the Binomial.

References

[R139] Lentner, Marvin, “Elementary Applied Statistics”, Bogden and Quigley, 1972.
[R140] Weisstein, Eric W. “Hypergeometric Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/HypergeometricDistribution.html
[R141] Wikipedia, “Hypergeometric-distribution”, http://en.wikipedia.org/wiki/Hypergeometric-distribution

Examples

Draw samples from the distribution:

>>> ngood, nbad, nsamp = 100, 2, 10
# number of good, number of bad, and number of samples
>>> s = np.random.hypergeometric(ngood, nbad, nsamp, 1000)
>>> hist(s)
#   note that it is very unlikely to grab both bad items

Suppose you have an urn with 15 white and 15 black marbles. If you pull 15 marbles at random, how likely is it that 12 or more of them are one color?

>>> s = np.random.hypergeometric(15, 15, 15, 100000)
>>> sum(s>=12)/100000. + sum(s<=3)/100000.
#   answer = 0.003 ... pretty unlikely!


numpy.random.RandomState.laplace

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.hypergeometric

Next topic

numpy.random.RandomState.logistic

numpy.random.RandomState.laplace

RandomState.laplace(loc=0.0, scale=1.0, size=None)

Draw samples from the Laplace or double exponential distribution with specified location (or mean) and scale (decay).

The Laplace distribution is similar to the Gaussian/normal distribution, but is sharper at the peak and has fatter tails. It represents the difference between two independent, identically distributed exponential random variables.

Parameters:

loc : float

The position, [image], of the distribution peak.

scale : float

, the exponential decay.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

Notes

It has the probability density function

The first law of Laplace, from 1774, states that the frequency of an error can be expressed as an exponential function of the absolute magnitude of the error, which leads to the Laplace distribution. For many problems in Economics and Health sciences, this distribution seems to model the data better than the standard Gaussian distribution

References

[R142] Abramowitz, M. and Stegun, I. A. (Eds.). Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables, 9th printing. New York: Dover, 1972.
[R143] The Laplace distribution and generalizations By Samuel Kotz, Tomasz J. Kozubowski, Krzysztof Podgorski, Birkhauser, 2001.
[R144] Weisstein, Eric W. “Laplace Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/LaplaceDistribution.html
[R145] Wikipedia, “Laplace distribution”, http://en.wikipedia.org/wiki/Laplace_distribution

Examples

Draw samples from the distribution

>>> loc, scale = 0., 1.
>>> s = np.random.laplace(loc, scale, 1000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 30, normed=True)
>>> x = np.arange(-8., 8., .01)
>>> pdf = np.exp(-abs(x-loc)/scale)/(2.*scale)
>>> plt.plot(x, pdf)

Plot Gaussian for comparison:

>>> g = (1/(scale * np.sqrt(2 * np.pi)) *
...      np.exp(-(x - loc)**2 / (2 * scale**2)))
>>> plt.plot(x,g)

(Source code, png, pdf)


numpy.random.RandomState.logistic

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.laplace

Next topic

numpy.random.RandomState.lognormal

numpy.random.RandomState.logistic

RandomState.logistic(loc=0.0, scale=1.0, size=None)

Draw samples from a Logistic distribution.

Samples are drawn from a Logistic distribution with specified parameters, loc (location or mean, also median), and scale (>0).

Parameters:

loc : float

scale : float > 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : {ndarray, scalar}

where the values are all integers in [0, n].

See also

scipy.stats.distributions.logistic
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Logistic distribution is

where [image] = location and s = scale.

The Logistic distribution is used in Extreme Value problems where it can act as a mixture of Gumbel distributions, in Epidemiology, and by the World Chess Federation (FIDE) where it is used in the Elo ranking system, assuming the performance of each player is a logistically distributed random variable.

References

[R146] Reiss, R.-D. and Thomas M. (2001), Statistical Analysis of Extreme Values, from Insurance, Finance, Hydrology and Other Fields, Birkhauser Verlag, Basel, pp 132-133.
[R147] Weisstein, Eric W. “Logistic Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/LogisticDistribution.html
[R148] Wikipedia, “Logistic-distribution”, http://en.wikipedia.org/wiki/Logistic-distribution

Examples

Draw samples from the distribution:

>>> loc, scale = 10, 1
>>> s = np.random.logistic(loc, scale, 10000)
>>> count, bins, ignored = plt.hist(s, bins=50)

# plot against distribution

>>> def logist(x, loc, scale):
...     return exp((loc-x)/scale)/(scale*(1+exp((loc-x)/scale))**2)
>>> plt.plot(bins, logist(bins, loc, scale)*count.max()/\
... logist(bins, loc, scale).max())
>>> plt.show()


numpy.random.RandomState.lognormal

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.logistic

Next topic

numpy.random.RandomState.logseries

numpy.random.RandomState.lognormal

RandomState.lognormal(mean=0.0, sigma=1.0, size=None)

Return samples drawn from a log-normal distribution.

Draw samples from a log-normal distribution with specified mean, standard deviation, and array shape. Note that the mean and standard deviation are not the values for the distribution itself, but of the underlying normal distribution it is derived from.

Parameters:

mean : float

Mean value of the underlying normal distribution

sigma : float, > 0.

Standard deviation of the underlying normal distribution

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : ndarray or float

The desired samples. An array of the same shape as size if given, if size is None a float is returned.

See also

scipy.stats.lognorm
probability density function, distribution, cumulative density function, etc.

Notes

A variable x has a log-normal distribution if log(x) is normally distributed. The probability density function for the log-normal distribution is:

where [image] is the mean and [image] is the standard deviation of the normally distributed logarithm of the variable. A log-normal distribution results if a random variable is the product of a large number of independent, identically-distributed variables in the same way that a normal distribution results if the variable is the sum of a large number of independent, identically-distributed variables.

References

Limpert, E., Stahel, W. A., and Abbt, M., “Log-normal Distributions across the Sciences: Keys and Clues,” BioScience, Vol. 51, No. 5, May, 2001. http://stat.ethz.ch/~stahel/lognormal/bioscience.pdf

Reiss, R.D. and Thomas, M., Statistical Analysis of Extreme Values, Basel: Birkhauser Verlag, 2001, pp. 31-32.

Examples

Draw samples from the distribution:

>>> mu, sigma = 3., 1. # mean and standard deviation
>>> s = np.random.lognormal(mu, sigma, 1000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 100, normed=True, align='mid')

>>> x = np.linspace(min(bins), max(bins), 10000)
>>> pdf = (np.exp(-(np.log(x) - mu)**2 / (2 * sigma**2))
...        / (x * sigma * np.sqrt(2 * np.pi)))

>>> plt.plot(x, pdf, linewidth=2, color='r')
>>> plt.axis('tight')
>>> plt.show()

Demonstrate that taking the products of random samples from a uniform distribution can be fit well by a log-normal probability density function.

>>> # Generate a thousand samples: each is the product of 100 random
>>> # values, drawn from a normal distribution.
>>> b = []
>>> for i in range(1000):
...    a = 10. + np.random.random(100)
...    b.append(np.product(a))

>>> b = np.array(b) / np.min(b) # scale values to be positive
>>> count, bins, ignored = plt.hist(b, 100, normed=True, align='center')
>>> sigma = np.std(np.log(b))
>>> mu = np.mean(np.log(b))

>>> x = np.linspace(min(bins), max(bins), 10000)
>>> pdf = (np.exp(-(np.log(x) - mu)**2 / (2 * sigma**2))
...        / (x * sigma * np.sqrt(2 * np.pi)))

>>> plt.plot(x, pdf, color='r', linewidth=2)
>>> plt.show()

(Source code)


numpy.random.RandomState.logseries

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.lognormal

Next topic

numpy.random.RandomState.multinomial

numpy.random.RandomState.logseries

RandomState.logseries(p, size=None)

Draw samples from a Logarithmic Series distribution.

Samples are drawn from a Log Series distribution with specified parameter, p (probability, 0 < p < 1).

Parameters:

loc : float

scale : float > 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : {ndarray, scalar}

where the values are all integers in [0, n].

See also

scipy.stats.distributions.logser
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Log Series distribution is

where p = probability.

The Log Series distribution is frequently used to represent species richness and occurrence, first proposed by Fisher, Corbet, and Williams in 1943 [2]. It may also be used to model the numbers of occupants seen in cars [3].

References

[R149] Buzas, Martin A.; Culver, Stephen J., Understanding regional species diversity through the log series distribution of occurrences: BIODIVERSITY RESEARCH Diversity & Distributions, Volume 5, Number 5, September 1999 , pp. 187-195(9).
[R150] Fisher, R.A,, A.S. Corbet, and C.B. Williams. 1943. The relation between the number of species and the number of individuals in a random sample of an animal population. Journal of Animal Ecology, 12:42-58.
[R151] D. J. Hand, F. Daly, D. Lunn, E. Ostrowski, A Handbook of Small Data Sets, CRC Press, 1994.
[R152] Wikipedia, “Logarithmic-distribution”, http://en.wikipedia.org/wiki/Logarithmic-distribution

Examples

Draw samples from the distribution:

>>> a = .6
>>> s = np.random.logseries(a, 10000)
>>> count, bins, ignored = plt.hist(s)

# plot against distribution

>>> def logseries(k, p):
...     return -p**k/(k*log(1-p))
>>> plt.plot(bins, logseries(bins, a)*count.max()/
             logseries(bins, a).max(), 'r')
>>> plt.show()


numpy.random.RandomState.multinomial

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.logseries

Next topic

numpy.random.RandomState.multivariate_normal

numpy.random.RandomState.multinomial

RandomState.multinomial(n, pvals, size=None)

Draw samples from a multinomial distribution.

The multinomial distribution is a multivariate generalisation of the binomial distribution. Take an experiment with one of p possible outcomes. An example of such an experiment is throwing a dice, where the outcome can be 1 through 6. Each sample drawn from the distribution represents n such experiments. Its values, X_i = [X_0, X_1, ..., X_p], represent the number of times the outcome was i.

Parameters:

n : int

Number of experiments.

pvals : sequence of floats, length p

Probabilities of each of the p different outcomes. These should sum to 1 (however, the last element is always assumed to account for the remaining probability, as long as sum(pvals[:-1]) <= 1).

size : tuple of ints

Given a size of (M, N, K), then M*N*K samples are drawn, and the output shape becomes (M, N, K, p), since each sample has shape (p,).

Examples

Throw a dice 20 times:

>>> np.random.multinomial(20, [1/6.]*6, size=1)
array([[4, 1, 7, 5, 2, 1]])

It landed 4 times on 1, once on 2, etc.

Now, throw the dice 20 times, and 20 times again:

>>> np.random.multinomial(20, [1/6.]*6, size=2)
array([[3, 4, 3, 3, 4, 3],
       [2, 4, 3, 4, 0, 7]])

For the first run, we threw 3 times 1, 4 times 2, etc. For the second, we threw 2 times 1, 4 times 2, etc.

A loaded dice is more likely to land on number 6:

>>> np.random.multinomial(100, [1/7.]*5)
array([13, 16, 13, 16, 42])


numpy.random.RandomState.multivariate_normal

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.multinomial

Next topic

numpy.random.RandomState.negative_binomial

numpy.random.RandomState.multivariate_normal

RandomState.multivariate_normal(mean, cov[, size])

Draw random samples from a multivariate normal distribution.

The multivariate normal, multinormal or Gaussian distribution is a generalization of the one-dimensional normal distribution to higher dimensions. Such a distribution is specified by its mean and covariance matrix. These parameters are analogous to the mean (average or “center”) and variance (standard deviation, or “width,” squared) of the one-dimensional normal distribution.

Parameters:

mean : 1-D array_like, of length N

Mean of the N-dimensional distribution.

cov : 2-D array_like, of shape (N, N)

Covariance matrix of the distribution. Must be symmetric and positive-semidefinite for “physically meaningful” results.

size : int or tuple of ints, optional

Given a shape of, for example, (m,n,k), m*n*k samples are generated, and packed in an m-by-n-by-k arrangement. Because each sample is N-dimensional, the output shape is (m,n,k,N). If no shape is specified, a single (N-D) sample is returned.
Returns:

out : ndarray

The drawn samples, of shape size, if that was provided. If not, the shape is (N,).

In other words, each entry out[i,j,...,:] is an N-dimensional value drawn from the distribution.

Notes

The mean is a coordinate in N-dimensional space, which represents the location where samples are most likely to be generated. This is analogous to the peak of the bell curve for the one-dimensional or univariate normal distribution.

Covariance indicates the level to which two variables vary together. From the multivariate normal distribution, we draw N-dimensional samples, X = [x_1, x_2, ... x_N]. The covariance matrix element [image] is the covariance of [image] and [image]. The element [image] is the variance of [image] (i.e. its “spread”).

Instead of specifying the full covariance matrix, popular approximations include:

  • Spherical covariance (cov is a multiple of the identity matrix)
  • Diagonal covariance (cov has non-negative elements, and only on the diagonal)

This geometrical property can be seen in two dimensions by plotting generated data-points:

>>> mean = [0,0]
>>> cov = [[1,0],[0,100]] # diagonal covariance, points lie on x or y-axis

>>> import matplotlib.pyplot as plt
>>> x,y = np.random.multivariate_normal(mean,cov,5000).T
>>> plt.plot(x,y,'x'); plt.axis('equal'); plt.show()

Note that the covariance matrix must be non-negative definite.

References

Papoulis, A., Probability, Random Variables, and Stochastic Processes, 3rd ed., New York: McGraw-Hill, 1991.

Duda, R. O., Hart, P. E., and Stork, D. G., Pattern Classification, 2nd ed., New York: Wiley, 2001.

Examples

>>> mean = (1,2)
>>> cov = [[1,0],[1,0]]
>>> x = np.random.multivariate_normal(mean,cov,(3,3))
>>> x.shape
(3, 3, 2)

The following is probably true, given that 0.6 is roughly twice the standard deviation:

>>> print list( (x[0,0,:] - mean) < 0.6 )
[True, True]


numpy.random.RandomState.negative_binomial

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.multivariate_normal

Next topic

numpy.random.RandomState.noncentral_chisquare

numpy.random.RandomState.negative_binomial

RandomState.negative_binomial(n, p, size=None)

Draw samples from a negative_binomial distribution.

Samples are drawn from a negative_Binomial distribution with specified parameters, n trials and p probability of success where n is an integer > 0 and p is in the interval [0, 1].

Parameters:

n : int

Parameter, > 0.

p : float

Parameter, >= 0 and <=1.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : int or ndarray of ints

Drawn samples.

Notes

The probability density for the Negative Binomial distribution is

where n-1 is the number of successes, p is the probability of success, and N+n-1 is the number of trials.

The negative binomial distribution gives the probability of n-1 successes and N failures in N+n-1 trials, and success on the (N+n)th trial.

If one throws a die repeatedly until the third time a “1” appears, then the probability distribution of the number of non-“1”s that appear before the third “1” is a negative binomial distribution.

References

[R153] Weisstein, Eric W. “Negative Binomial Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/NegativeBinomialDistribution.html
[R154] Wikipedia, “Negative binomial distribution”, http://en.wikipedia.org/wiki/Negative_binomial_distribution

Examples

Draw samples from the distribution:

A real world example. A company drills wild-cat oil exploration wells, each with an estimated probability of success of 0.1. What is the probability of having one success for each successive well, that is what is the probability of a single success after drilling 5 wells, after 6 wells, etc.?

>>> s = np.random.negative_binomial(1, 0.1, 100000)
>>> for i in range(1, 11):
...    probability = sum(s<i) / 100000.
...    print i, "wells drilled, probability of one success =", probability


numpy.random.RandomState.noncentral_chisquare

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.negative_binomial

Next topic

numpy.random.RandomState.noncentral_f

numpy.random.RandomState.noncentral_chisquare

RandomState.noncentral_chisquare(df, nonc, size=None)

Draw samples from a noncentral chi-square distribution.

The noncentral [image] distribution is a generalisation of the [image] distribution.

Parameters:

df : int

Degrees of freedom, should be >= 1.

nonc : float

Non-centrality, should be > 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

Notes

The probability density function for the noncentral Chi-square distribution is

where [image] is the Chi-square with q degrees of freedom.

In Delhi (2007), it is noted that the noncentral chi-square is useful in bombing and coverage problems, the probability of killing the point target given by the noncentral chi-squared distribution.

References

[R155] Delhi, M.S. Holla, “On a noncentral chi-square distribution in the analysis of weapon systems effectiveness”, Metrika, Volume 15, Number 1 / December, 1970.
[R156] Wikipedia, “Noncentral chi-square distribution” http://en.wikipedia.org/wiki/Noncentral_chi-square_distribution

Examples

Draw values from the distribution and plot the histogram

>>> import matplotlib.pyplot as plt
>>> values = plt.hist(np.random.noncentral_chisquare(3, 20, 100000),
...                   bins=200, normed=True)
>>> plt.show()

(Source code, png, pdf)

Draw values from a noncentral chisquare with very small noncentrality, and compare to a chisquare.

>>> plt.figure()
>>> values = plt.hist(np.random.noncentral_chisquare(3, .0000001, 100000),
...                   bins=np.arange(0., 25, .1), normed=True)
>>> values2 = plt.hist(np.random.chisquare(3, 100000),
...                    bins=np.arange(0., 25, .1), normed=True)
>>> plt.plot(values[1][0:-1], values[0]-values2[0], 'ob')
>>> plt.show()

(png, pdf)

Demonstrate how large values of non-centrality lead to a more symmetric distribution.

>>> plt.figure()
>>> values = plt.hist(np.random.noncentral_chisquare(3, 20, 100000),
...                   bins=200, normed=True)
>>> plt.show()

(png, pdf)


numpy.random.RandomState.noncentral_f

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.noncentral_chisquare

Next topic

numpy.random.RandomState.normal

numpy.random.RandomState.noncentral_f

RandomState.noncentral_f(dfnum, dfden, nonc, size=None)

Draw samples from the noncentral F distribution.

Samples are drawn from an F distribution with specified parameters, dfnum (degrees of freedom in numerator) and dfden (degrees of freedom in denominator), where both parameters > 1. nonc is the non-centrality parameter.

Parameters:

dfnum : int

Parameter, should be > 1.

dfden : int

Parameter, should be > 1.

nonc : float

Parameter, should be >= 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : scalar or ndarray

Drawn samples.

Notes

When calculating the power of an experiment (power = probability of rejecting the null hypothesis when a specific alternative is true) the non-central F statistic becomes important. When the null hypothesis is true, the F statistic follows a central F distribution. When the null hypothesis is not true, then it follows a non-central F statistic.

References

Weisstein, Eric W. “Noncentral F-Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/NoncentralF-Distribution.html

Wikipedia, “Noncentral F distribution”, http://en.wikipedia.org/wiki/Noncentral_F-distribution

Examples

In a study, testing for a specific alternative to the null hypothesis requires use of the Noncentral F distribution. We need to calculate the area in the tail of the distribution that exceeds the value of the F distribution for the null hypothesis. We’ll plot the two probability distributions for comparison.

>>> dfnum = 3 # between group deg of freedom
>>> dfden = 20 # within groups degrees of freedom
>>> nonc = 3.0
>>> nc_vals = np.random.noncentral_f(dfnum, dfden, nonc, 1000000)
>>> NF = np.histogram(nc_vals, bins=50, normed=True)
>>> c_vals = np.random.f(dfnum, dfden, 1000000)
>>> F = np.histogram(c_vals, bins=50, normed=True)
>>> plt.plot(F[1][1:], F[0])
>>> plt.plot(NF[1][1:], NF[0])
>>> plt.show()


numpy.random.RandomState.normal

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.noncentral_f

Next topic

numpy.random.RandomState.pareto

numpy.random.RandomState.normal

RandomState.normal(loc=0.0, scale=1.0, size=None)

Draw random samples from a normal (Gaussian) distribution.

The probability density function of the normal distribution, first derived by De Moivre and 200 years later by both Gauss and Laplace independently [R158], is often called the bell curve because of its characteristic shape (see the example below).

The normal distributions occurs often in nature. For example, it describes the commonly occurring distribution of samples influenced by a large number of tiny, random disturbances, each with its own unique distribution [R158].

Parameters:

loc : float

Mean (“centre”) of the distribution.

scale : float

Standard deviation (spread or “width”) of the distribution.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

See also

scipy.stats.distributions.norm
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Gaussian distribution is

where [image] is the mean and [image] the standard deviation. The square of the standard deviation, [image], is called the variance.

The function has its peak at the mean, and its “spread” increases with the standard deviation (the function reaches 0.607 times its maximum at [image] and [image] [R158]). This implies that numpy.random.normal is more likely to return samples lying close to the mean, rather than those far away.

References

[R157] Wikipedia, “Normal distribution”, http://en.wikipedia.org/wiki/Normal_distribution
[R158] (1, 2, 3, 4) P. R. Peebles Jr., “Central Limit Theorem” in “Probability, Random Variables and Random Signal Principles”, 4th ed., 2001, pp. 51, 51, 125.

Examples

Draw samples from the distribution:

>>> mu, sigma = 0, 0.1 # mean and standard deviation
>>> s = np.random.normal(mu, sigma, 1000)

Verify the mean and the variance:

>>> abs(mu - np.mean(s)) < 0.01
True

>>> abs(sigma - np.std(s, ddof=1)) < 0.01
True

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 30, normed=True)
>>> plt.plot(bins, 1/(sigma * np.sqrt(2 * np.pi)) *
...                np.exp( - (bins - mu)**2 / (2 * sigma**2) ),
...          linewidth=2, color='r')
>>> plt.show()

(Source code, png, pdf)


numpy.random.RandomState.pareto

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.normal

Next topic

numpy.random.RandomState.permutation

numpy.random.RandomState.pareto

RandomState.pareto(a, size=None)

Draw samples from a Pareto II or Lomax distribution with specified shape.

The Lomax or Pareto II distribution is a shifted Pareto distribution. The classical Pareto distribution can be obtained from the Lomax distribution by adding the location parameter m, see below. The smallest value of the Lomax distribution is zero while for the classical Pareto distribution it is m, where the standard Pareto distribution has location m=1. Lomax can also be considered as a simplified version of the Generalized Pareto distribution (available in SciPy), with the scale set to one and the location set to zero.

The Pareto distribution must be greater than zero, and is unbounded above. It is also known as the “80-20 rule”. In this distribution, 80 percent of the weights are in the lowest 20 percent of the range, while the other 20 percent fill the remaining 80 percent of the range.

Parameters:

shape : float, > 0.

Shape of the distribution.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

See also

scipy.stats.distributions.lomax.pdf
probability density function, distribution or cumulative density function, etc.
scipy.stats.distributions.genpareto.pdf
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Pareto distribution is

where a is the shape and m the location

The Pareto distribution, named after the Italian economist Vilfredo Pareto, is a power law probability distribution useful in many real world problems. Outside the field of economics it is generally referred to as the Bradford distribution. Pareto developed the distribution to describe the distribution of wealth in an economy. It has also found use in insurance, web page access statistics, oil field sizes, and many other problems, including the download frequency for projects in Sourceforge [1]. It is one of the so-called “fat-tailed” distributions.

References

[R159] Francis Hunt and Paul Johnson, On the Pareto Distribution of Sourceforge projects.
[R160] Pareto, V. (1896). Course of Political Economy. Lausanne.
[R161] Reiss, R.D., Thomas, M.(2001), Statistical Analysis of Extreme Values, Birkhauser Verlag, Basel, pp 23-30.
[R162] Wikipedia, “Pareto distribution”, http://en.wikipedia.org/wiki/Pareto_distribution

Examples

Draw samples from the distribution:

>>> a, m = 3., 1. # shape and mode
>>> s = np.random.pareto(a, 1000) + m

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 100, normed=True, align='center')
>>> fit = a*m**a/bins**(a+1)
>>> plt.plot(bins, max(count)*fit/max(fit),linewidth=2, color='r')
>>> plt.show()

(Source code)


numpy.random.RandomState.permutation

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.pareto

Next topic

numpy.random.RandomState.poisson

numpy.random.RandomState.permutation

RandomState.permutation(x)

Randomly permute a sequence, or return a permuted range.

If x is a multi-dimensional array, it is only shuffled along its first index.

Parameters:

x : int or array_like

If x is an integer, randomly permute np.arange(x). If x is an array, make a copy and shuffle the elements randomly.
Returns:

out : ndarray

Permuted sequence or array range.

Examples

>>> np.random.permutation(10)
array([1, 7, 4, 3, 0, 9, 2, 5, 8, 6])

>>> np.random.permutation([1, 4, 9, 12, 15])
array([15,  1,  9,  4, 12])

>>> arr = np.arange(9).reshape((3, 3))
>>> np.random.permutation(arr)
array([[6, 7, 8],
       [0, 1, 2],
       [3, 4, 5]])


numpy.random.RandomState.poisson

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.permutation

Next topic

numpy.random.RandomState.power

numpy.random.RandomState.poisson

RandomState.poisson(lam=1.0, size=None)

Draw samples from a Poisson distribution.

The Poisson distribution is the limit of the Binomial distribution for large N.

Parameters:

lam : float or sequence of float

Expectation of interval, should be >= 0. A sequence of expectation intervals must be broadcastable over the requested size.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

Notes

The Poisson distribution

For events with an expected separation [image] the Poisson distribution [image] describes the probability of k events occurring within the observed interval [image].

Because the output is limited to the range of the C long type, a ValueError is raised when lam is within 10 sigma of the maximum representable value.

References

[R163] Weisstein, Eric W. “Poisson Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/PoissonDistribution.html
[R164] Wikipedia, “Poisson distribution”, http://en.wikipedia.org/wiki/Poisson_distribution

Examples

Draw samples from the distribution:

>>> import numpy as np
>>> s = np.random.poisson(5, 10000)

Display histogram of the sample:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 14, normed=True)
>>> plt.show()

(Source code, png, pdf)

Draw each 100 values for lambda 100 and 500:

>>> s = np.random.poisson(lam=(100., 500.), size=(100, 2))

()


numpy.random.RandomState.power

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.poisson

Next topic

numpy.random.RandomState.rand

numpy.random.RandomState.power

RandomState.power(a, size=None)

Draws samples in [0, 1] from a power distribution with positive exponent a - 1.

Also known as the power function distribution.

Parameters:

a : float

parameter, > 0

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : {ndarray, scalar}

The returned samples lie in [0, 1].
Raises:

ValueError

If a<1.

Notes

The probability density function is

The power function distribution is just the inverse of the Pareto distribution. It may also be seen as a special case of the Beta distribution.

It is used, for example, in modeling the over-reporting of insurance claims.

References

[R165] Christian Kleiber, Samuel Kotz, “Statistical size distributions in economics and actuarial sciences”, Wiley, 2003.
[R166] Heckert, N. A. and Filliben, James J. (2003). NIST Handbook 148: Dataplot Reference Manual, Volume 2: Let Subcommands and Library Functions”, National Institute of Standards and Technology Handbook Series, June 2003. http://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/powpdf.pdf

Examples

Draw samples from the distribution:

>>> a = 5. # shape
>>> samples = 1000
>>> s = np.random.power(a, samples)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, bins=30)
>>> x = np.linspace(0, 1, 100)
>>> y = a*x**(a-1.)
>>> normed_y = samples*np.diff(bins)[0]*y
>>> plt.plot(x, normed_y)
>>> plt.show()

(Source code, png, pdf)

Compare the power function distribution to the inverse of the Pareto.

>>> from scipy import stats
>>> rvs = np.random.power(5, 1000000)
>>> rvsp = np.random.pareto(5, 1000000)
>>> xx = np.linspace(0,1,100)
>>> powpdf = stats.powerlaw.pdf(xx,5)

>>> plt.figure()
>>> plt.hist(rvs, bins=50, normed=True)
>>> plt.plot(xx,powpdf,'r-')
>>> plt.title('np.random.power(5)')

>>> plt.figure()
>>> plt.hist(1./(1.+rvsp), bins=50, normed=True)
>>> plt.plot(xx,powpdf,'r-')
>>> plt.title('inverse of 1 + np.random.pareto(5)')

>>> plt.figure()
>>> plt.hist(1./(1.+rvsp), bins=50, normed=True)
>>> plt.plot(xx,powpdf,'r-')
>>> plt.title('inverse of stats.pareto(5)')

(png, pdf)

(png, pdf)

(png, pdf)


numpy.random.RandomState.rand

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.power

Next topic

numpy.random.RandomState.randint

numpy.random.RandomState.rand

RandomState.rand(d0, d1, ..., dn)

Random values in a given shape.

Create an array of the given shape and propagate it with random samples from a uniform distribution over [0, 1).

Parameters:

d0, d1, ..., dn : int, optional

The dimensions of the returned array, should all be positive. If no argument is given a single Python float is returned.
Returns:

out : ndarray, shape (d0, d1, ..., dn)

Random values.

See also

random

Notes

This is a convenience function. If you want an interface that takes a shape-tuple as the first argument, refer to np.random.random_sample .

Examples

>>> np.random.rand(3,2)
array([[ 0.14022471,  0.96360618],  #random
       [ 0.37601032,  0.25528411],  #random
       [ 0.49313049,  0.94909878]]) #random


numpy.random.RandomState.randint

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.rand

Next topic

numpy.random.RandomState.randn

numpy.random.RandomState.randint

RandomState.randint(low, high=None, size=None)

Return random integers from low (inclusive) to high (exclusive).

Return random integers from the “discrete uniform” distribution in the “half-open” interval [low, high). If high is None (the default), then results are from [0, low).

Parameters:

low : int

Lowest (signed) integer to be drawn from the distribution (unless high=None, in which case this parameter is the highest such integer).

high : int, optional

If provided, one above the largest (signed) integer to be drawn from the distribution (see above for behavior if high=None).

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : int or ndarray of ints

size-shaped array of random integers from the appropriate distribution, or a single such random int if size not provided.

See also

random.random_integers
similar to randint, only for the closed interval [low, high], and 1 is the lowest value if high is omitted. In particular, this other one is the one to use to generate uniformly distributed discrete non-integers.

Examples

>>> np.random.randint(2, size=10)
array([1, 0, 0, 0, 1, 1, 0, 0, 1, 0])
>>> np.random.randint(1, size=10)
array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0])

Generate a 2 x 4 array of ints between 0 and 4, inclusive:

>>> np.random.randint(5, size=(2, 4))
array([[4, 0, 2, 1],
       [3, 2, 2, 0]])


numpy.random.RandomState.randn

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.randint

Next topic

numpy.random.RandomState.random_integers

numpy.random.RandomState.randn

RandomState.randn(d0, d1, ..., dn)

Return a sample (or samples) from the “standard normal” distribution.

If positive, int_like or int-convertible arguments are provided, randn generates an array of shape (d0, d1, ..., dn), filled with random floats sampled from a univariate “normal” (Gaussian) distribution of mean 0 and variance 1 (if any of the [image] are floats, they are first converted to integers by truncation). A single float randomly sampled from the distribution is returned if no argument is provided.

This is a convenience function. If you want an interface that takes a tuple as the first argument, use numpy.random.standard_normal instead.

Parameters:

d0, d1, ..., dn : int, optional

The dimensions of the returned array, should be all positive. If no argument is given a single Python float is returned.
Returns:

Z : ndarray or float

A (d0, d1, ..., dn)-shaped array of floating-point samples from the standard normal distribution, or a single such float if no parameters were supplied.

See also

random.standard_normal
Similar, but takes a tuple as its argument.

Notes

For random samples from [image], use:

sigma * np.random.randn(...) + mu

Examples

>>> np.random.randn()
2.1923875335537315 #random

Two-by-four array of samples from N(3, 6.25):

>>> 2.5 * np.random.randn(2, 4) + 3
array([[-4.49401501,  4.00950034, -1.81814867,  7.29718677],  #random
       [ 0.39924804,  4.68456316,  4.99394529,  4.84057254]]) #random


numpy.random.RandomState.random_integers

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.randn

Next topic

numpy.random.RandomState.random_sample

numpy.random.RandomState.random_integers

RandomState.random_integers(low, high=None, size=None)

Return random integers between low and high, inclusive.

Return random integers from the “discrete uniform” distribution in the closed interval [low, high]. If high is None (the default), then results are from [1, low].

Parameters:

low : int

Lowest (signed) integer to be drawn from the distribution (unless high=None, in which case this parameter is the highest such integer).

high : int, optional

If provided, the largest (signed) integer to be drawn from the distribution (see above for behavior if high=None).

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : int or ndarray of ints

size-shaped array of random integers from the appropriate distribution, or a single such random int if size not provided.

See also

random.randint
Similar to random_integers, only for the half-open interval [low, high), and 0 is the lowest value if high is omitted.

Notes

To sample from N evenly spaced floating-point numbers between a and b, use:

a + (b - a) * (np.random.random_integers(N) - 1) / (N - 1.)

Examples

>>> np.random.random_integers(5)
4
>>> type(np.random.random_integers(5))
<type 'int'>
>>> np.random.random_integers(5, size=(3.,2.))
array([[5, 4],
       [3, 3],
       [4, 5]])

Choose five random numbers from the set of five evenly-spaced numbers between 0 and 2.5, inclusive (i.e., from the set {0, 5/8, 10/8, 15/8, 20/8}):

>>> 2.5 * (np.random.random_integers(5, size=(5,)) - 1) / 4.
array([ 0.625,  1.25 ,  0.625,  0.625,  2.5  ])

Roll two six sided dice 1000 times and sum the results:

>>> d1 = np.random.random_integers(1, 6, 1000)
>>> d2 = np.random.random_integers(1, 6, 1000)
>>> dsums = d1 + d2

Display results as a histogram:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(dsums, 11, normed=True)
>>> plt.show()

(Source code, png, pdf)


numpy.random.RandomState.random_sample

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.random_integers

Next topic

numpy.random.RandomState.rayleigh

numpy.random.RandomState.random_sample

RandomState.random_sample(size=None)

Return random floats in the half-open interval [0.0, 1.0).

Results are from the “continuous uniform” distribution over the stated interval. To sample Unif[a, b), b > a multiply the output of random_sample by (b-a) and add a:

(b - a) * random_sample() + a
Parameters:

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : float or ndarray of floats

Array of random floats of shape size (unless size=None, in which case a single float is returned).

Examples

>>> np.random.random_sample()
0.47108547995356098
>>> type(np.random.random_sample())
<type 'float'>
>>> np.random.random_sample((5,))
array([ 0.30220482,  0.86820401,  0.1654503 ,  0.11659149,  0.54323428])

Three-by-two array of random numbers from [-5, 0):

>>> 5 * np.random.random_sample((3, 2)) - 5
array([[-3.99149989, -0.52338984],
       [-2.99091858, -0.79479508],
       [-1.23204345, -1.75224494]])


numpy.random.RandomState.rayleigh

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.random_sample

Next topic

numpy.random.RandomState.seed

numpy.random.RandomState.rayleigh

RandomState.rayleigh(scale=1.0, size=None)

Draw samples from a Rayleigh distribution.

The [image] and Weibull distributions are generalizations of the Rayleigh.

Parameters:

scale : scalar

Scale, also equals the mode. Should be >= 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

Notes

The probability density function for the Rayleigh distribution is

The Rayleigh distribution arises if the wind speed and wind direction are both gaussian variables, then the vector wind velocity forms a Rayleigh distribution. The Rayleigh distribution is used to model the expected output from wind turbines.

References

[R167] Brighton Webs Ltd., Rayleigh Distribution, http://www.brighton-webs.co.uk/distributions/rayleigh.asp
[R168] Wikipedia, “Rayleigh distribution” http://en.wikipedia.org/wiki/Rayleigh_distribution

Examples

Draw values from the distribution and plot the histogram

>>> values = hist(np.random.rayleigh(3, 100000), bins=200, normed=True)

Wave heights tend to follow a Rayleigh distribution. If the mean wave height is 1 meter, what fraction of waves are likely to be larger than 3 meters?

>>> meanvalue = 1
>>> modevalue = np.sqrt(2 / np.pi) * meanvalue
>>> s = np.random.rayleigh(modevalue, 1000000)

The percentage of waves larger than 3 meters is:

>>> 100.*sum(s>3)/1000000.
0.087300000000000003


numpy.random.RandomState.seed

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.rayleigh

Next topic

numpy.random.RandomState.set_state

numpy.random.RandomState.seed

RandomState.seed(seed=None)

Seed the generator.

This method is called when RandomState is initialized. It can be called again to re-seed the generator. For details, see RandomState.

Parameters:

seed : int or array_like, optional

Seed for RandomState. Must be convertable to 32 bit unsigned integers.

See also

RandomState


numpy.random.RandomState.set_state

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.seed

Next topic

numpy.random.RandomState.shuffle

numpy.random.RandomState.set_state

RandomState.set_state(state)

Set the internal state of the generator from a tuple.

For use if one has reason to manually (re-)set the internal state of the “Mersenne Twister”[R169] pseudo-random number generating algorithm.

Parameters:

state : tuple(str, ndarray of 624 uints, int, int, float)

The state tuple has the following items:

  1. the string ‘MT19937’, specifying the Mersenne Twister algorithm.
  2. a 1-D array of 624 unsigned integers keys.
  3. an integer pos.
  4. an integer has_gauss.
  5. a float cached_gaussian.
Returns:

out : None

Returns ‘None’ on success.

See also

get_state

Notes

set_state and get_state are not needed to work with any of the random distributions in NumPy. If the internal state is manually altered, the user should know exactly what he/she is doing.

For backwards compatibility, the form (str, array of 624 uints, int) is also accepted although it is missing some information about the cached Gaussian value: state = ('MT19937', keys, pos).

References

[R169] (1, 2) M. Matsumoto and T. Nishimura, “Mersenne Twister: A 623-dimensionally equidistributed uniform pseudorandom number generator,” ACM Trans. on Modeling and Computer Simulation, Vol. 8, No. 1, pp. 3-30, Jan. 1998.


numpy.random.RandomState.shuffle

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.set_state

Next topic

numpy.random.RandomState.standard_cauchy

numpy.random.RandomState.shuffle

RandomState.shuffle(x)

Modify a sequence in-place by shuffling its contents.

Parameters:

x : array_like

The array or list to be shuffled.
Returns:

None

Examples

>>> arr = np.arange(10)
>>> np.random.shuffle(arr)
>>> arr
[1 7 5 2 9 4 3 6 0 8]

This function only shuffles the array along the first index of a multi-dimensional array:

>>> arr = np.arange(9).reshape((3, 3))
>>> np.random.shuffle(arr)
>>> arr
array([[3, 4, 5],
       [6, 7, 8],
       [0, 1, 2]])


numpy.random.RandomState.standard_cauchy

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.shuffle

Next topic

numpy.random.RandomState.standard_exponential

numpy.random.RandomState.standard_cauchy

RandomState.standard_cauchy(size=None)

Standard Cauchy distribution with mode = 0.

Also known as the Lorentz distribution.

Parameters:

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : ndarray or scalar

The drawn samples.

Notes

The probability density function for the full Cauchy distribution is

and the Standard Cauchy distribution just sets [image] and

The Cauchy distribution arises in the solution to the driven harmonic oscillator problem, and also describes spectral line broadening. It also describes the distribution of values at which a line tilted at a random angle will cut the x axis.

When studying hypothesis tests that assume normality, seeing how the tests perform on data from a Cauchy distribution is a good indicator of their sensitivity to a heavy-tailed distribution, since the Cauchy looks very much like a Gaussian distribution, but with heavier tails.

References

[R170] NIST/SEMATECH e-Handbook of Statistical Methods, “Cauchy Distribution”, http://www.itl.nist.gov/div898/handbook/eda/section3/eda3663.htm
[R171] Weisstein, Eric W. “Cauchy Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/CauchyDistribution.html
[R172] Wikipedia, “Cauchy distribution” http://en.wikipedia.org/wiki/Cauchy_distribution

Examples

Draw samples and plot the distribution:

>>> s = np.random.standard_cauchy(1000000)
>>> s = s[(s>-25) & (s<25)]  # truncate distribution so it plots well
>>> plt.hist(s, bins=100)
>>> plt.show()


numpy.random.RandomState.standard_exponential

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.standard_cauchy

Next topic

numpy.random.RandomState.standard_gamma

numpy.random.RandomState.standard_exponential

RandomState.standard_exponential(size=None)

Draw samples from the standard exponential distribution.

standard_exponential is identical to the exponential distribution with a scale parameter of 1.

Parameters:

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : float or ndarray

Drawn samples.

Examples

Output a 3x8000 array:

>>> n = np.random.standard_exponential((3, 8000))


numpy.random.RandomState.standard_gamma

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.standard_exponential

Next topic

numpy.random.RandomState.standard_normal

numpy.random.RandomState.standard_gamma

RandomState.standard_gamma(shape, size=None)

Draw samples from a Standard Gamma distribution.

Samples are drawn from a Gamma distribution with specified parameters, shape (sometimes designated “k”) and scale=1.

Parameters:

shape : float

Parameter, should be > 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : ndarray or scalar

The drawn samples.

See also

scipy.stats.distributions.gamma
probability density function, distribution or cumulative density function, etc.

Notes

The probability density for the Gamma distribution is

where k is the shape and [image] the scale, and [image] is the Gamma function.

The Gamma distribution is often used to model the times to failure of electronic components, and arises naturally in processes for which the waiting times between Poisson distributed events are relevant.

References

[R173] Weisstein, Eric W. “Gamma Distribution.” From MathWorld–A Wolfram Web Resource. http://mathworld.wolfram.com/GammaDistribution.html
[R174] Wikipedia, “Gamma-distribution”, http://en.wikipedia.org/wiki/Gamma-distribution

Examples

Draw samples from the distribution:

>>> shape, scale = 2., 1. # mean and width
>>> s = np.random.standard_gamma(shape, 1000000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> import scipy.special as sps
>>> count, bins, ignored = plt.hist(s, 50, normed=True)
>>> y = bins**(shape-1) * ((np.exp(-bins/scale))/ \
...                       (sps.gamma(shape) * scale**shape))
>>> plt.plot(bins, y, linewidth=2, color='r')
>>> plt.show()

(Source code, png, pdf)


numpy.random.RandomState.standard_normal

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.standard_gamma

Next topic

numpy.random.RandomState.standard_t

numpy.random.RandomState.standard_normal

RandomState.standard_normal(size=None)

Returns samples from a Standard Normal distribution (mean=0, stdev=1).

Parameters:

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : float or ndarray

Drawn samples.

Examples

>>> s = np.random.standard_normal(8000)
>>> s
array([ 0.6888893 ,  0.78096262, -0.89086505, ...,  0.49876311, #random
       -0.38672696, -0.4685006 ])                               #random
>>> s.shape
(8000,)
>>> s = np.random.standard_normal(size=(3, 4, 2))
>>> s.shape
(3, 4, 2)


numpy.random.RandomState.standard_t

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.standard_normal

Next topic

numpy.random.RandomState.tomaxint

numpy.random.RandomState.standard_t

RandomState.standard_t(df, size=None)

Standard Student’s t distribution with df degrees of freedom.

A special case of the hyperbolic distribution. As df gets large, the result resembles that of the standard normal distribution (standard_normal).

Parameters:

df : int

Degrees of freedom, should be > 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : ndarray or scalar

Drawn samples.

Notes

The probability density function for the t distribution is

The t test is based on an assumption that the data come from a Normal distribution. The t test provides a way to test whether the sample mean (that is the mean calculated from the data) is a good estimate of the true mean.

The derivation of the t-distribution was forst published in 1908 by William Gisset while working for the Guinness Brewery in Dublin. Due to proprietary issues, he had to publish under a pseudonym, and so he used the name Student.

References

[R175] (1, 2) Dalgaard, Peter, “Introductory Statistics With R”, Springer, 2002.
[R176] Wikipedia, “Student’s t-distribution” http://en.wikipedia.org/wiki/Student’s_t-distribution

Examples

From Dalgaard page 83 [R175], suppose the daily energy intake for 11 women in Kj is:

>>> intake = np.array([5260., 5470, 5640, 6180, 6390, 6515, 6805, 7515, \
...                    7515, 8230, 8770])

Does their energy intake deviate systematically from the recommended value of 7725 kJ?

We have 10 degrees of freedom, so is the sample mean within 95% of the recommended value?

>>> s = np.random.standard_t(10, size=100000)
>>> np.mean(intake)
6753.636363636364
>>> intake.std(ddof=1)
1142.1232221373727

Calculate the t statistic, setting the ddof parameter to the unbiased value so the divisor in the standard deviation will be degrees of freedom, N-1.

>>> t = (np.mean(intake)-7725)/(intake.std(ddof=1)/np.sqrt(len(intake)))
>>> import matplotlib.pyplot as plt
>>> h = plt.hist(s, bins=100, normed=True)

For a one-sided t-test, how far out in the distribution does the t statistic appear?

>>> >>> np.sum(s<t) / float(len(s))
0.0090699999999999999  #random

So the p-value is about 0.009, which says the null hypothesis has a probability of about 99% of being true.

(Source code)


numpy.random.RandomState.tomaxint

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.standard_t

Next topic

numpy.random.RandomState.triangular

numpy.random.RandomState.tomaxint

RandomState.tomaxint(size=None)

Random integers between 0 and sys.maxint, inclusive.

Return a sample of uniformly distributed random integers in the interval [0, sys.maxint].

Parameters:

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : ndarray

Drawn samples, with shape size.

See also

randint
Uniform sampling over a given half-open interval of integers.
random_integers
Uniform sampling over a given closed interval of integers.

Examples

>>> RS = np.random.mtrand.RandomState() # need a RandomState object
>>> RS.tomaxint((2,2,2))
array([[[1170048599, 1600360186],
        [ 739731006, 1947757578]],
       [[1871712945,  752307660],
        [1601631370, 1479324245]]])
>>> import sys
>>> sys.maxint
2147483647
>>> RS.tomaxint((2,2,2)) < sys.maxint
array([[[ True,  True],
        [ True,  True]],
       [[ True,  True],
        [ True,  True]]], dtype=bool)


numpy.random.RandomState.triangular

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.tomaxint

Next topic

numpy.random.RandomState.uniform

numpy.random.RandomState.triangular

RandomState.triangular(left, mode, right, size=None)

Draw samples from the triangular distribution.

The triangular distribution is a continuous probability distribution with lower limit left, peak at mode, and upper limit right. Unlike the other distributions, these parameters directly define the shape of the pdf.

Parameters:

left : scalar

Lower limit.

mode : scalar

The value where the peak of the distribution occurs. The value should fulfill the condition left <= mode <= right.

right : scalar

Upper limit, should be larger than left.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : ndarray or scalar

The returned samples all lie in the interval [left, right].

Notes

The probability density function for the Triangular distribution is

The triangular distribution is often used in ill-defined problems where the underlying distribution is not known, but some knowledge of the limits and mode exists. Often it is used in simulations.

References

[R177] Wikipedia, “Triangular distribution” http://en.wikipedia.org/wiki/Triangular_distribution

Examples

Draw values from the distribution and plot the histogram:

>>> import matplotlib.pyplot as plt
>>> h = plt.hist(np.random.triangular(-3, 0, 8, 100000), bins=200,
...              normed=True)
>>> plt.show()

(Source code, png, pdf)


numpy.random.RandomState.uniform

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.triangular

Next topic

numpy.random.RandomState.vonmises

numpy.random.RandomState.uniform

RandomState.uniform(low=0.0, high=1.0, size=None)

Draw samples from a uniform distribution.

Samples are uniformly distributed over the half-open interval [low, high) (includes low, but excludes high). In other words, any value within the given interval is equally likely to be drawn by uniform.

Parameters:

low : float, optional

Lower boundary of the output interval. All values generated will be greater than or equal to low. The default value is 0.

high : float

Upper boundary of the output interval. All values generated will be less than high. The default value is 1.0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

out : ndarray

Drawn samples, with shape size.

See also

randint
Discrete uniform distribution, yielding integers.
random_integers
Discrete uniform distribution over the closed interval [low, high].
random_sample
Floats uniformly distributed over [0, 1).
random
Alias for random_sample.
rand
Convenience function that accepts dimensions as input, e.g., rand(2,2) would generate a 2-by-2 array of floats, uniformly distributed over [0, 1).

Notes

The probability density function of the uniform distribution is

anywhere within the interval [a, b), and zero elsewhere.

Examples

Draw samples from the distribution:

>>> s = np.random.uniform(-1,0,1000)

All values are within the given interval:

>>> np.all(s >= -1)
True
>>> np.all(s < 0)
True

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 15, normed=True)
>>> plt.plot(bins, np.ones_like(bins), linewidth=2, color='r')
>>> plt.show()

(Source code, png, pdf)


numpy.random.RandomState.vonmises

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.uniform

Next topic

numpy.random.RandomState.wald

numpy.random.RandomState.vonmises

RandomState.vonmises(mu, kappa, size=None)

Draw samples from a von Mises distribution.

Samples are drawn from a von Mises distribution with specified mode (mu) and dispersion (kappa), on the interval [-pi, pi].

The von Mises distribution (also known as the circular normal distribution) is a continuous probability distribution on the unit circle. It may be thought of as the circular analogue of the normal distribution.

Parameters:

mu : float

Mode (“center”) of the distribution.

kappa : float

Dispersion of the distribution, has to be >=0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : scalar or ndarray

The returned samples, which are in the interval [-pi, pi].

See also

scipy.stats.distributions.vonmises
probability density function, distribution, or cumulative density function, etc.

Notes

The probability density for the von Mises distribution is

where [image] is the mode and [image] the dispersion, and [image] is the modified Bessel function of order 0.

The von Mises is named for Richard Edler von Mises, who was born in Austria-Hungary, in what is now the Ukraine. He fled to the United States in 1939 and became a professor at Harvard. He worked in probability theory, aerodynamics, fluid mechanics, and philosophy of science.

References

Abramowitz, M. and Stegun, I. A. (ed.), Handbook of Mathematical Functions, New York: Dover, 1965.

von Mises, R., Mathematical Theory of Probability and Statistics, New York: Academic Press, 1964.

Examples

Draw samples from the distribution:

>>> mu, kappa = 0.0, 4.0 # mean and dispersion
>>> s = np.random.vonmises(mu, kappa, 1000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> import scipy.special as sps
>>> count, bins, ignored = plt.hist(s, 50, normed=True)
>>> x = np.arange(-np.pi, np.pi, 2*np.pi/50.)
>>> y = -np.exp(kappa*np.cos(x-mu))/(2*np.pi*sps.jn(0,kappa))
>>> plt.plot(x, y/max(y), linewidth=2, color='r')
>>> plt.show()

(Source code, png, pdf)


numpy.random.RandomState.wald

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.vonmises

Next topic

numpy.random.RandomState.weibull

numpy.random.RandomState.wald

RandomState.wald(mean, scale, size=None)

Draw samples from a Wald, or Inverse Gaussian, distribution.

As the scale approaches infinity, the distribution becomes more like a Gaussian.

Some references claim that the Wald is an Inverse Gaussian with mean=1, but this is by no means universal.

The Inverse Gaussian distribution was first studied in relationship to Brownian motion. In 1956 M.C.K. Tweedie used the name Inverse Gaussian because there is an inverse relationship between the time to cover a unit distance and distance covered in unit time.

Parameters:

mean : scalar

Distribution mean, should be > 0.

scale : scalar

Scale parameter, should be >= 0.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : ndarray or scalar

Drawn sample, all greater than zero.

Notes

The probability density function for the Wald distribution is

As noted above the Inverse Gaussian distribution first arise from attempts to model Brownian Motion. It is also a competitor to the Weibull for use in reliability modeling and modeling stock returns and interest rate processes.

References

[R178] Brighton Webs Ltd., Wald Distribution, http://www.brighton-webs.co.uk/distributions/wald.asp
[R179] Chhikara, Raj S., and Folks, J. Leroy, “The Inverse Gaussian Distribution: Theory : Methodology, and Applications”, CRC Press, 1988.
[R180] Wikipedia, “Wald distribution” http://en.wikipedia.org/wiki/Wald_distribution

Examples

Draw values from the distribution and plot the histogram:

>>> import matplotlib.pyplot as plt
>>> h = plt.hist(np.random.wald(3, 2, 100000), bins=200, normed=True)
>>> plt.show()

(Source code, png, pdf)


numpy.random.RandomState.weibull

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.wald

Next topic

numpy.random.RandomState.zipf

numpy.random.RandomState.weibull

RandomState.weibull(a, size=None)

Weibull distribution.

Draw samples from a 1-parameter Weibull distribution with the given shape parameter a.

X = (-ln(U))^{1/a}

Here, U is drawn from the uniform distribution over (0,1].

The more common 2-parameter Weibull, including a scale parameter [image] is just [image].

Parameters:

a : float

Shape of the distribution.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.

See also

scipy.stats.distributions.weibull_max, scipy.stats.distributions.weibull_min, scipy.stats.distributions.genextreme, gumbel

Notes

The Weibull (or Type III asymptotic extreme value distribution for smallest values, SEV Type III, or Rosin-Rammler distribution) is one of a class of Generalized Extreme Value (GEV) distributions used in modeling extreme value problems. This class includes the Gumbel and Frechet distributions.

The probability density for the Weibull distribution is

where a is the shape and [image] the scale.

The function has its peak (the mode) at [image].

When a = 1, the Weibull distribution reduces to the exponential distribution.

References

[R181] Waloddi Weibull, Professor, Royal Technical University, Stockholm, 1939 “A Statistical Theory Of The Strength Of Materials”, Ingeniorsvetenskapsakademiens Handlingar Nr 151, 1939, Generalstabens Litografiska Anstalts Forlag, Stockholm.
[R182] Waloddi Weibull, 1951 “A Statistical Distribution Function of Wide Applicability”, Journal Of Applied Mechanics ASME Paper.
[R183] Wikipedia, “Weibull distribution”, http://en.wikipedia.org/wiki/Weibull_distribution

Examples

Draw samples from the distribution:

>>> a = 5. # shape
>>> s = np.random.weibull(a, 1000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> x = np.arange(1,100.)/50.
>>> def weib(x,n,a):
...     return (a / n) * (x / n)**(a - 1) * np.exp(-(x / n)**a)

>>> count, bins, ignored = plt.hist(np.random.weibull(5.,1000))
>>> x = np.arange(1,100.)/50.
>>> scale = count.max()/weib(x, 1., 5.).max()
>>> plt.plot(x, weib(x, 1., 5.)*scale)
>>> plt.show()

(Source code, png, pdf)


numpy.random.RandomState.zipf

  • Random sampling (numpy.random)
  • numpy.random.RandomState
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.weibull

Next topic

numpy.random.seed

numpy.random.RandomState.zipf

RandomState.zipf(a, size=None)

Draw samples from a Zipf distribution.

Samples are drawn from a Zipf distribution with specified parameter a > 1.

The Zipf distribution (also known as the zeta distribution) is a continuous probability distribution that satisfies Zipf’s law: the frequency of an item is inversely proportional to its rank in a frequency table.

Parameters:

a : float > 1

Distribution parameter.

size : int or tuple of ints, optional

Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.
Returns:

samples : scalar or ndarray

The returned samples are greater than or equal to one.

See also

scipy.stats.distributions.zipf
probability density function, distribution, or cumulative density function, etc.

Notes

The probability density for the Zipf distribution is

where [image] is the Riemann Zeta function.

It is named for the American linguist George Kingsley Zipf, who noted that the frequency of any word in a sample of a language is inversely proportional to its rank in the frequency table.

References

Zipf, G. K., Selected Studies of the Principle of Relative Frequency in Language, Cambridge, MA: Harvard Univ. Press, 1932.

Examples

Draw samples from the distribution:

>>> a = 2. # parameter
>>> s = np.random.zipf(a, 1000)

Display the histogram of the samples, along with the probability density function:

>>> import matplotlib.pyplot as plt
>>> import scipy.special as sps
Truncate s values at 50 so plot is interesting
>>> count, bins, ignored = plt.hist(s[s<50], 50, normed=True)
>>> x = np.arange(1., 50.)
>>> y = x**(-a)/sps.zetac(a)
>>> plt.plot(x, y/max(y), linewidth=2, color='r')
>>> plt.show()

(Source code, png, pdf)


numpy.random.seed

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.RandomState.zipf

Next topic

numpy.random.get_state

numpy.random.seed

numpy.random.seed(seed=None)

Seed the generator.

This method is called when RandomState is initialized. It can be called again to re-seed the generator. For details, see RandomState.

Parameters:

seed : int or array_like, optional

Seed for RandomState. Must be convertable to 32 bit unsigned integers.

See also

RandomState


numpy.random.get_state

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.seed

Next topic

numpy.random.set_state

numpy.random.get_state

numpy.random.get_state()

Return a tuple representing the internal state of the generator.

For more details, see set_state.

Returns:

out : tuple(str, ndarray of 624 uints, int, int, float)

The returned tuple has the following items:

  1. the string ‘MT19937’.
  2. a 1-D array of 624 unsigned integer keys.
  3. an integer pos.
  4. an integer has_gauss.
  5. a float cached_gaussian.

See also

set_state

Notes

set_state and get_state are not needed to work with any of the random distributions in NumPy. If the internal state is manually altered, the user should know exactly what he/she is doing.


numpy.random.set_state

  • Random sampling (numpy.random)
  • index
  • next
  • previous

Previous topic

numpy.random.get_state

Next topic

Set routines

numpy.random.set_state

numpy.random.set_state(state)

Set the internal state of the generator from a tuple.

For use if one has reason to manually (re-)set the internal state of the “Mersenne Twister”[R228] pseudo-random number generating algorithm.

Parameters:

state : tuple(str, ndarray of 624 uints, int, int, float)

The state tuple has the following items:

  1. the string ‘MT19937’, specifying the Mersenne Twister algorithm.
  2. a 1-D array of 624 unsigned integers keys.
  3. an integer pos.
  4. an integer has_gauss.
  5. a float cached_gaussian.
Returns:

out : None

Returns ‘None’ on success.

See also

get_state

Notes

set_state and get_state are not needed to work with any of the random distributions in NumPy. If the internal state is manually altered, the user should know exactly what he/she is doing.

For backwards compatibility, the form (str, array of 624 uints, int) is also accepted although it is missing some information about the cached Gaussian value: state = ('MT19937', keys, pos).

References

[R228] (1, 2) M. Matsumoto and T. Nishimura, “Mersenne Twister: A 623-dimensionally equidistributed uniform pseudorandom number generator,” ACM Trans. on Modeling and Computer Simulation, Vol. 8, No. 1, pp. 3-30, Jan. 1998.


Set routines

  • next
  • previous

Table Of Contents

  • Set routines
    • Making proper sets
    • Boolean operations

Previous topic

numpy.random.set_state

Next topic

numpy.unique

Set routines

Making proper sets

unique(ar[, return_index, return_inverse, ...]) Find the unique elements of an array.

Boolean operations

in1d(ar1, ar2[, assume_unique, invert]) | Test whether each element of a 1-D array is also present in a second array.
intersect1d(ar1, ar2[, assume_unique]) | Find the intersection of two arrays.
setdiff1d(ar1, ar2[, assume_unique]) | Find the set difference of two arrays.
setxor1d(ar1, ar2[, assume_unique]) | Find the set exclusive-or of two arrays.
union1d(ar1, ar2) | Find the union of two arrays.


numpy.in1d

  • Set routines
  • next
  • previous

Previous topic

numpy.unique

Next topic

numpy.intersect1d

numpy.in1d

numpy.in1d(ar1, ar2, assume_unique=False, invert=False) [source]

Test whether each element of a 1-D array is also present in a second array.

Returns a boolean array the same length as ar1 that is True where an element of ar1 is in ar2 and False otherwise.

Parameters:

ar1 : (M,) array_like

Input array.

ar2 : array_like

The values against which to test each value of ar1.

assume_unique : bool, optional

If True, the input arrays are both assumed to be unique, which can speed up the calculation. Default is False.

invert : bool, optional

If True, the values in the returned array are inverted (that is, False where an element of ar1 is in ar2 and True otherwise). Default is False. np.in1d(a, b, invert=True) is equivalent to (but is faster than) np.invert(in1d(a, b)).

New in version 1.8.0.
Returns:

in1d : (M,) ndarray, bool

The values ar1[in1d] are in ar2.

See also

numpy.lib.arraysetops
Module with a number of other functions for performing set operations on arrays.

Notes

in1d can be considered as an element-wise function version of the python keyword in, for 1-D sequences. in1d(a, b) is roughly equivalent to np.array([item in b for item in a]).

New in version 1.4.0.

Examples

>>> test = np.array([0, 1, 2, 5, 0])
>>> states = [0, 2]
>>> mask = np.in1d(test, states)
>>> mask
array([ True, False,  True, False,  True], dtype=bool)
>>> test[mask]
array([0, 2, 0])
>>> mask = np.in1d(test, states, invert=True)
>>> mask
array([False,  True, False,  True, False], dtype=bool)
>>> test[mask]
array([1, 5])


numpy.intersect1d

  • Set routines
  • next
  • previous

Previous topic

numpy.in1d

Next topic

numpy.setdiff1d

numpy.intersect1d

numpy.intersect1d(ar1, ar2, assume_unique=False) [source]

Find the intersection of two arrays.

Return the sorted, unique values that are in both of the input arrays.

Parameters:

ar1, ar2 : array_like

Input arrays.

assume_unique : bool

If True, the input arrays are both assumed to be unique, which can speed up the calculation. Default is False.
Returns:

intersect1d : ndarray

Sorted 1D array of common and unique elements.

See also

numpy.lib.arraysetops
Module with a number of other functions for performing set operations on arrays.

Examples

>>> np.intersect1d([1, 3, 4, 3], [3, 1, 2, 1])
array([1, 3])


numpy.setdiff1d

  • Set routines
  • next
  • previous

Previous topic

numpy.intersect1d

Next topic

numpy.setxor1d

numpy.setdiff1d

numpy.setdiff1d(ar1, ar2, assume_unique=False) [source]

Find the set difference of two arrays.

Return the sorted, unique values in ar1 that are not in ar2.

Parameters:

ar1 : array_like

Input array.

ar2 : array_like

Input comparison array.

assume_unique : bool

If True, the input arrays are both assumed to be unique, which can speed up the calculation. Default is False.
Returns:

setdiff1d : ndarray

Sorted 1D array of values in ar1 that are not in ar2.

See also

numpy.lib.arraysetops
Module with a number of other functions for performing set operations on arrays.

Examples

>>> a = np.array([1, 2, 3, 2, 4, 1])
>>> b = np.array([3, 4, 5, 6])
>>> np.setdiff1d(a, b)
array([1, 2])


numpy.setxor1d

  • Set routines
  • next
  • previous

Previous topic

numpy.setdiff1d

Next topic

numpy.union1d

numpy.setxor1d

numpy.setxor1d(ar1, ar2, assume_unique=False) [source]

Find the set exclusive-or of two arrays.

Return the sorted, unique values that are in only one (not both) of the input arrays.

Parameters:

ar1, ar2 : array_like

Input arrays.

assume_unique : bool

If True, the input arrays are both assumed to be unique, which can speed up the calculation. Default is False.
Returns:

setxor1d : ndarray

Sorted 1D array of unique values that are in only one of the input arrays.

Examples

>>> a = np.array([1, 2, 3, 2, 4])
>>> b = np.array([2, 3, 5, 7, 5])
>>> np.setxor1d(a,b)
array([1, 4, 5, 7])


numpy.union1d

  • Set routines
  • next
  • previous

Previous topic

numpy.setxor1d

Next topic

Sorting, searching, and counting

numpy.union1d

numpy.union1d(ar1, ar2) [source]

Find the union of two arrays.

Return the unique, sorted array of values that are in either of the two input arrays.

Parameters:

ar1, ar2 : array_like

Input arrays. They are flattened if they are not already 1D.
Returns:

union1d : ndarray

Unique, sorted union of the input arrays.

See also

numpy.lib.arraysetops
Module with a number of other functions for performing set operations on arrays.

Examples

>>> np.union1d([-1, 0, 1], [-2, 0, 2])
array([-2, -1,  0,  1,  2])


Sorting, searching, and counting

  • next
  • previous

Table Of Contents

  • Sorting, searching, and counting
    • Sorting
    • Searching
    • Counting

Previous topic

numpy.union1d

Next topic

numpy.sort

Sorting, searching, and counting

Sorting

sort(a[, axis, kind, order]) | Return a sorted copy of an array.
lexsort(keys[, axis]) | Perform an indirect sort using a sequence of keys.
argsort(a[, axis, kind, order]) | Returns the indices that would sort an array.
ndarray.sort([axis, kind, order]) | Sort an array, in-place.
msort(a) | Return a copy of an array sorted along the first axis.
sort_complex(a) | Sort a complex array using the real part first, then the imaginary part.
partition(a, kth[, axis, kind, order]) | Return a partitioned copy of an array.
argpartition(a, kth[, axis, kind, order]) | Perform an indirect partition along the given axis using the algorithm specified by the kind keyword.

Searching

argmax(a[, axis]) | Indices of the maximum values along an axis.
nanargmax(a[, axis]) | Return the indices of the maximum values in the specified axis ignoring NaNs.
argmin(a[, axis]) | Return the indices of the minimum values along an axis.
nanargmin(a[, axis]) | Return the indices of the minimum values in the specified axis ignoring NaNs.
argwhere(a) | Find the indices of array elements that are non-zero, grouped by element.
nonzero(a) | Return the indices of the elements that are non-zero.
flatnonzero(a) | Return indices that are non-zero in the flattened version of a.
where(condition, [x, y]) | Return elements, either from x or y, depending on condition.
searchsorted(a, v[, side, sorter]) | Find indices where elements should be inserted to maintain order.
extract(condition, arr) | Return the elements of an array that satisfy some condition.

Counting

count_nonzero(a) Counts the number of non-zero values in the array a.


numpy.sort

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.count_nonzero

Next topic

numpy.lexsort

numpy.sort

numpy.sort(a, axis=-1, kind='quicksort', order=None) [source]

Return a sorted copy of an array.

Parameters:

a : array_like

Array to be sorted.

axis : int or None, optional

Axis along which to sort. If None, the array is flattened before sorting. The default is -1, which sorts along the last axis.

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm. Default is ‘quicksort’.

order : list, optional

When a is a structured array, this argument specifies which fields to compare first, second, and so on. This list does not need to include all of the fields.
Returns:

sorted_array : ndarray

Array of the same type and shape as a.

See also

ndarray.sort
Method to sort an array in-place.
argsort
Indirect sort.
lexsort
Indirect stable sort on multiple keys.
searchsorted
Find elements in a sorted array.
partition
Partial sort.

Notes

The various sorting algorithms are characterized by their average speed, worst case performance, work space size, and whether they are stable. A stable sort keeps items with the same key in the same relative order. The three available algorithms have the following properties:

kind | speed | worst case | work space | stable
‘quicksort’ | 1 | O(n^2) | 0 | no
‘mergesort’ | 2 | O(n*log(n)) | ~n/2 | yes
‘heapsort’ | 3 | O(n*log(n)) | 0 | no

All the sort algorithms make temporary copies of the data when sorting along any but the last axis. Consequently, sorting along the last axis is faster and uses less space than sorting along any other axis.

The sort order for complex numbers is lexicographic. If both the real and imaginary parts are non-nan then the order is determined by the real parts except when they are equal, in which case the order is determined by the imaginary parts.

Previous to numpy 1.4.0 sorting real and complex arrays containing nan values led to undefined behaviour. In numpy versions >= 1.4.0 nan values are sorted to the end. The extended sort order is:

  • Real: [R, nan]
  • Complex: [R + Rj, R + nanj, nan + Rj, nan + nanj]

where R is a non-nan real value. Complex values with the same nan placements are sorted according to the non-nan part if it exists. Non-nan values are sorted as before.

Examples

>>> a = np.array([[1,4],[3,1]])
>>> np.sort(a)                # sort along the last axis
array([[1, 4],
       [1, 3]])
>>> np.sort(a, axis=None)     # sort the flattened array
array([1, 1, 3, 4])
>>> np.sort(a, axis=0)        # sort along the first axis
array([[1, 1],
       [3, 4]])

Use the order keyword to specify a field to use when sorting a structured array:

>>> dtype = [('name', 'S10'), ('height', float), ('age', int)]
>>> values = [('Arthur', 1.8, 41), ('Lancelot', 1.9, 38),
...           ('Galahad', 1.7, 38)]
>>> a = np.array(values, dtype=dtype)       # create a structured array
>>> np.sort(a, order='height')
array([('Galahad', 1.7, 38), ('Arthur', 1.8, 41),
       ('Lancelot', 1.8999999999999999, 38)],
      dtype=[('name', '|S10'), ('height', '<f8'), ('age', '<i4')])

Sort by age, then height if ages are equal:

>>> np.sort(a, order=['age', 'height'])
array([('Galahad', 1.7, 38), ('Lancelot', 1.8999999999999999, 38),
       ('Arthur', 1.8, 41)],
      dtype=[('name', '|S10'), ('height', '<f8'), ('age', '<i4')])


numpy.lexsort

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.sort

Next topic

numpy.argsort

numpy.lexsort

numpy.lexsort(keys, axis=-1)

Perform an indirect sort using a sequence of keys.

Given multiple sorting keys, which can be interpreted as columns in a spreadsheet, lexsort returns an array of integer indices that describes the sort order by multiple columns. The last key in the sequence is used for the primary sort order, the second-to-last key for the secondary sort order, and so on. The keys argument must be a sequence of objects that can be converted to arrays of the same shape. If a 2D array is provided for the keys argument, it’s rows are interpreted as the sorting keys and sorting is according to the last row, second last row etc.

Parameters:

keys : (k, N) array or tuple containing k (N,)-shaped sequences

The k different “columns” to be sorted. The last column (or row if keys is a 2D array) is the primary sort key.

axis : int, optional

Axis to be indirectly sorted. By default, sort over the last axis.
Returns:

indices : (N,) ndarray of ints

Array of indices that sort the keys along the specified axis.

See also

argsort
Indirect sort.
ndarray.sort
In-place sort.
sort
Return a sorted copy of an array.

Examples

Sort names: first by surname, then by name.

>>> surnames =    ('Hertz',    'Galilei', 'Hertz')
>>> first_names = ('Heinrich', 'Galileo', 'Gustav')
>>> ind = np.lexsort((first_names, surnames))
>>> ind
array([1, 2, 0])

>>> [surnames[i] + ", " + first_names[i] for i in ind]
['Galilei, Galileo', 'Hertz, Gustav', 'Hertz, Heinrich']

Sort two columns of numbers:

>>> a = [1,5,1,4,3,4,4] # First column
>>> b = [9,4,0,4,0,2,1] # Second column
>>> ind = np.lexsort((b,a)) # Sort by a, then by b
>>> print ind
[2 0 4 6 5 3 1]

>>> [(a[i],b[i]) for i in ind]
[(1, 0), (1, 9), (3, 0), (4, 1), (4, 2), (4, 4), (5, 4)]

Note that sorting is first according to the elements of a. Secondary sorting is according to the elements of b.

A normal argsort would have yielded:

>>> [(a[i],b[i]) for i in np.argsort(a)]
[(1, 9), (1, 0), (3, 0), (4, 4), (4, 2), (4, 1), (5, 4)]

Structured arrays are sorted lexically by argsort:

>>> x = np.array([(1,9), (5,4), (1,0), (4,4), (3,0), (4,2), (4,1)],
...              dtype=np.dtype([('x', int), ('y', int)]))

>>> np.argsort(x) # or np.argsort(x, order=('x', 'y'))
array([2, 0, 4, 6, 5, 3, 1])


numpy.argsort

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.lexsort

Next topic

numpy.ndarray.sort

numpy.argsort

numpy.argsort(a, axis=-1, kind='quicksort', order=None) [source]

Returns the indices that would sort an array.

Perform an indirect sort along the given axis using the algorithm specified by the kind keyword. It returns an array of indices of the same shape as a that index data along the given axis in sorted order.

Parameters:

a : array_like

Array to sort.

axis : int or None, optional

Axis along which to sort. The default is -1 (the last axis). If None, the flattened array is used.

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.
Returns:

index_array : ndarray, int

Array of indices that sort a along the specified axis. In other words, a[index_array] yields a sorted a.

See also

sort
Describes sorting algorithms used.
lexsort
Indirect stable sort with multiple keys.
ndarray.sort
Inplace sort.
argpartition
Indirect partial sort.

Notes

See sort for notes on the different sorting algorithms.

As of NumPy 1.4.0 argsort works with real/complex arrays containing nan values. The enhanced sort order is documented in sort.

Examples

One dimensional array:

>>> x = np.array([3, 1, 2])
>>> np.argsort(x)
array([1, 2, 0])

Two-dimensional array:

>>> x = np.array([[0, 3], [2, 2]])
>>> x
array([[0, 3],
       [2, 2]])

>>> np.argsort(x, axis=0)
array([[0, 1],
       [1, 0]])

>>> np.argsort(x, axis=1)
array([[0, 1],
       [0, 1]])

Sorting with keys:

>>> x = np.array([(1, 0), (0, 1)], dtype=[('x', '<i4'), ('y', '<i4')])
>>> x
array([(1, 0), (0, 1)],
      dtype=[('x', '<i4'), ('y', '<i4')])

>>> np.argsort(x, order=('x','y'))
array([1, 0])

>>> np.argsort(x, order=('y','x'))
array([0, 1])


numpy.msort

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.ndarray.sort

Next topic

numpy.sort_complex

numpy.msort

numpy.msort(a) [source]

Return a copy of an array sorted along the first axis.

Parameters:

a : array_like

Array to be sorted.
Returns:

sorted_array : ndarray

Array of the same type and shape as a.

See also

sort

Notes

np.msort(a) is equivalent to np.sort(a, axis=0).


numpy.sort_complex

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.msort

Next topic

numpy.partition

numpy.sort_complex

numpy.sort_complex(a) [source]

Sort a complex array using the real part first, then the imaginary part.

Parameters:

a : array_like

Input array
Returns:

out : complex ndarray

Always returns a sorted complex array.

Examples

>>> np.sort_complex([5, 3, 6, 2, 1])
array([ 1.+0.j,  2.+0.j,  3.+0.j,  5.+0.j,  6.+0.j])

>>> np.sort_complex([1 + 2j, 2 - 1j, 3 - 2j, 3 - 3j, 3 + 5j])
array([ 1.+2.j,  2.-1.j,  3.-3.j,  3.-2.j,  3.+5.j])


numpy.partition

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.sort_complex

Next topic

numpy.argpartition

numpy.partition

numpy.partition(a, kth, axis=-1, kind='introselect', order=None) [source]

Return a partitioned copy of an array.

Creates a copy of the array with its elements rearranged in such a way that the value of the element in kth position is in the position it would be in a sorted array. All elements smaller than the kth element are moved before this element and all equal or greater are moved behind it. The ordering of the elements in the two partitions is undefined.

New in version 1.8.0.

Parameters:

a : array_like

Array to be sorted.

kth : int or sequence of ints

Element index to partition by. The kth value of the element will be in its final sorted position and all smaller elements will be moved before it and all equal or greater elements behind it. The order all elements in the partitions is undefined. If provided with a sequence of kth it will partition all elements indexed by kth of them into their sorted position at once.

axis : int or None, optional

Axis along which to sort. If None, the array is flattened before sorting. The default is -1, which sorts along the last axis.

kind : {‘introselect’}, optional

Selection algorithm. Default is ‘introselect’.

order : list, optional

When a is a structured array, this argument specifies which fields to compare first, second, and so on. This list does not need to include all of the fields.
Returns:

partitioned_array : ndarray

Array of the same type and shape as a.

See also

ndarray.partition
Method to sort an array in-place.
argpartition
Indirect partition.
sort
Full sorting

Notes

The various selection algorithms are characterized by their average speed, worst case performance, work space size, and whether they are stable. A stable sort keeps items with the same key in the same relative order. The available algorithms have the following properties:

kind | speed | worst case | work space | stable
‘introselect’ | 1 | O(n) | 0 | no

All the partition algorithms make temporary copies of the data when partitioning along any but the last axis. Consequently, partitioning along the last axis is faster and uses less space than partitioning along any other axis.

The sort order for complex numbers is lexicographic. If both the real and imaginary parts are non-nan then the order is determined by the real parts except when they are equal, in which case the order is determined by the imaginary parts.

Examples

>>> a = np.array([3, 4, 2, 1])
>>> np.partition(a, 3)
array([2, 1, 3, 4])

>>> np.partition(a, (1, 3))
array([1, 2, 3, 4])


numpy.argpartition

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.partition

Next topic

numpy.argmax

numpy.argpartition

numpy.argpartition(a, kth, axis=-1, kind='introselect', order=None) [source]

Perform an indirect partition along the given axis using the algorithm specified by the kind keyword. It returns an array of indices of the same shape as a that index data along the given axis in partitioned order.

New in version 1.8.0.

Parameters:

a : array_like

Array to sort.

kth : int or sequence of ints

Element index to partition by. The kth element will be in its final sorted position and all smaller elements will be moved before it and all larger elements behind it. The order all elements in the partitions is undefined. If provided with a sequence of kth it will partition all of them into their sorted position at once.

axis : int or None, optional

Axis along which to sort. The default is -1 (the last axis). If None, the flattened array is used.

kind : {‘introselect’}, optional

Selection algorithm. Default is ‘introselect’

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.
Returns:

index_array : ndarray, int

Array of indices that partition a along the specified axis. In other words, a[index_array] yields a sorted a.

See also

partition
Describes partition algorithms used.
ndarray.partition
Inplace partition.
argsort
Full indirect sort

Notes

See partition for notes on the different selection algorithms.

Examples

One dimensional array:

>>> x = np.array([3, 4, 2, 1])
>>> x[np.argpartition(x, 3)]
array([2, 1, 3, 4])
>>> x[np.argpartition(x, (1, 3))]
array([1, 2, 3, 4])


numpy.argmax

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.argpartition

Next topic

numpy.nanargmax

numpy.argmax

numpy.argmax(a, axis=None) [source]

Indices of the maximum values along an axis.

Parameters:

a : array_like

Input array.

axis : int, optional

By default, the index is into the flattened array, otherwise along the specified axis.
Returns:

index_array : ndarray of ints

Array of indices into the array. It has the same shape as a.shape with the dimension along axis removed.

See also

ndarray.argmax, argmin

amax
The maximum value along a given axis.
unravel_index
Convert a flat index into an index tuple.

Notes

In case of multiple occurrences of the maximum values, the indices corresponding to the first occurrence are returned.

Examples

>>> a = np.arange(6).reshape(2,3)
>>> a
array([[0, 1, 2],
       [3, 4, 5]])
>>> np.argmax(a)
5
>>> np.argmax(a, axis=0)
array([1, 1, 1])
>>> np.argmax(a, axis=1)
array([2, 2])

>>> b = np.arange(6)
>>> b[1] = 5
>>> b
array([0, 5, 2, 3, 4, 5])
>>> np.argmax(b) # Only the first occurrence is returned.
1


numpy.nanargmax

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.argmax

Next topic

numpy.argmin

numpy.nanargmax

numpy.nanargmax(a, axis=None) [source]

Return the indices of the maximum values in the specified axis ignoring NaNs. For all-NaN slices ValueError is raised. Warning: the results cannot be trusted if a slice contains only NaNs and -Infs.

Parameters:

a : array_like

Input data.

axis : int, optional

Axis along which to operate. By default flattened input is used.
Returns:

index_array : ndarray

An array of indices or a single index value.

See also

argmax, nanargmin

Examples

>>> a = np.array([[np.nan, 4], [2, 3]])
>>> np.argmax(a)
0
>>> np.nanargmax(a)
1
>>> np.nanargmax(a, axis=0)
array([1, 0])
>>> np.nanargmax(a, axis=1)
array([1, 1])


numpy.argmin

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.nanargmax

Next topic

numpy.nanargmin

numpy.argmin

numpy.argmin(a, axis=None) [source]

Return the indices of the minimum values along an axis.

See also

argmax
Similar function. Please refer to numpy.argmax for detailed documentation.


numpy.nanargmin

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.argmin

Next topic

numpy.argwhere

numpy.nanargmin

numpy.nanargmin(a, axis=None) [source]

Return the indices of the minimum values in the specified axis ignoring NaNs. For all-NaN slices ValueError is raised. Warning: the results cannot be trusted if a slice contains only NaNs and Infs.

Parameters:

a : array_like

Input data.

axis : int, optional

Axis along which to operate. By default flattened input is used.
Returns:

index_array : ndarray

An array of indices or a single index value.

See also

argmin, nanargmax

Examples

>>> a = np.array([[np.nan, 4], [2, 3]])
>>> np.argmin(a)
0
>>> np.nanargmin(a)
2
>>> np.nanargmin(a, axis=0)
array([1, 1])
>>> np.nanargmin(a, axis=1)
array([1, 0])


numpy.argwhere

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.nanargmin

Next topic

numpy.nonzero

numpy.argwhere

numpy.argwhere(a) [source]

Find the indices of array elements that are non-zero, grouped by element.

Parameters:

a : array_like

Input data.
Returns:

index_array : ndarray

Indices of elements that are non-zero. Indices are grouped by element.

See also

where, nonzero

Notes

np.argwhere(a) is the same as np.transpose(np.nonzero(a)).

The output of argwhere is not suitable for indexing arrays. For this purpose use where(a) instead.

Examples

>>> x = np.arange(6).reshape(2,3)
>>> x
array([[0, 1, 2],
       [3, 4, 5]])
>>> np.argwhere(x>1)
array([[0, 2],
       [1, 0],
       [1, 1],
       [1, 2]])


numpy.flatnonzero

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.nonzero

Next topic

numpy.where

numpy.flatnonzero

numpy.flatnonzero(a) [source]

Return indices that are non-zero in the flattened version of a.

This is equivalent to a.ravel().nonzero()[0].

Parameters:

a : ndarray

Input array.
Returns:

res : ndarray

Output array, containing the indices of the elements of a.ravel() that are non-zero.

See also

nonzero
Return the indices of the non-zero elements of the input array.
ravel
Return a 1-D array containing the elements of the input array.

Examples

>>> x = np.arange(-2, 3)
>>> x
array([-2, -1,  0,  1,  2])
>>> np.flatnonzero(x)
array([0, 1, 3, 4])

Use the indices of the non-zero elements as an index array to extract these elements:

>>> x.ravel()[np.flatnonzero(x)]
array([-2, -1,  1,  2])


numpy.searchsorted

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.where

Next topic

numpy.extract

numpy.searchsorted

numpy.searchsorted(a, v, side='left', sorter=None) [source]

Find indices where elements should be inserted to maintain order.

Find the indices into a sorted array a such that, if the corresponding elements in v were inserted before the indices, the order of a would be preserved.

Parameters:

a : 1-D array_like

Input array. If sorter is None, then it must be sorted in ascending order, otherwise sorter must be an array of indices that sort it.

v : array_like

Values to insert into a.

side : {‘left’, ‘right’}, optional

If ‘left’, the index of the first suitable location found is given. If ‘right’, return the last such index. If there is no suitable index, return either 0 or N (where N is the length of a).

sorter : 1-D array_like, optional

New in version 1.7.0.

Optional array of integer indices that sort array a into ascending order. They are typically the result of argsort.
Returns:

indices : array of ints

Array of insertion points with the same shape as v.

See also

sort
Return a sorted copy of an array.
histogram
Produce histogram from 1-D data.

Notes

Binary search is used to find the required insertion points.

As of Numpy 1.4.0 searchsorted works with real/complex arrays containing nan values. The enhanced sort order is documented in sort.

Examples

>>> np.searchsorted([1,2,3,4,5], 3)
2
>>> np.searchsorted([1,2,3,4,5], 3, side='right')
3
>>> np.searchsorted([1,2,3,4,5], [-10, 10, 2, 3])
array([0, 5, 1, 2])


numpy.extract

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.searchsorted

Next topic

numpy.count_nonzero

numpy.extract

numpy.extract(condition, arr) [source]

Return the elements of an array that satisfy some condition.

This is equivalent to np.compress(ravel(condition), ravel(arr)). If condition is boolean np.extract is equivalent to arr[condition].

Parameters:

condition : array_like

An array whose nonzero or True entries indicate the elements of arr to extract.

arr : array_like

Input array of the same size as condition.
Returns:

extract : ndarray

Rank 1 array of values from arr where condition is True.

See also

take, put, copyto, compress

Examples

>>> arr = np.arange(12).reshape((3, 4))
>>> arr
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]])
>>> condition = np.mod(arr, 3)==0
>>> condition
array([[ True, False, False,  True],
       [False, False,  True, False],
       [False,  True, False, False]], dtype=bool)
>>> np.extract(condition, arr)
array([0, 3, 6, 9])

If condition is boolean:

>>> arr[condition]
array([0, 3, 6, 9])


numpy.count_nonzero

  • Sorting, searching, and counting
  • next
  • previous

Previous topic

numpy.extract

Next topic

Statistics

numpy.count_nonzero

numpy.count_nonzero(a)

Counts the number of non-zero values in the array a.

Parameters:

a : array_like

The array for which to count non-zeros.
Returns:

count : int or array of int

Number of non-zero values in the array.

See also

nonzero
Return the coordinates of all the non-zero values.

Examples

>>> np.count_nonzero(np.eye(4))
4
>>> np.count_nonzero([[0,1,7,0,0],[3,0,0,2,19]])
5


Statistics

  • next
  • previous

Table Of Contents

  • Statistics
    • Order statistics
    • Averages and variances
    • Correlating
    • Histograms

Previous topic

numpy.count_nonzero

Next topic

numpy.amin

Statistics

Order statistics

amin(a[, axis, out, keepdims]) | Return the minimum of an array or minimum along an axis.
amax(a[, axis, out, keepdims]) | Return the maximum of an array or maximum along an axis.
nanmin(a[, axis, out, keepdims]) | Return minimum of an array or minimum along an axis, ignoring any NaNs.
nanmax(a[, axis, out, keepdims]) | Return the maximum of an array or maximum along an axis, ignoring any NaNs.
ptp(a[, axis, out]) | Range of values (maximum - minimum) along an axis.
percentile(a, q[, axis, out, ...]) | Compute the qth percentile of the data along the specified axis.

Averages and variances

median(a[, axis, out, overwrite_input, keepdims]) | Compute the median along the specified axis.
average(a[, axis, weights, returned]) | Compute the weighted average along the specified axis.
mean(a[, axis, dtype, out, keepdims]) | Compute the arithmetic mean along the specified axis.
std(a[, axis, dtype, out, ddof, keepdims]) | Compute the standard deviation along the specified axis.
var(a[, axis, dtype, out, ddof, keepdims]) | Compute the variance along the specified axis.
nanmean(a[, axis, dtype, out, keepdims]) | Compute the arithmetic mean along the specified axis, ignoring NaNs.
nanstd(a[, axis, dtype, out, ddof, keepdims]) | Compute the standard deviation along the specified axis, while ignoring NaNs.
nanvar(a[, axis, dtype, out, ddof, keepdims]) | Compute the variance along the specified axis, while ignoring NaNs.

Correlating

corrcoef(x[, y, rowvar, bias, ddof]) | Return correlation coefficients.
correlate(a, v[, mode, old_behavior]) | Cross-correlation of two 1-dimensional sequences.
cov(m[, y, rowvar, bias, ddof]) | Estimate a covariance matrix, given data.

Histograms

histogram(a[, bins, range, normed, weights, ...]) | Compute the histogram of a set of data.
histogram2d(x, y[, bins, range, normed, weights]) | Compute the bi-dimensional histogram of two data samples.
histogramdd(sample[, bins, range, normed, ...]) | Compute the multidimensional histogram of some data.
bincount(x[, weights, minlength]) | Count number of occurrences of each value in array of non-negative ints.
digitize(x, bins[, right]) | Return the indices of the bins to which each value in input array belongs.


numpy.amin

  • Statistics
  • next
  • previous

Previous topic

numpy.digitize

Next topic

numpy.amax

numpy.amin

numpy.amin(a, axis=None, out=None, keepdims=False) [source]

Return the minimum of an array or minimum along an axis.

Parameters:

a : array_like

Input data.

axis : int, optional

Axis along which to operate. By default, flattened input is used.

out : ndarray, optional

Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output. See doc.ufuncs (Section “Output arguments”) for more details.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

amin : ndarray or scalar

Minimum of a. If axis is None, the result is a scalar value. If axis is given, the result is an array of dimension a.ndim - 1.

See also

amax
The maximum value of an array along a given axis, propagating any NaNs.
nanmin
The minimum value of an array along a given axis, ignoring any NaNs.
minimum
Element-wise minimum of two arrays, propagating any NaNs.
fmin
Element-wise minimum of two arrays, ignoring any NaNs.
argmin
Return the indices of the minimum values.

nanmax, maximum, fmax

Notes

NaN values are propagated, that is if at least one item is NaN, the corresponding min value will be NaN as well. To ignore NaN values (MATLAB behavior), please use nanmin.

Don’t use amin for element-wise comparison of 2 arrays; when a.shape[0] is 2, minimum(a[0], a[1]) is faster than amin(a, axis=0).

Examples

>>> a = np.arange(4).reshape((2,2))
>>> a
array([[0, 1],
       [2, 3]])
>>> np.amin(a)           # Minimum of the flattened array
0
>>> np.amin(a, axis=0)   # Minima along the first axis
array([0, 1])
>>> np.amin(a, axis=1)   # Minima along the second axis
array([0, 2])

>>> b = np.arange(5, dtype=np.float)
>>> b[2] = np.NaN
>>> np.amin(b)
nan
>>> np.nanmin(b)
0.0


numpy.amax

  • Statistics
  • next
  • previous

Previous topic

numpy.amin

Next topic

numpy.nanmin

numpy.amax

numpy.amax(a, axis=None, out=None, keepdims=False) [source]

Return the maximum of an array or maximum along an axis.

Parameters:

a : array_like

Input data.

axis : int, optional

Axis along which to operate. By default, flattened input is used.

out : ndarray, optional

Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output. See doc.ufuncs (Section “Output arguments”) for more details.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

amax : ndarray or scalar

Maximum of a. If axis is None, the result is a scalar value. If axis is given, the result is an array of dimension a.ndim - 1.

See also

amin
The minimum value of an array along a given axis, propagating any NaNs.
nanmax
The maximum value of an array along a given axis, ignoring any NaNs.
maximum
Element-wise maximum of two arrays, propagating any NaNs.
fmax
Element-wise maximum of two arrays, ignoring any NaNs.
argmax
Return the indices of the maximum values.

nanmin, minimum, fmin

Notes

NaN values are propagated, that is if at least one item is NaN, the corresponding max value will be NaN as well. To ignore NaN values (MATLAB behavior), please use nanmax.

Don’t use amax for element-wise comparison of 2 arrays; when a.shape[0] is 2, maximum(a[0], a[1]) is faster than amax(a, axis=0).

Examples

>>> a = np.arange(4).reshape((2,2))
>>> a
array([[0, 1],
       [2, 3]])
>>> np.amax(a)           # Maximum of the flattened array
3
>>> np.amax(a, axis=0)   # Maxima along the first axis
array([2, 3])
>>> np.amax(a, axis=1)   # Maxima along the second axis
array([1, 3])

>>> b = np.arange(5, dtype=np.float)
>>> b[2] = np.NaN
>>> np.amax(b)
nan
>>> np.nanmax(b)
4.0


numpy.nanmin

  • Statistics
  • next
  • previous

Previous topic

numpy.amax

Next topic

numpy.nanmax

numpy.nanmin

numpy.nanmin(a, axis=None, out=None, keepdims=False) [source]

Return minimum of an array or minimum along an axis, ignoring any NaNs. When all-NaN slices are encountered a RuntimeWarning is raised and Nan is returned for that slice.

Parameters:

a : array_like

Array containing numbers whose minimum is desired. If a is not an array, a conversion is attempted.

axis : int, optional

Axis along which the minimum is computed. The default is to compute the minimum of the flattened array.

out : ndarray, optional

Alternate output array in which to place the result. The default is None; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. See doc.ufuncs for details.

New in version 1.8.0.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original a.

New in version 1.8.0.
Returns:

nanmin : ndarray

An array with the same shape as a, with the specified axis removed. If a is a 0-d array, or if axis is None, an ndarray scalar is returned. The same dtype as a is returned.

See also

nanmax
The maximum value of an array along a given axis, ignoring any NaNs.
amin
The minimum value of an array along a given axis, propagating any NaNs.
fmin
Element-wise minimum of two arrays, ignoring any NaNs.
minimum
Element-wise minimum of two arrays, propagating any NaNs.
isnan
Shows which elements are Not a Number (NaN).
isfinite
Shows which elements are neither NaN nor infinity.

amax, fmax, maximum

Notes

Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). This means that Not a Number is not equivalent to infinity. Positive infinity is treated as a very large number and negative infinity is treated as a very small (i.e. negative) number.

If the input has a integer type the function is equivalent to np.min.

Examples

>>> a = np.array([[1, 2], [3, np.nan]])
>>> np.nanmin(a)
1.0
>>> np.nanmin(a, axis=0)
array([ 1.,  2.])
>>> np.nanmin(a, axis=1)
array([ 1.,  3.])

When positive infinity and negative infinity are present:

>>> np.nanmin([1, 2, np.nan, np.inf])
1.0
>>> np.nanmin([1, 2, np.nan, np.NINF])
-inf


numpy.nanmax

  • Statistics
  • next
  • previous

Previous topic

numpy.nanmin

Next topic

numpy.ptp

numpy.nanmax

numpy.nanmax(a, axis=None, out=None, keepdims=False) [source]

Return the maximum of an array or maximum along an axis, ignoring any NaNs. When all-NaN slices are encountered a RuntimeWarning is raised and NaN is returned for that slice.

Parameters:

a : array_like

Array containing numbers whose maximum is desired. If a is not an array, a conversion is attempted.

axis : int, optional

Axis along which the maximum is computed. The default is to compute the maximum of the flattened array.

out : ndarray, optional

Alternate output array in which to place the result. The default is None; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. See doc.ufuncs for details.

New in version 1.8.0.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original a.

New in version 1.8.0.
Returns:

nanmax : ndarray

An array with the same shape as a, with the specified axis removed. If a is a 0-d array, or if axis is None, an ndarray scalar is returned. The same dtype as a is returned.

See also

nanmin
The minimum value of an array along a given axis, ignoring any NaNs.
amax
The maximum value of an array along a given axis, propagating any NaNs.
fmax
Element-wise maximum of two arrays, ignoring any NaNs.
maximum
Element-wise maximum of two arrays, propagating any NaNs.
isnan
Shows which elements are Not a Number (NaN).
isfinite
Shows which elements are neither NaN nor infinity.

amin, fmin, minimum

Notes

Numpy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). This means that Not a Number is not equivalent to infinity. Positive infinity is treated as a very large number and negative infinity is treated as a very small (i.e. negative) number.

If the input has a integer type the function is equivalent to np.max.

Examples

>>> a = np.array([[1, 2], [3, np.nan]])
>>> np.nanmax(a)
3.0
>>> np.nanmax(a, axis=0)
array([ 3.,  2.])
>>> np.nanmax(a, axis=1)
array([ 2.,  3.])

When positive infinity and negative infinity are present:

>>> np.nanmax([1, 2, np.nan, np.NINF])
2.0
>>> np.nanmax([1, 2, np.nan, np.inf])
inf


numpy.ptp

  • Statistics
  • next
  • previous

Previous topic

numpy.nanmax

Next topic

numpy.percentile

numpy.ptp

numpy.ptp(a, axis=None, out=None) [source]

Range of values (maximum - minimum) along an axis.

The name of the function comes from the acronym for ‘peak to peak’.

Parameters:

a : array_like

Input values.

axis : int, optional

Axis along which to find the peaks. By default, flatten the array.

out : array_like

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type of the output values will be cast if necessary.
Returns:

ptp : ndarray

A new array holding the result, unless out was specified, in which case a reference to out is returned.

Examples

>>> x = np.arange(4).reshape((2,2))
>>> x
array([[0, 1],
       [2, 3]])

>>> np.ptp(x, axis=0)
array([2, 2])

>>> np.ptp(x, axis=1)
array([1, 1])


numpy.percentile

  • Statistics
  • next
  • previous

Previous topic

numpy.ptp

Next topic

numpy.median

numpy.percentile

numpy.percentile(a, q, axis=None, out=None, overwrite_input=False, interpolation='linear', keepdims=False) [source]

Compute the qth percentile of the data along the specified axis.

Returns the qth percentile of the array elements.

Parameters:

a : array_like

Input array or object that can be converted to an array.

q : float in range of [0,100] (or sequence of floats)

Percentile to compute which must be between 0 and 100 inclusive.

axis : int or sequence of int, optional

Axis along which the percentiles are computed. The default (None) is to compute the percentiles along a flattened version of the array. A sequence of axes is supported since version 1.9.0.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type (of the output) will be cast if necessary.

overwrite_input : bool, optional

If True, then allow use of memory of input array a for calculations. The input array will be modified by the call to percentile. This will save memory when you do not need to preserve the contents of the input array. In this case you should not make any assumptions about the content of the passed in array a after this function completes – treat it as undefined. Default is False. Note that, if the a input is not already an array this parameter will have no effect, a will be converted to an array internally regardless of the value of this parameter.

interpolation : {‘linear’, ‘lower’, ‘higher’, ‘midpoint’, ‘nearest’}

This optional parameter specifies the interpolation method to use, when the desired quantile lies between two data points i and j:

  • linear: i + (j - i) * fraction, where fraction is the fractional part of the index surrounded by i and j.
  • lower: i.
  • higher: j.
  • nearest: i or j whichever is nearest.
  • midpoint: (i + j) / 2.

New in version 1.9.0.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.

New in version 1.9.0.
Returns:

percentile : scalar or ndarray

If a single percentile q is given and axis=None a scalar is returned. If multiple percentiles q are given an array holding the result is returned. The results are listed in the first axis. (If out is specified, in which case that array is returned instead). If the input contains integers, or floats of smaller precision than 64, then the output data-type is float64. Otherwise, the output data-type is the same as that of the input.

See also

mean, median

Notes

Given a vector V of length N, the q-th percentile of V is the q-th ranked value in a sorted copy of V. The values and distances of the two nearest neighbors as well as the interpolation parameter will determine the percentile if the normalized ranking does not match q exactly. This function is the same as the median if q=50, the same as the minimum if q=0 and the same as the maximum if q=100.

Examples

>>> a = np.array([[10, 7, 4], [3, 2, 1]])
>>> a
array([[10,  7,  4],
       [ 3,  2,  1]])
>>> np.percentile(a, 50)
array([ 3.5])
>>> np.percentile(a, 50, axis=0)
array([[ 6.5,  4.5,  2.5]])
>>> np.percentile(a, 50, axis=1)
array([[ 7.],
       [ 2.]])

>>> m = np.percentile(a, 50, axis=0)
>>> out = np.zeros_like(m)
>>> np.percentile(a, 50, axis=0, out=m)
array([[ 6.5,  4.5,  2.5]])
>>> m
array([[ 6.5,  4.5,  2.5]])

>>> b = a.copy()
>>> np.percentile(b, 50, axis=1, overwrite_input=True)
array([[ 7.],
       [ 2.]])
>>> assert not np.all(a==b)
>>> b = a.copy()
>>> np.percentile(b, 50, axis=None, overwrite_input=True)
array([ 3.5])


numpy.median

  • Statistics
  • next
  • previous

Previous topic

numpy.percentile

Next topic

numpy.average

numpy.median

numpy.median(a, axis=None, out=None, overwrite_input=False, keepdims=False) [source]

Compute the median along the specified axis.

Returns the median of the array elements.

Parameters:

a : array_like

Input array or object that can be converted to an array.

axis : int or sequence of int, optional

Axis along which the medians are computed. The default (axis=None) is to compute the median along a flattened version of the array. A sequence of axes is supported since version 1.9.0.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type (of the output) will be cast if necessary.

overwrite_input : bool, optional

If True, then allow use of memory of input array (a) for calculations. The input array will be modified by the call to median. This will save memory when you do not need to preserve the contents of the input array. Treat the input as undefined, but it will probably be fully or partially sorted. Default is False. Note that, if overwrite_input is True and the input is not already an ndarray, an error will be raised.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.

New in version 1.9.0.
Returns:

median : ndarray

A new array holding the result (unless out is specified, in which case that array is returned instead). If the input contains integers, or floats of smaller precision than 64, then the output data-type is float64. Otherwise, the output data-type is the same as that of the input.

See also

mean, percentile

Notes

Given a vector V of length N, the median of V is the middle value of a sorted copy of V, V_sorted - i.e., V_sorted[(N-1)/2], when N is odd. When N is even, it is the average of the two middle values of V_sorted.

Examples

>>> a = np.array([[10, 7, 4], [3, 2, 1]])
>>> a
array([[10,  7,  4],
       [ 3,  2,  1]])
>>> np.median(a)
3.5
>>> np.median(a, axis=0)
array([ 6.5,  4.5,  2.5])
>>> np.median(a, axis=1)
array([ 7.,  2.])
>>> m = np.median(a, axis=0)
>>> out = np.zeros_like(m)
>>> np.median(a, axis=0, out=m)
array([ 6.5,  4.5,  2.5])
>>> m
array([ 6.5,  4.5,  2.5])
>>> b = a.copy()
>>> np.median(b, axis=1, overwrite_input=True)
array([ 7.,  2.])
>>> assert not np.all(a==b)
>>> b = a.copy()
>>> np.median(b, axis=None, overwrite_input=True)
3.5
>>> assert not np.all(a==b)


numpy.average

  • Statistics
  • next
  • previous

Previous topic

numpy.median

Next topic

numpy.mean

numpy.average

numpy.average(a, axis=None, weights=None, returned=False) [source]

Compute the weighted average along the specified axis.

Parameters:

a : array_like

Array containing data to be averaged. If a is not an array, a conversion is attempted.

axis : int, optional

Axis along which to average a. If None, averaging is done over the flattened array.

weights : array_like, optional

An array of weights associated with the values in a. Each value in a contributes to the average according to its associated weight. The weights array can either be 1-D (in which case its length must be the size of a along the given axis) or of the same shape as a. If weights=None, then all data in a are assumed to have a weight equal to one.

returned : bool, optional

Default is False. If True, the tuple (average, sum_of_weights) is returned, otherwise only the average is returned. If weights=None, sum_of_weights is equivalent to the number of elements over which the average is taken.
Returns:

average, [sum_of_weights] : {array_type, double}

Return the average along the specified axis. When returned is True, return a tuple with the average as the first element and the sum of the weights as the second element. The return type is Float if a is of integer type, otherwise it is of the same type as a. sum_of_weights is of the same type as average.
Raises:

ZeroDivisionError

When all weights along axis are zero. See numpy.ma.average for a version robust to this type of error.

TypeError

When the length of 1D weights is not the same as the shape of a along axis.

See also

mean

ma.average
average for masked arrays – useful if your data contains “missing” values

Examples

>>> data = range(1,5)
>>> data
[1, 2, 3, 4]
>>> np.average(data)
2.5
>>> np.average(range(1,11), weights=range(10,0,-1))
4.0

>>> data = np.arange(6).reshape((3,2))
>>> data
array([[0, 1],
       [2, 3],
       [4, 5]])
>>> np.average(data, axis=1, weights=[1./4, 3./4])
array([ 0.75,  2.75,  4.75])
>>> np.average(data, weights=[1./4, 3./4])
Traceback (most recent call last):
...
TypeError: Axis must be specified when shapes of a and weights differ.


numpy.mean

  • Statistics
  • next
  • previous

Previous topic

numpy.average

Next topic

numpy.std

numpy.mean

numpy.mean(a, axis=None, dtype=None, out=None, keepdims=False) [source]

Compute the arithmetic mean along the specified axis.

Returns the average of the array elements. The average is taken over the flattened array by default, otherwise over the specified axis. float64 intermediate and return values are used for integer inputs.

Parameters:

a : array_like

Array containing numbers whose mean is desired. If a is not an array, a conversion is attempted.

axis : int, optional

Axis along which the means are computed. The default is to compute the mean of the flattened array.

dtype : data-type, optional

Type to use in computing the mean. For integer inputs, the default is float64; for floating point inputs, it is the same as the input dtype.

out : ndarray, optional

Alternate output array in which to place the result. The default is None; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. See doc.ufuncs for details.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

m : ndarray, see dtype parameter above

If out=None, returns a new array containing the mean values, otherwise a reference to the output array is returned.

See also

average
Weighted average

std, var, nanmean, nanstd, nanvar

Notes

The arithmetic mean is the sum of the elements along the axis divided by the number of elements.

Note that for floating-point input, the mean is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-precision accumulator using the dtype keyword can alleviate this issue.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> np.mean(a)
2.5
>>> np.mean(a, axis=0)
array([ 2.,  3.])
>>> np.mean(a, axis=1)
array([ 1.5,  3.5])

In single precision, mean can be inaccurate:

>>> a = np.zeros((2, 512*512), dtype=np.float32)
>>> a[0, :] = 1.0
>>> a[1, :] = 0.1
>>> np.mean(a)
0.546875

Computing the mean in float64 is more accurate:

>>> np.mean(a, dtype=np.float64)
0.55000000074505806


numpy.std

  • Statistics
  • next
  • previous

Previous topic

numpy.mean

Next topic

numpy.var

numpy.std

numpy.std(a, axis=None, dtype=None, out=None, ddof=0, keepdims=False) [source]

Compute the standard deviation along the specified axis.

Returns the standard deviation, a measure of the spread of a distribution, of the array elements. The standard deviation is computed for the flattened array by default, otherwise over the specified axis.

Parameters:

a : array_like

Calculate the standard deviation of these values.

axis : int, optional

Axis along which the standard deviation is computed. The default is to compute the standard deviation of the flattened array.

dtype : dtype, optional

Type to use in computing the standard deviation. For arrays of integer type the default is float64, for arrays of float types it is the same as the array type.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type (of the calculated values) will be cast if necessary.

ddof : int, optional

Means Delta Degrees of Freedom. The divisor used in calculations is N - ddof, where N represents the number of elements. By default ddof is zero.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

standard_deviation : ndarray, see dtype parameter above.

If out is None, return a new array containing the standard deviation, otherwise return a reference to the output array.

See also

var, mean, nanmean, nanstd, nanvar

numpy.doc.ufuncs
Section “Output arguments”

Notes

The standard deviation is the square root of the average of the squared deviations from the mean, i.e., std = sqrt(mean(abs(x - x.mean())**2)).

The average squared deviation is normally calculated as x.sum() / N, where N = len(x). If, however, ddof is specified, the divisor N - ddof is used instead. In standard statistical practice, ddof=1 provides an unbiased estimator of the variance of the infinite population. ddof=0 provides a maximum likelihood estimate of the variance for normally distributed variables. The standard deviation computed in this function is the square root of the estimated variance, so even with ddof=1, it will not be an unbiased estimate of the standard deviation per se.

Note that, for complex numbers, std takes the absolute value before squaring, so that the result is always real and nonnegative.

For floating-point input, the std is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-accuracy accumulator using the dtype keyword can alleviate this issue.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> np.std(a)
1.1180339887498949
>>> np.std(a, axis=0)
array([ 1.,  1.])
>>> np.std(a, axis=1)
array([ 0.5,  0.5])

In single precision, std() can be inaccurate:

>>> a = np.zeros((2,512*512), dtype=np.float32)
>>> a[0,:] = 1.0
>>> a[1,:] = 0.1
>>> np.std(a)
0.45172946707416706

Computing the standard deviation in float64 is more accurate:

>>> np.std(a, dtype=np.float64)
0.44999999925552653


numpy.var

  • Statistics
  • next
  • previous

Previous topic

numpy.std

Next topic

numpy.nanmean

numpy.var

numpy.var(a, axis=None, dtype=None, out=None, ddof=0, keepdims=False) [source]

Compute the variance along the specified axis.

Returns the variance of the array elements, a measure of the spread of a distribution. The variance is computed for the flattened array by default, otherwise over the specified axis.

Parameters:

a : array_like

Array containing numbers whose variance is desired. If a is not an array, a conversion is attempted.

axis : int, optional

Axis along which the variance is computed. The default is to compute the variance of the flattened array.

dtype : data-type, optional

Type to use in computing the variance. For arrays of integer type the default is float32; for arrays of float types it is the same as the array type.

out : ndarray, optional

Alternate output array in which to place the result. It must have the same shape as the expected output, but the type is cast if necessary.

ddof : int, optional

“Delta Degrees of Freedom”: the divisor used in the calculation is N - ddof, where N represents the number of elements. By default ddof is zero.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

variance : ndarray, see dtype parameter above

If out=None, returns a new array containing the variance; otherwise, a reference to the output array is returned.

See also

std, mean, nanmean, nanstd, nanvar

numpy.doc.ufuncs
Section “Output arguments”

Notes

The variance is the average of the squared deviations from the mean, i.e., var = mean(abs(x - x.mean())**2).

The mean is normally calculated as x.sum() / N, where N = len(x). If, however, ddof is specified, the divisor N - ddof is used instead. In standard statistical practice, ddof=1 provides an unbiased estimator of the variance of a hypothetical infinite population. ddof=0 provides a maximum likelihood estimate of the variance for normally distributed variables.

Note that for complex numbers, the absolute value is taken before squaring, so that the result is always real and nonnegative.

For floating-point input, the variance is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-accuracy accumulator using the dtype keyword can alleviate this issue.

Examples

>>> a = np.array([[1,2],[3,4]])
>>> np.var(a)
1.25
>>> np.var(a, axis=0)
array([ 1.,  1.])
>>> np.var(a, axis=1)
array([ 0.25,  0.25])

In single precision, var() can be inaccurate:

>>> a = np.zeros((2,512*512), dtype=np.float32)
>>> a[0,:] = 1.0
>>> a[1,:] = 0.1
>>> np.var(a)
0.20405951142311096

Computing the variance in float64 is more accurate:

>>> np.var(a, dtype=np.float64)
0.20249999932997387
>>> ((1-0.55)**2 + (0.1-0.55)**2)/2
0.20250000000000001


numpy.nanmean

  • Statistics
  • next
  • previous

Previous topic

numpy.var

Next topic

numpy.nanstd

numpy.nanmean

numpy.nanmean(a, axis=None, dtype=None, out=None, keepdims=False) [source]

Compute the arithmetic mean along the specified axis, ignoring NaNs.

Returns the average of the array elements. The average is taken over the flattened array by default, otherwise over the specified axis. float64 intermediate and return values are used for integer inputs.

For all-NaN slices, NaN is returned and a RuntimeWarning is raised.

New in version 1.8.0.

Parameters:

a : array_like

Array containing numbers whose mean is desired. If a is not an array, a conversion is attempted.

axis : int, optional

Axis along which the means are computed. The default is to compute the mean of the flattened array.

dtype : data-type, optional

Type to use in computing the mean. For integer inputs, the default is float64; for inexact inputs, it is the same as the input dtype.

out : ndarray, optional

Alternate output array in which to place the result. The default is None; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. See doc.ufuncs for details.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

m : ndarray, see dtype parameter above

If out=None, returns a new array containing the mean values, otherwise a reference to the output array is returned. Nan is returned for slices that contain only NaNs.

See also

average
Weighted average
mean
Arithmetic mean taken while not ignoring NaNs

var, nanvar

Notes

The arithmetic mean is the sum of the non-NaN elements along the axis divided by the number of non-NaN elements.

Note that for floating-point input, the mean is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32. Specifying a higher-precision accumulator using the dtype keyword can alleviate this issue.

Examples

>>> a = np.array([[1, np.nan], [3, 4]])
>>> np.nanmean(a)
2.6666666666666665
>>> np.nanmean(a, axis=0)
array([ 2.,  4.])
>>> np.nanmean(a, axis=1)
array([ 1.,  3.5])


numpy.nanstd

  • Statistics
  • next
  • previous

Previous topic

numpy.nanmean

Next topic

numpy.nanvar

numpy.nanstd

numpy.nanstd(a, axis=None, dtype=None, out=None, ddof=0, keepdims=False) [source]

Compute the standard deviation along the specified axis, while ignoring NaNs.

Returns the standard deviation, a measure of the spread of a distribution, of the non-NaN array elements. The standard deviation is computed for the flattened array by default, otherwise over the specified axis.

For all-NaN slices or slices with zero degrees of freedom, NaN is returned and a RuntimeWarning is raised.

New in version 1.8.0.

Parameters:

a : array_like

Calculate the standard deviation of the non-NaN values.

axis : int, optional

Axis along which the standard deviation is computed. The default is to compute the standard deviation of the flattened array.

dtype : dtype, optional

Type to use in computing the standard deviation. For arrays of integer type the default is float64, for arrays of float types it is the same as the array type.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type (of the calculated values) will be cast if necessary.

ddof : int, optional

Means Delta Degrees of Freedom. The divisor used in calculations is N - ddof, where N represents the number of non-NaN elements. By default ddof is zero.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

standard_deviation : ndarray, see dtype parameter above.

If out is None, return a new array containing the standard deviation, otherwise return a reference to the output array. If ddof is >= the number of non-NaN elements in a slice or the slice contains only NaNs, then the result for that slice is NaN.

See also

var, mean, std, nanvar, nanmean

numpy.doc.ufuncs
Section “Output arguments”

Notes

The standard deviation is the square root of the average of the squared deviations from the mean: std = sqrt(mean(abs(x - x.mean())**2)).

The average squared deviation is normally calculated as x.sum() / N, where N = len(x). If, however, ddof is specified, the divisor N - ddof is used instead. In standard statistical practice, ddof=1 provides an unbiased estimator of the variance of the infinite population. ddof=0 provides a maximum likelihood estimate of the variance for normally distributed variables. The standard deviation computed in this function is the square root of the estimated variance, so even with ddof=1, it will not be an unbiased estimate of the standard deviation per se.

Note that, for complex numbers, std takes the absolute value before squaring, so that the result is always real and nonnegative.

For floating-point input, the std is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-accuracy accumulator using the dtype keyword can alleviate this issue.

Examples

>>> a = np.array([[1, np.nan], [3, 4]])
>>> np.nanstd(a)
1.247219128924647
>>> np.nanstd(a, axis=0)
array([ 1.,  0.])
>>> np.nanstd(a, axis=1)
array([ 0.,  0.5])


numpy.nanvar

  • Statistics
  • next
  • previous

Previous topic

numpy.nanstd

Next topic

numpy.corrcoef

numpy.nanvar

numpy.nanvar(a, axis=None, dtype=None, out=None, ddof=0, keepdims=False) [source]

Compute the variance along the specified axis, while ignoring NaNs.

Returns the variance of the array elements, a measure of the spread of a distribution. The variance is computed for the flattened array by default, otherwise over the specified axis.

For all-NaN slices or slices with zero degrees of freedom, NaN is returned and a RuntimeWarning is raised.

New in version 1.8.0.

Parameters:

a : array_like

Array containing numbers whose variance is desired. If a is not an array, a conversion is attempted.

axis : int, optional

Axis along which the variance is computed. The default is to compute the variance of the flattened array.

dtype : data-type, optional

Type to use in computing the variance. For arrays of integer type the default is float32; for arrays of float types it is the same as the array type.

out : ndarray, optional

Alternate output array in which to place the result. It must have the same shape as the expected output, but the type is cast if necessary.

ddof : int, optional

“Delta Degrees of Freedom”: the divisor used in the calculation is N - ddof, where N represents the number of non-NaN elements. By default ddof is zero.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

variance : ndarray, see dtype parameter above

If out is None, return a new array containing the variance, otherwise return a reference to the output array. If ddof is >= the number of non-NaN elements in a slice or the slice contains only NaNs, then the result for that slice is NaN.

See also

std
Standard deviation
mean
Average
var
Variance while not ignoring NaNs

nanstd, nanmean

numpy.doc.ufuncs
Section “Output arguments”

Notes

The variance is the average of the squared deviations from the mean, i.e., var = mean(abs(x - x.mean())**2).

The mean is normally calculated as x.sum() / N, where N = len(x). If, however, ddof is specified, the divisor N - ddof is used instead. In standard statistical practice, ddof=1 provides an unbiased estimator of the variance of a hypothetical infinite population. ddof=0 provides a maximum likelihood estimate of the variance for normally distributed variables.

Note that for complex numbers, the absolute value is taken before squaring, so that the result is always real and nonnegative.

For floating-point input, the variance is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-accuracy accumulator using the dtype keyword can alleviate this issue.

Examples

>>> a = np.array([[1, np.nan], [3, 4]])
>>> np.var(a)
1.5555555555555554
>>> np.nanvar(a, axis=0)
array([ 1.,  0.])
>>> np.nanvar(a, axis=1)
array([ 0.,  0.25])


numpy.corrcoef

  • Statistics
  • next
  • previous

Previous topic

numpy.nanvar

Next topic

numpy.correlate

numpy.corrcoef

numpy.corrcoef(x, y=None, rowvar=1, bias=0, ddof=None) [source]

Return correlation coefficients.

Please refer to the documentation for cov for more detail. The relationship between the correlation coefficient matrix, P, and the covariance matrix, C, is

The values of P are between -1 and 1, inclusive.

Parameters:

x : array_like

A 1-D or 2-D array containing multiple variables and observations. Each row of m represents a variable, and each column a single observation of all those variables. Also see rowvar below.

y : array_like, optional

An additional set of variables and observations. y has the same shape as m.

rowvar : int, optional

If rowvar is non-zero (default), then each row represents a variable, with observations in the columns. Otherwise, the relationship is transposed: each column represents a variable, while the rows contain observations.

bias : int, optional

Default normalization is by (N - 1), where N is the number of observations (unbiased estimate). If bias is 1, then normalization is by N. These values can be overridden by using the keyword ddof in numpy versions >= 1.5.

ddof : {None, int}, optional

New in version 1.5.

If not None normalization is by (N - ddof), where N is the number of observations; this overrides the value implied by bias. The default value is None.
Returns:

out : ndarray

The correlation coefficient matrix of the variables.

See also

cov
Covariance matrix


numpy.correlate

  • Statistics
  • next
  • previous

Previous topic

numpy.corrcoef

Next topic

numpy.cov

numpy.correlate

numpy.correlate(a, v, mode='valid', old_behavior=False) [source]

Cross-correlation of two 1-dimensional sequences.

This function computes the correlation as generally defined in signal processing texts:

c_{av}[k] = sum_n a[n+k] * conj(v[n])

with a and v sequences being zero-padded where necessary and conj being the conjugate.

Parameters:

a, v : array_like

Input sequences.

mode : {‘valid’, ‘same’, ‘full’}, optional

Refer to the convolve docstring. Note that the default is valid, unlike convolve, which uses full.

old_behavior : bool

If True, uses the old behavior from Numeric, (correlate(a,v) == correlate(v,a), and the conjugate is not taken for complex arrays). If False, uses the conventional signal processing definition.
Returns:

out : ndarray

Discrete cross-correlation of a and v.

See also

convolve
Discrete, linear convolution of two one-dimensional sequences.

Notes

The definition of correlation above is not unique and sometimes correlation may be defined differently. Another common definition is:

c'_{av}[k] = sum_n a[n] conj(v[n+k])

which is related to c_{av}[k] by c'_{av}[k] = c_{av}[-k].

Examples

>>> np.correlate([1, 2, 3], [0, 1, 0.5])
array([ 3.5])
>>> np.correlate([1, 2, 3], [0, 1, 0.5], "same")
array([ 2. ,  3.5,  3. ])
>>> np.correlate([1, 2, 3], [0, 1, 0.5], "full")
array([ 0.5,  2. ,  3.5,  3. ,  0. ])

Using complex sequences:

>>> np.correlate([1+1j, 2, 3-1j], [0, 1, 0.5j], 'full')
array([ 0.5-0.5j,  1.0+0.j ,  1.5-1.5j,  3.0-1.j ,  0.0+0.j ])

Note that you get the time reversed, complex conjugated result when the two input sequences change places, i.e., c_{va}[k] = c^{*}_{av}[-k]:

>>> np.correlate([0, 1, 0.5j], [1+1j, 2, 3-1j], 'full')
array([ 0.0+0.j ,  3.0+1.j ,  1.5+1.5j,  1.0+0.j ,  0.5+0.5j])


numpy.cov

  • Statistics
  • next
  • previous

Previous topic

numpy.correlate

Next topic

numpy.histogram

numpy.cov

numpy.cov(m, y=None, rowvar=1, bias=0, ddof=None) [source]

Estimate a covariance matrix, given data.

Covariance indicates the level to which two variables vary together. If we examine N-dimensional samples, X = [x_1, x_2, ... x_N]^T, then the covariance matrix element [image] is the covariance of [image] and [image]. The element [image] is the variance of [image].

Parameters:

m : array_like

A 1-D or 2-D array containing multiple variables and observations. Each row of m represents a variable, and each column a single observation of all those variables. Also see rowvar below.

y : array_like, optional

An additional set of variables and observations. y has the same form as that of m.

rowvar : int, optional

If rowvar is non-zero (default), then each row represents a variable, with observations in the columns. Otherwise, the relationship is transposed: each column represents a variable, while the rows contain observations.

bias : int, optional

Default normalization is by (N - 1), where N is the number of observations given (unbiased estimate). If bias is 1, then normalization is by N. These values can be overridden by using the keyword ddof in numpy versions >= 1.5.

ddof : int, optional

New in version 1.5.

If not None normalization is by (N - ddof), where N is the number of observations; this overrides the value implied by bias. The default value is None.
Returns:

out : ndarray

The covariance matrix of the variables.

See also

corrcoef
Normalized covariance matrix

Examples

Consider two variables, [image] and [image], which correlate perfectly, but in opposite directions:

>>> x = np.array([[0, 2], [1, 1], [2, 0]]).T
>>> x
array([[0, 1, 2],
       [2, 1, 0]])

Note how [image] increases while [image] decreases. The covariance matrix shows this clearly:

>>> np.cov(x)
array([[ 1., -1.],
       [-1.,  1.]])

Note that element [image], which shows the correlation between [image] and [image], is negative.

Further, note how x and y are combined:

>>> x = [-2.1, -1,  4.3]
>>> y = [3,  1.1,  0.12]
>>> X = np.vstack((x,y))
>>> print np.cov(X)
[[ 11.71        -4.286     ]
 [ -4.286        2.14413333]]
>>> print np.cov(x, y)
[[ 11.71        -4.286     ]
 [ -4.286        2.14413333]]
>>> print np.cov(x)
11.71


numpy.histogram

  • Statistics
  • next
  • previous

Previous topic

numpy.cov

Next topic

numpy.histogram2d

numpy.histogram

numpy.histogram(a, bins=10, range=None, normed=False, weights=None, density=None) [source]

Compute the histogram of a set of data.

Parameters:

a : array_like

Input data. The histogram is computed over the flattened array.

bins : int or sequence of scalars, optional

If bins is an int, it defines the number of equal-width bins in the given range (10, by default). If bins is a sequence, it defines the bin edges, including the rightmost edge, allowing for non-uniform bin widths.

range : (float, float), optional

The lower and upper range of the bins. If not provided, range is simply (a.min(), a.max()). Values outside the range are ignored.

normed : bool, optional

This keyword is deprecated in Numpy 1.6 due to confusing/buggy behavior. It will be removed in Numpy 2.0. Use the density keyword instead. If False, the result will contain the number of samples in each bin. If True, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1. Note that this latter behavior is known to be buggy with unequal bin widths; use density instead.

weights : array_like, optional

An array of weights, of the same shape as a. Each value in a only contributes its associated weight towards the bin count (instead of 1). If normed is True, the weights are normalized, so that the integral of the density over the range remains 1

density : bool, optional

If False, the result will contain the number of samples in each bin. If True, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1. Note that the sum of the histogram values will not be equal to 1 unless bins of unity width are chosen; it is not a probability mass function. Overrides the normed keyword if given.
Returns:

hist : array

The values of the histogram. See normed and weights for a description of the possible semantics.

bin_edges : array of dtype float

Return the bin edges (length(hist)+1).

See also

histogramdd, bincount, searchsorted, digitize

Notes

All but the last (righthand-most) bin is half-open. In other words, if bins is:

[1, 2, 3, 4]

then the first bin is [1, 2) (including 1, but excluding 2) and the second [2, 3). The last bin, however, is [3, 4], which includes 4.

Examples

>>> np.histogram([1, 2, 1], bins=[0, 1, 2, 3])
(array([0, 2, 1]), array([0, 1, 2, 3]))
>>> np.histogram(np.arange(4), bins=np.arange(5), density=True)
(array([ 0.25,  0.25,  0.25,  0.25]), array([0, 1, 2, 3, 4]))
>>> np.histogram([[1, 2, 1], [1, 0, 1]], bins=[0,1,2,3])
(array([1, 4, 1]), array([0, 1, 2, 3]))

>>> a = np.arange(5)
>>> hist, bin_edges = np.histogram(a, density=True)
>>> hist
array([ 0.5,  0. ,  0.5,  0. ,  0. ,  0.5,  0. ,  0.5,  0. ,  0.5])
>>> hist.sum()
2.4999999999999996
>>> np.sum(hist*np.diff(bin_edges))
1.0


numpy.histogram2d

  • Statistics
  • next
  • previous

Previous topic

numpy.histogram

Next topic

numpy.histogramdd

numpy.histogram2d

numpy.histogram2d(x, y, bins=10, range=None, normed=False, weights=None) [source]

Compute the bi-dimensional histogram of two data samples.

Parameters:

x : array_like, shape (N,)

An array containing the x coordinates of the points to be histogrammed.

y : array_like, shape (N,)

An array containing the y coordinates of the points to be histogrammed.

bins : int or [int, int] or array_like or [array, array], optional

The bin specification:

  • If int, the number of bins for the two dimensions (nx=ny=bins).
  • If [int, int], the number of bins in each dimension (nx, ny = bins).
  • If array_like, the bin edges for the two dimensions (x_edges=y_edges=bins).
  • If [array, array], the bin edges in each dimension (x_edges, y_edges = bins).

range : array_like, shape(2,2), optional

The leftmost and rightmost edges of the bins along each dimension (if not specified explicitly in the bins parameters): [[xmin, xmax], [ymin, ymax]]. All values outside of this range will be considered outliers and not tallied in the histogram.

normed : bool, optional

If False, returns the number of samples in each bin. If True, returns the bin density bin_count / sample_count / bin_area.

weights : array_like, shape(N,), optional

An array of values w_i weighing each sample (x_i, y_i). Weights are normalized to 1 if normed is True. If normed is False, the values of the returned histogram are equal to the sum of the weights belonging to the samples falling into each bin.
Returns:

H : ndarray, shape(nx, ny)

The bi-dimensional histogram of samples x and y. Values in x are histogrammed along the first dimension and values in y are histogrammed along the second dimension.

xedges : ndarray, shape(nx,)

The bin edges along the first dimension.

yedges : ndarray, shape(ny,)

The bin edges along the second dimension.

See also

histogram
1D histogram
histogramdd
Multidimensional histogram

Notes

When normed is True, then the returned histogram is the sample density, defined such that the sum over bins of the product bin_value * bin_area is 1.

Please note that the histogram does not follow the Cartesian convention where x values are on the abscissa and y values on the ordinate axis. Rather, x is histogrammed along the first dimension of the array (vertical), and y along the second dimension of the array (horizontal). This ensures compatibility with histogramdd.

Examples

>>> import matplotlib as mpl
>>> import matplotlib.pyplot as plt

Construct a 2D-histogram with variable bin width. First define the bin edges:

>>> xedges = [0, 1, 1.5, 3, 5]
>>> yedges = [0, 2, 3, 4, 6]

Next we create a histogram H with random bin content:

>>> x = np.random.normal(3, 1, 100)
>>> y = np.random.normal(1, 1, 100)
>>> H, xedges, yedges = np.histogram2d(y, x, bins=(xedges, yedges))

Or we fill the histogram H with a determined bin content:

>>> H = np.ones((4, 4)).cumsum().reshape(4, 4)
>>> print H[::-1]  # This shows the bin content in the order as plotted
[[ 13.  14.  15.  16.]
 [  9.  10.  11.  12.]
 [  5.   6.   7.   8.]
 [  1.   2.   3.   4.]]

Imshow can only do an equidistant representation of bins:

>>> fig = plt.figure(figsize=(7, 3))
>>> ax = fig.add_subplot(131)
>>> ax.set_title('imshow: equidistant')
>>> im = plt.imshow(H, interpolation='nearest', origin='low',
                extent=[xedges[0], xedges[-1], yedges[0], yedges[-1]])

pcolormesh can display exact bin edges:

>>> ax = fig.add_subplot(132)
>>> ax.set_title('pcolormesh: exact bin edges')
>>> X, Y = np.meshgrid(xedges, yedges)
>>> ax.pcolormesh(X, Y, H)
>>> ax.set_aspect('equal')

NonUniformImage displays exact bin edges with interpolation:

>>> ax = fig.add_subplot(133)
>>> ax.set_title('NonUniformImage: interpolated')
>>> im = mpl.image.NonUniformImage(ax, interpolation='bilinear')
>>> xcenters = xedges[:-1] + 0.5 * (xedges[1:] - xedges[:-1])
>>> ycenters = yedges[:-1] + 0.5 * (yedges[1:] - yedges[:-1])
>>> im.set_data(xcenters, ycenters, H)
>>> ax.images.append(im)
>>> ax.set_xlim(xedges[0], xedges[-1])
>>> ax.set_ylim(yedges[0], yedges[-1])
>>> ax.set_aspect('equal')
>>> plt.show()

(Source code)


numpy.histogramdd

  • Statistics
  • next
  • previous

Previous topic

numpy.histogram2d

Next topic

numpy.bincount

numpy.histogramdd

numpy.histogramdd(sample, bins=10, range=None, normed=False, weights=None) [source]

Compute the multidimensional histogram of some data.

Parameters:

sample : array_like

The data to be histogrammed. It must be an (N,D) array or data that can be converted to such. The rows of the resulting array are the coordinates of points in a D dimensional polytope.

bins : sequence or int, optional

The bin specification:

  • A sequence of arrays describing the bin edges along each dimension.
  • The number of bins for each dimension (nx, ny, ... =bins)
  • The number of bins for all dimensions (nx=ny=...=bins).

range : sequence, optional

A sequence of lower and upper bin edges to be used if the edges are not given explicitly in bins. Defaults to the minimum and maximum values along each dimension.

normed : bool, optional

If False, returns the number of samples in each bin. If True, returns the bin density bin_count / sample_count / bin_volume.

weights : array_like (N,), optional

An array of values w_i weighing each sample (x_i, y_i, z_i, ...). Weights are normalized to 1 if normed is True. If normed is False, the values of the returned histogram are equal to the sum of the weights belonging to the samples falling into each bin.
Returns:

H : ndarray

The multidimensional histogram of sample x. See normed and weights for the different possible semantics.

edges : list

A list of D arrays describing the bin edges for each dimension.

See also

histogram
1-D histogram
histogram2d
2-D histogram

Examples

>>> r = np.random.randn(100,3)
>>> H, edges = np.histogramdd(r, bins = (5, 8, 4))
>>> H.shape, edges[0].size, edges[1].size, edges[2].size
((5, 8, 4), 6, 9, 5)


numpy.bincount

  • Statistics
  • next
  • previous

Previous topic

numpy.histogramdd

Next topic

numpy.digitize

numpy.bincount

numpy.bincount(x, weights=None, minlength=None)

Count number of occurrences of each value in array of non-negative ints.

The number of bins (of size 1) is one larger than the largest value in x. If minlength is specified, there will be at least this number of bins in the output array (though it will be longer if necessary, depending on the contents of x). Each bin gives the number of occurrences of its index value in x. If weights is specified the input array is weighted by it, i.e. if a value n is found at position i, out[n] += weight[i] instead of out[n] += 1.

Parameters:

x : array_like, 1 dimension, nonnegative ints

Input array.

weights : array_like, optional

Weights, array of the same shape as x.

minlength : int, optional

New in version 1.6.0.

A minimum number of bins for the output array.
Returns:

out : ndarray of ints

The result of binning the input array. The length of out is equal to np.amax(x)+1.
Raises:

ValueError

If the input is not 1-dimensional, or contains elements with negative values, or if minlength is non-positive.

TypeError

If the type of the input is float or complex.

See also

histogram, digitize, unique

Examples

>>> np.bincount(np.arange(5))
array([1, 1, 1, 1, 1])
>>> np.bincount(np.array([0, 1, 1, 3, 2, 1, 7]))
array([1, 3, 1, 1, 0, 0, 0, 1])

>>> x = np.array([0, 1, 1, 3, 2, 1, 7, 23])
>>> np.bincount(x).size == np.amax(x)+1
True

The input array needs to be of integer dtype, otherwise a TypeError is raised:

>>> np.bincount(np.arange(5, dtype=np.float))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: array cannot be safely cast to required type

A possible use of bincount is to perform sums over variable-size chunks of an array, using the weights keyword.

>>> w = np.array([0.3, 0.5, 0.2, 0.7, 1., -0.6]) # weights
>>> x = np.array([0, 1, 1, 2, 2, 2])
>>> np.bincount(x,  weights=w)
array([ 0.3,  0.7,  1.1])


numpy.digitize

  • Statistics
  • next
  • previous

Previous topic

numpy.bincount

Next topic

Test Support (numpy.testing)

numpy.digitize

numpy.digitize(x, bins, right=False)

Return the indices of the bins to which each value in input array belongs.

Each index i returned is such that bins[i-1] <= x < bins[i] if bins is monotonically increasing, or bins[i-1] > x >= bins[i] if bins is monotonically decreasing. If values in x are beyond the bounds of bins, 0 or len(bins) is returned as appropriate. If right is True, then the right bin is closed so that the index i is such that bins[i-1] < x <= bins[i] or bins[i-1] >= x > bins[i]`` if bins is monotonically increasing or decreasing, respectively.

Parameters:

x : array_like

Input array to be binned. It has to be 1-dimensional.

bins : array_like

Array of bins. It has to be 1-dimensional and monotonic.

right : bool, optional

Indicating whether the intervals include the right or the left bin edge. Default behavior is (right==False) indicating that the interval does not include the right edge. The left bin and is open in this case. Ie., bins[i-1] <= x < bins[i] is the default behavior for monotonically increasing bins.
Returns:

out : ndarray of ints

Output array of indices, of same shape as x.
Raises:

ValueError

If the input is not 1-dimensional, or if bins is not monotonic.

TypeError

If the type of the input is complex.

See also

bincount, histogram, unique

Notes

If values in x are such that they fall outside the bin range, attempting to index bins with the indices that digitize returns will result in an IndexError.

Examples

>>> x = np.array([0.2, 6.4, 3.0, 1.6])
>>> bins = np.array([0.0, 1.0, 2.5, 4.0, 10.0])
>>> inds = np.digitize(x, bins)
>>> inds
array([1, 4, 3, 2])
>>> for n in range(x.size):
...   print bins[inds[n]-1], "<=", x[n], "<", bins[inds[n]]
...
0.0 <= 0.2 < 1.0
4.0 <= 6.4 < 10.0
2.5 <= 3.0 < 4.0
1.0 <= 1.6 < 2.5

>>> x = np.array([1.2, 10.0, 12.4, 15.5, 20.])
>>> bins = np.array([0,5,10,15,20])
>>> np.digitize(x,bins,right=True)
array([1, 2, 3, 4, 4])
>>> np.digitize(x,bins,right=False)
array([1, 3, 3, 4, 5])


Test Support (numpy.testing)

  • next
  • previous

Table Of Contents

  • Test Support (numpy.testing)
    • Asserts
    • Decorators
    • Test Running

Previous topic

numpy.digitize

Next topic

numpy.testing.assert_almost_equal

Test Support (numpy.testing)

Common test support for all numpy test scripts.

This single module should provide all the common functionality for numpy tests in a single location, so that test scripts can just import it and work right away.

Asserts

assert_almost_equal(actual, desired[, ...]) | Raises an AssertionError if two items are not equal up to desired precision.
assert_approx_equal(actual, desired[, ...]) | Raises an AssertionError if two items are not equal up to significant digits.
assert_array_almost_equal(x, y[, decimal, ...]) | Raises an AssertionError if two objects are not equal up to desired precision.
assert_allclose(actual, desired[, rtol, ...]) | Raises an AssertionError if two objects are not equal up to desired tolerance.
assert_array_almost_equal_nulp(x, y[, nulp]) | Compare two arrays relatively to their spacing.
assert_array_max_ulp(a, b[, maxulp, dtype]) | Check that all items of arrays differ in at most N Units in the Last Place.
assert_array_equal(x, y[, err_msg, verbose]) | Raises an AssertionError if two array_like objects are not equal.
assert_array_less(x, y[, err_msg, verbose]) | Raises an AssertionError if two array_like objects are not ordered by less than.
assert_equal(actual, desired[, err_msg, verbose]) | Raises an AssertionError if two objects are not equal.
assert_raises(exception_class, callable, ...) | Fail unless an exception of class exception_class is thrown by callable when invoked with arguments args and keyword arguments kwargs.
assert_raises_regex(exception_class, ...[, ...]) | Fail unless an exception of class exception_class and with message that matches expected_regexp is thrown by callable when invoked with arguments args and keyword arguments kwargs.
assert_warns(warning_class, func, *args, **kw) | Fail unless the given callable throws the specified warning.
assert_string_equal(actual, desired) | Test if two strings are equal.

Decorators

decorators.deprecated([conditional]) | Filter deprecation warnings while running the test suite.
decorators.knownfailureif(fail_condition[, msg]) | Make function raise KnownFailureTest exception if given condition is true.
decorators.setastest([tf]) | Signals to nose that this function is or is not a test.
decorators.skipif(skip_condition[, msg]) | Make function raise SkipTest exception if a given condition is true.
decorators.slow(t) | Label a test as ‘slow’.
decorate_methods(cls, decorator[, testmatch]) | Apply a decorator to all methods in a class matching a regular expression.

Test Running

Tester | alias of NoseTester
run_module_suite([file_to_run, argv]) | Run a test module.
rundocs([filename, raise_on_error]) | Run doctests found in the given file.


numpy.testing.assert_almost_equal

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.rundocs

Next topic

numpy.testing.assert_approx_equal

numpy.testing.assert_almost_equal

numpy.testing.assert_almost_equal(actual, desired, decimal=7, err_msg='', verbose=True) [source]

Raises an AssertionError if two items are not equal up to desired precision.

Note

It is recommended to use one of assert_allclose, assert_array_almost_equal_nulp or assert_array_max_ulp instead of this function for more consistent floating point comparisons.

The test is equivalent to abs(desired-actual) < 0.5 * 10**(-decimal).

Given two objects (numbers or ndarrays), check that all elements of these objects are almost equal. An exception is raised at conflicting values. For ndarrays this delegates to assert_array_almost_equal

Parameters:

actual : array_like

The object to check.

desired : array_like

The expected object.

decimal : int, optional

Desired precision, default is 7.

err_msg : str, optional

The error message to be printed in case of failure.

verbose : bool, optional

If True, the conflicting values are appended to the error message.
Raises:

AssertionError

If actual and desired are not equal up to specified precision.

See also

assert_allclose
Compare two array_like objects for equality with desired relative and/or absolute precision.

assert_array_almost_equal_nulp, assert_array_max_ulp, assert_equal

Examples

>>> import numpy.testing as npt
>>> npt.assert_almost_equal(2.3333333333333, 2.33333334)
>>> npt.assert_almost_equal(2.3333333333333, 2.33333334, decimal=10)
...
<type 'exceptions.AssertionError'>:
Items are not equal:
 ACTUAL: 2.3333333333333002
 DESIRED: 2.3333333399999998

>>> npt.assert_almost_equal(np.array([1.0,2.3333333333333]),
...                         np.array([1.0,2.33333334]), decimal=9)
...
<type 'exceptions.AssertionError'>:
Arrays are not almost equal

(mismatch 50.0%)
 x: array([ 1.        ,  2.33333333])
 y: array([ 1.        ,  2.33333334])


numpy.testing.assert_approx_equal

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.assert_almost_equal

Next topic

numpy.testing.assert_array_almost_equal

numpy.testing.assert_approx_equal

numpy.testing.assert_approx_equal(actual, desired, significant=7, err_msg='', verbose=True) [source]

Raises an AssertionError if two items are not equal up to significant digits.

Note

It is recommended to use one of assert_allclose, assert_array_almost_equal_nulp or assert_array_max_ulp instead of this function for more consistent floating point comparisons.

Given two numbers, check that they are approximately equal. Approximately equal is defined as the number of significant digits that agree.

Parameters:

actual : scalar

The object to check.

desired : scalar

The expected object.

significant : int, optional

Desired precision, default is 7.

err_msg : str, optional

The error message to be printed in case of failure.

verbose : bool, optional

If True, the conflicting values are appended to the error message.
Raises:

AssertionError

If actual and desired are not equal up to specified precision.

See also

assert_allclose
Compare two array_like objects for equality with desired relative and/or absolute precision.

assert_array_almost_equal_nulp, assert_array_max_ulp, assert_equal

Examples

>>> np.testing.assert_approx_equal(0.12345677777777e-20, 0.1234567e-20)
>>> np.testing.assert_approx_equal(0.12345670e-20, 0.12345671e-20,
                                   significant=8)
>>> np.testing.assert_approx_equal(0.12345670e-20, 0.12345672e-20,
                                   significant=8)
...
<type 'exceptions.AssertionError'>:
Items are not equal to 8 significant digits:
 ACTUAL: 1.234567e-021
 DESIRED: 1.2345672000000001e-021

the evaluated condition that raises the exception is

>>> abs(0.12345670e-20/1e-21 - 0.12345672e-20/1e-21) >= 10**-(8-1)
True


numpy.testing.assert_array_almost_equal

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.assert_approx_equal

Next topic

numpy.testing.assert_allclose

numpy.testing.assert_array_almost_equal

numpy.testing.assert_array_almost_equal(x, y, decimal=6, err_msg='', verbose=True) [source]

Raises an AssertionError if two objects are not equal up to desired precision.

Note

It is recommended to use one of assert_allclose, assert_array_almost_equal_nulp or assert_array_max_ulp instead of this function for more consistent floating point comparisons.

The test verifies identical shapes and verifies values with abs(desired-actual) < 0.5 * 10**(-decimal).

Given two array_like objects, check that the shape is equal and all elements of these objects are almost equal. An exception is raised at shape mismatch or conflicting values. In contrast to the standard usage in numpy, NaNs are compared like numbers, no assertion is raised if both objects have NaNs in the same positions.

Parameters:

x : array_like

The actual object to check.

y : array_like

The desired, expected object.

decimal : int, optional

Desired precision, default is 6.

err_msg : str, optional

The error message to be printed in case of failure.

verbose : bool, optional

If True, the conflicting values are appended to the error message.
Raises:

AssertionError

If actual and desired are not equal up to specified precision.

See also

assert_allclose
Compare two array_like objects for equality with desired relative and/or absolute precision.

assert_array_almost_equal_nulp, assert_array_max_ulp, assert_equal

Examples

the first assert does not raise an exception

>>> np.testing.assert_array_almost_equal([1.0,2.333,np.nan],
                                         [1.0,2.333,np.nan])

>>> np.testing.assert_array_almost_equal([1.0,2.33333,np.nan],
...                                      [1.0,2.33339,np.nan], decimal=5)
...
<type 'exceptions.AssertionError'>:
AssertionError:
Arrays are not almost equal

(mismatch 50.0%)
 x: array([ 1.     ,  2.33333,      NaN])
 y: array([ 1.     ,  2.33339,      NaN])

>>> np.testing.assert_array_almost_equal([1.0,2.33333,np.nan],
...                                      [1.0,2.33333, 5], decimal=5)
<type 'exceptions.ValueError'>:
ValueError:
Arrays are not almost equal
 x: array([ 1.     ,  2.33333,      NaN])
 y: array([ 1.     ,  2.33333,  5.     ])


numpy.testing.assert_allclose

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.assert_array_almost_equal

Next topic

numpy.testing.assert_array_almost_equal_nulp

numpy.testing.assert_allclose

numpy.testing.assert_allclose(actual, desired, rtol=1e-07, atol=0, err_msg='', verbose=True) [source]

Raises an AssertionError if two objects are not equal up to desired tolerance.

The test is equivalent to allclose(actual, desired, rtol, atol). It compares the difference between actual and desired to atol + rtol * abs(desired).

New in version 1.5.0.

Parameters:

actual : array_like

Array obtained.

desired : array_like

Array desired.

rtol : float, optional

Relative tolerance.

atol : float, optional

Absolute tolerance.

err_msg : str, optional

The error message to be printed in case of failure.

verbose : bool, optional

If True, the conflicting values are appended to the error message.
Raises:

AssertionError

If actual and desired are not equal up to specified precision.

See also

assert_array_almost_equal_nulp, assert_array_max_ulp

Examples

>>> x = [1e-5, 1e-3, 1e-1]
>>> y = np.arccos(np.cos(x))
>>> assert_allclose(x, y, rtol=1e-5, atol=0)


numpy.testing.assert_array_almost_equal_nulp

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.assert_allclose

Next topic

numpy.testing.assert_array_max_ulp

numpy.testing.assert_array_almost_equal_nulp

numpy.testing.assert_array_almost_equal_nulp(x, y, nulp=1) [source]

Compare two arrays relatively to their spacing.

This is a relatively robust method to compare two arrays whose amplitude is variable.

Parameters:

x, y : array_like

Input arrays.

nulp : int, optional

The maximum number of unit in the last place for tolerance (see Notes). Default is 1.
Returns:

None
Raises:

AssertionError

If the spacing between x and y for one or more elements is larger than nulp.

See also

assert_array_max_ulp
Check that all items of arrays differ in at most N Units in the Last Place.
spacing
Return the distance between x and the nearest adjacent number.

Notes

An assertion is raised if the following condition is not met:

abs(x - y) <= nulps * spacing(max(abs(x), abs(y)))

Examples

>>> x = np.array([1., 1e-10, 1e-20])
>>> eps = np.finfo(x.dtype).eps
>>> np.testing.assert_array_almost_equal_nulp(x, x*eps/2 + x)

>>> np.testing.assert_array_almost_equal_nulp(x, x*eps + x)
Traceback (most recent call last):
  ...
AssertionError: X and Y are not equal to 1 ULP (max is 2)


numpy.testing.assert_array_max_ulp

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.assert_array_almost_equal_nulp

Next topic

numpy.testing.assert_array_equal

numpy.testing.assert_array_max_ulp

numpy.testing.assert_array_max_ulp(a, b, maxulp=1, dtype=None) [source]

Check that all items of arrays differ in at most N Units in the Last Place.

Parameters:

a, b : array_like

Input arrays to be compared.

maxulp : int, optional

The maximum number of units in the last place that elements of a and b can differ. Default is 1.

dtype : dtype, optional

Data-type to convert a and b to if given. Default is None.
Returns:

ret : ndarray

Array containing number of representable floating point numbers between items in a and b.
Raises:

AssertionError

If one or more elements differ by more than maxulp.

See also

assert_array_almost_equal_nulp
Compare two arrays relatively to their spacing.

Examples

>>> a = np.linspace(0., 1., 100)
>>> res = np.testing.assert_array_max_ulp(a, np.arcsin(np.sin(a)))


numpy.testing.assert_array_equal

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.assert_array_max_ulp

Next topic

numpy.testing.assert_array_less

numpy.testing.assert_array_equal

numpy.testing.assert_array_equal(x, y, err_msg='', verbose=True) [source]

Raises an AssertionError if two array_like objects are not equal.

Given two array_like objects, check that the shape is equal and all elements of these objects are equal. An exception is raised at shape mismatch or conflicting values. In contrast to the standard usage in numpy, NaNs are compared like numbers, no assertion is raised if both objects have NaNs in the same positions.

The usual caution for verifying equality with floating point numbers is advised.

Parameters:

x : array_like

The actual object to check.

y : array_like

The desired, expected object.

err_msg : str, optional

The error message to be printed in case of failure.

verbose : bool, optional

If True, the conflicting values are appended to the error message.
Raises:

AssertionError

If actual and desired objects are not equal.

See also

assert_allclose
Compare two array_like objects for equality with desired relative and/or absolute precision.

assert_array_almost_equal_nulp, assert_array_max_ulp, assert_equal

Examples

The first assert does not raise an exception:

>>> np.testing.assert_array_equal([1.0,2.33333,np.nan],
...                               [np.exp(0),2.33333, np.nan])

Assert fails with numerical inprecision with floats:

>>> np.testing.assert_array_equal([1.0,np.pi,np.nan],
...                               [1, np.sqrt(np.pi)**2, np.nan])
...
<type 'exceptions.ValueError'>:
AssertionError:
Arrays are not equal

(mismatch 50.0%)
 x: array([ 1.        ,  3.14159265,         NaN])
 y: array([ 1.        ,  3.14159265,         NaN])

Use assert_allclose or one of the nulp (number of floating point values) functions for these cases instead:

>>> np.testing.assert_allclose([1.0,np.pi,np.nan],
...                            [1, np.sqrt(np.pi)**2, np.nan],
...                            rtol=1e-10, atol=0)


numpy.testing.assert_array_less

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.assert_array_equal

Next topic

numpy.testing.assert_equal

numpy.testing.assert_array_less

numpy.testing.assert_array_less(x, y, err_msg='', verbose=True) [source]

Raises an AssertionError if two array_like objects are not ordered by less than.

Given two array_like objects, check that the shape is equal and all elements of the first object are strictly smaller than those of the second object. An exception is raised at shape mismatch or incorrectly ordered values. Shape mismatch does not raise if an object has zero dimension. In contrast to the standard usage in numpy, NaNs are compared, no assertion is raised if both objects have NaNs in the same positions.

Parameters:

x : array_like

The smaller object to check.

y : array_like

The larger object to compare.

err_msg : string

The error message to be printed in case of failure.

verbose : bool

If True, the conflicting values are appended to the error message.
Raises:

AssertionError

If actual and desired objects are not equal.

See also

assert_array_equal
tests objects for equality
assert_array_almost_equal
test objects for equality up to precision

Examples

>>> np.testing.assert_array_less([1.0, 1.0, np.nan], [1.1, 2.0, np.nan])
>>> np.testing.assert_array_less([1.0, 1.0, np.nan], [1, 2.0, np.nan])
...
<type 'exceptions.ValueError'>:
Arrays are not less-ordered
(mismatch 50.0%)
 x: array([  1.,   1.,  NaN])
 y: array([  1.,   2.,  NaN])

>>> np.testing.assert_array_less([1.0, 4.0], 3)
...
<type 'exceptions.ValueError'>:
Arrays are not less-ordered
(mismatch 50.0%)
 x: array([ 1.,  4.])
 y: array(3)

>>> np.testing.assert_array_less([1.0, 2.0, 3.0], [4])
...
<type 'exceptions.ValueError'>:
Arrays are not less-ordered
(shapes (3,), (1,) mismatch)
 x: array([ 1.,  2.,  3.])
 y: array([4])


numpy.testing.assert_equal

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.assert_array_less

Next topic

numpy.testing.assert_raises

numpy.testing.assert_equal

numpy.testing.assert_equal(actual, desired, err_msg='', verbose=True) [source]

Raises an AssertionError if two objects are not equal.

Given two objects (scalars, lists, tuples, dictionaries or numpy arrays), check that all elements of these objects are equal. An exception is raised at the first conflicting values.

Parameters:

actual : array_like

The object to check.

desired : array_like

The expected object.

err_msg : str, optional

The error message to be printed in case of failure.

verbose : bool, optional

If True, the conflicting values are appended to the error message.
Raises:

AssertionError

If actual and desired are not equal.

Examples

>>> np.testing.assert_equal([4,5], [4,6])
...
<type 'exceptions.AssertionError'>:
Items are not equal:
item=1
 ACTUAL: 5
 DESIRED: 6


numpy.testing.assert_raises

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.assert_equal

Next topic

numpy.testing.assert_raises_regex

numpy.testing.assert_raises

numpy.testing.assert_raises(exception_class, callable, *args, **kwargs) [source]

Fail unless an exception of class exception_class is thrown by callable when invoked with arguments args and keyword arguments kwargs. If a different type of exception is thrown, it will not be caught, and the test case will be deemed to have suffered an error, exactly as for an unexpected exception.


numpy.testing.assert_raises_regex

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.assert_raises

Next topic

numpy.testing.assert_warns

numpy.testing.assert_raises_regex

numpy.testing.assert_raises_regex(exception_class, expected_regexp, callable_obj=None, *args, **kwargs) [source]

Fail unless an exception of class exception_class and with message that matches expected_regexp is thrown by callable when invoked with arguments args and keyword arguments kwargs.

Name of this function adheres to Python 3.2+ reference, but should work in all versions down to 2.6.


numpy.testing.assert_warns

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.assert_raises_regex

Next topic

numpy.testing.assert_string_equal

numpy.testing.assert_warns

numpy.testing.assert_warns(warning_class, func, *args, **kw) [source]

Fail unless the given callable throws the specified warning.

A warning of class warning_class should be thrown by the callable when invoked with arguments args and keyword arguments kwargs. If a different type of warning is thrown, it will not be caught, and the test case will be deemed to have suffered an error.

New in version 1.4.0.

Parameters:

warning_class : class

The class defining the warning that func is expected to throw.

func : callable

The callable to test.

*args : Arguments

Arguments passed to func.

**kwargs : Kwargs

Keyword arguments passed to func.
Returns:

The value returned by func.


numpy.testing.assert_string_equal

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.assert_warns

Next topic

numpy.testing.decorators.deprecated

numpy.testing.assert_string_equal

numpy.testing.assert_string_equal(actual, desired) [source]

Test if two strings are equal.

If the given strings are equal, assert_string_equal does nothing. If they are not equal, an AssertionError is raised, and the diff between the strings is shown.

Parameters:

actual : str

The string to test for equality against the expected string.

desired : str

The expected string.

Examples

>>> np.testing.assert_string_equal('abc', 'abc')
>>> np.testing.assert_string_equal('abc', 'abcd')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
...
AssertionError: Differences in strings:
- abc+ abcd?    +


numpy.testing.decorators.deprecated

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.assert_string_equal

Next topic

numpy.testing.decorators.knownfailureif

numpy.testing.decorators.deprecated

numpy.testing.decorators.deprecated(conditional=True) [source]

Filter deprecation warnings while running the test suite.

This decorator can be used to filter DeprecationWarning’s, to avoid printing them during the test suite run, while checking that the test actually raises a DeprecationWarning.

Parameters:

conditional : bool or callable, optional

Flag to determine whether to mark test as deprecated or not. If the condition is a callable, it is used at runtime to dynamically make the decision. Default is True.
Returns:

decorator : function

The deprecated decorator itself.

Notes

New in version 1.4.0.


numpy.testing.decorators.knownfailureif

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.decorators.deprecated

Next topic

numpy.testing.decorators.setastest

numpy.testing.decorators.knownfailureif

numpy.testing.decorators.knownfailureif(fail_condition, msg=None) [source]

Make function raise KnownFailureTest exception if given condition is true.

If the condition is a callable, it is used at runtime to dynamically make the decision. This is useful for tests that may require costly imports, to delay the cost until the test suite is actually executed.

Parameters:

fail_condition : bool or callable

Flag to determine whether to mark the decorated test as a known failure (if True) or not (if False).

msg : str, optional

Message to give on raising a KnownFailureTest exception. Default is None.
Returns:

decorator : function

Decorator, which, when applied to a function, causes SkipTest to be raised when skip_condition is True, and the function to be called normally otherwise.

Notes

The decorator itself is decorated with the nose.tools.make_decorator function in order to transmit function name, and various other metadata.


numpy.testing.decorators.setastest

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.decorators.knownfailureif

Next topic

numpy.testing.decorators.skipif

numpy.testing.decorators.setastest

numpy.testing.decorators.setastest(tf=True) [source]

Signals to nose that this function is or is not a test.

Parameters:

tf : bool

If True, specifies that the decorated callable is a test. If False, specifies that the decorated callable is not a test. Default is True.

Notes

This decorator can’t use the nose namespace, because it can be called from a non-test module. See also istest and nottest in nose.tools.

Examples

setastest can be used in the following way:

from numpy.testing.decorators import setastest

@setastest(False)
def func_with_test_in_name(arg1, arg2):
    pass


numpy.testing.decorators.skipif

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.decorators.setastest

Next topic

numpy.testing.decorators.slow

numpy.testing.decorators.skipif

numpy.testing.decorators.skipif(skip_condition, msg=None) [source]

Make function raise SkipTest exception if a given condition is true.

If the condition is a callable, it is used at runtime to dynamically make the decision. This is useful for tests that may require costly imports, to delay the cost until the test suite is actually executed.

Parameters:

skip_condition : bool or callable

Flag to determine whether to skip the decorated test.

msg : str, optional

Message to give on raising a SkipTest exception. Default is None.
Returns:

decorator : function

Decorator which, when applied to a function, causes SkipTest to be raised when skip_condition is True, and the function to be called normally otherwise.

Notes

The decorator itself is decorated with the nose.tools.make_decorator function in order to transmit function name, and various other metadata.


numpy.testing.decorators.slow

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.decorators.skipif

Next topic

numpy.testing.decorate_methods

numpy.testing.decorators.slow

numpy.testing.decorators.slow(t) [source]

Label a test as ‘slow’.

The exact definition of a slow test is obviously both subjective and hardware-dependent, but in general any individual test that requires more than a second or two should be labeled as slow (the whole suite consits of thousands of tests, so even a second is significant).

Parameters:

t : callable

The test to label as slow.
Returns:

t : callable

The decorated test t.

Examples

The numpy.testing module includes import decorators as dec. A test can be decorated as slow like this:

from numpy.testing import *

@dec.slow
def test_big(self):
    print 'Big, slow test'


numpy.testing.decorate_methods

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.decorators.slow

Next topic

numpy.testing.Tester

numpy.testing.decorate_methods

numpy.testing.decorate_methods(cls, decorator, testmatch=None) [source]

Apply a decorator to all methods in a class matching a regular expression.

The given decorator is applied to all public methods of cls that are matched by the regular expression testmatch (testmatch.search(methodname)). Methods that are private, i.e. start with an underscore, are ignored.

Parameters:

cls : class

Class whose methods to decorate.

decorator : function

Decorator to apply to methods

testmatch : compiled regexp or str, optional

The regular expression. Default value is None, in which case the nose default (re.compile(r'(?:^|[\b_\.%s-])[Tt]est' % os.sep)) is used. If testmatch is a string, it is compiled to a regular expression first.


numpy.testing.Tester

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.decorate_methods

Next topic

numpy.testing.run_module_suite

numpy.testing.Tester

numpy.testing.Tester [source]

alias of NoseTester


numpy.testing.run_module_suite

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.Tester

Next topic

numpy.testing.rundocs

numpy.testing.run_module_suite

numpy.testing.run_module_suite(file_to_run=None, argv=None) [source]

Run a test module.

Equivalent to calling $ nosetests <argv> <file_to_run> from the command line

Parameters:

file_to_run: str, optional

Path to test module, or None. By default, run the module from which this function is called.

argv: list of strings

Arguments to be passed to the nose test runner. argv[0] is ignored. All command line arguments accepted by nosetests will work.

New in version 1.9.0.

Examples

Adding the following:

if __name__ == "__main__" :
    run_module_suite(argv=sys.argv)

at the end of a test module will run the tests when that module is called in the python interpreter.

Alternatively, calling:

>>> run_module_suite(file_to_run="numpy/tests/test_matlib.py")

from an interpreter will run all the test routine in ‘test_matlib.py’.


numpy.testing.rundocs

  • Test Support (numpy.testing)
  • index
  • next
  • previous

Previous topic

numpy.testing.run_module_suite

Next topic

Window functions

numpy.testing.rundocs

numpy.testing.rundocs(filename=None, raise_on_error=True) [source]

Run doctests found in the given file.

By default rundocs raises an AssertionError on failure.

Parameters:

filename : str

The path to the file for which the doctests are run.

raise_on_error : bool

Whether to raise an AssertionError when a doctest fails. Default is True.

Notes

The doctests can be run by the user/developer by adding the doctests argument to the test() call. For example, to run all tests (including doctests) for numpy.lib:

>>> np.lib.test(doctests=True)


Window functions

  • next
  • previous

Table Of Contents

  • Window functions
    • Various windows

Previous topic

numpy.testing.rundocs

Next topic

numpy.bartlett

Window functions

Various windows

bartlett(M) | Return the Bartlett window.
blackman(M) | Return the Blackman window.
hamming(M) | Return the Hamming window.
hanning(M) | Return the Hanning window.
kaiser(M, beta) | Return the Kaiser window.


numpy.bartlett

  • Window functions
  • next
  • previous

Previous topic

numpy.kaiser

Next topic

numpy.blackman

numpy.bartlett

numpy.bartlett(M) [source]

Return the Bartlett window.

The Bartlett window is very similar to a triangular window, except that the end points are at zero. It is often used in signal processing for tapering a signal, without generating too much ripple in the frequency domain.

Parameters:

M : int

Number of points in the output window. If zero or less, an empty array is returned.
Returns:

out : array

The triangular window, with the maximum value normalized to one (the value one appears only if the number of samples is odd), with the first and last samples equal to zero.

See also

blackman, hamming, hanning, kaiser

Notes

The Bartlett window is defined as

Most references to the Bartlett window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. Note that convolution with this window produces linear interpolation. It is also known as an apodization (which means”removing the foot”, i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function. The fourier transform of the Bartlett is the product of two sinc functions. Note the excellent discussion in Kanasewich.

References

[R11] M.S. Bartlett, “Periodogram Analysis and Continuous Spectra”, Biometrika 37, 1-16, 1950.
[R12] E.R. Kanasewich, “Time Sequence Analysis in Geophysics”, The University of Alberta Press, 1975, pp. 109-110.
[R13] A.V. Oppenheim and R.W. Schafer, “Discrete-Time Signal Processing”, Prentice-Hall, 1999, pp. 468-471.
[R14] Wikipedia, “Window function”, http://en.wikipedia.org/wiki/Window_function
[R15] W.H. Press, B.P. Flannery, S.A. Teukolsky, and W.T. Vetterling, “Numerical Recipes”, Cambridge University Press, 1986, page 429.

Examples

>>> np.bartlett(12)
array([ 0.        ,  0.18181818,  0.36363636,  0.54545455,  0.72727273,
        0.90909091,  0.90909091,  0.72727273,  0.54545455,  0.36363636,
        0.18181818,  0.        ])

Plot the window and its frequency response (requires SciPy and matplotlib):

>>> from numpy.fft import fft, fftshift
>>> window = np.bartlett(51)
>>> plt.plot(window)
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.title("Bartlett window")
<matplotlib.text.Text object at 0x...>
>>> plt.ylabel("Amplitude")
<matplotlib.text.Text object at 0x...>
>>> plt.xlabel("Sample")
<matplotlib.text.Text object at 0x...>
>>> plt.show()

>>> plt.figure()
<matplotlib.figure.Figure object at 0x...>
>>> A = fft(window, 2048) / 25.5
>>> mag = np.abs(fftshift(A))
>>> freq = np.linspace(-0.5, 0.5, len(A))
>>> response = 20 * np.log10(mag)
>>> response = np.clip(response, -100, 100)
>>> plt.plot(freq, response)
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.title("Frequency response of Bartlett window")
<matplotlib.text.Text object at 0x...>
>>> plt.ylabel("Magnitude [dB]")
<matplotlib.text.Text object at 0x...>
>>> plt.xlabel("Normalized frequency [cycles per sample]")
<matplotlib.text.Text object at 0x...>
>>> plt.axis('tight')
(-0.5, 0.5, -100.0, ...)
>>> plt.show()


numpy.blackman

  • Window functions
  • next
  • previous

Previous topic

numpy.bartlett

Next topic

numpy.hamming

numpy.blackman

numpy.blackman(M) [source]

Return the Blackman window.

The Blackman window is a taper formed by using the first three terms of a summation of cosines. It was designed to have close to the minimal leakage possible. It is close to optimal, only slightly worse than a Kaiser window.

Parameters:

M : int

Number of points in the output window. If zero or less, an empty array is returned.
Returns:

out : ndarray

The window, with the maximum value normalized to one (the value one appears only if the number of samples is odd).

See also

bartlett, hamming, hanning, kaiser

Notes

The Blackman window is defined as

Most references to the Blackman window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. It is also known as an apodization (which means “removing the foot”, i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function. It is known as a “near optimal” tapering function, almost as good (by some measures) as the kaiser window.

References

Blackman, R.B. and Tukey, J.W., (1958) The measurement of power spectra, Dover Publications, New York.

Oppenheim, A.V., and R.W. Schafer. Discrete-Time Signal Processing. Upper Saddle River, NJ: Prentice-Hall, 1999, pp. 468-471.

Examples

>>> np.blackman(12)
array([ -1.38777878e-17,   3.26064346e-02,   1.59903635e-01,
         4.14397981e-01,   7.36045180e-01,   9.67046769e-01,
         9.67046769e-01,   7.36045180e-01,   4.14397981e-01,
         1.59903635e-01,   3.26064346e-02,  -1.38777878e-17])

Plot the window and the frequency response:

>>> from numpy.fft import fft, fftshift
>>> window = np.blackman(51)
>>> plt.plot(window)
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.title("Blackman window")
<matplotlib.text.Text object at 0x...>
>>> plt.ylabel("Amplitude")
<matplotlib.text.Text object at 0x...>
>>> plt.xlabel("Sample")
<matplotlib.text.Text object at 0x...>
>>> plt.show()

>>> plt.figure()
<matplotlib.figure.Figure object at 0x...>
>>> A = fft(window, 2048) / 25.5
>>> mag = np.abs(fftshift(A))
>>> freq = np.linspace(-0.5, 0.5, len(A))
>>> response = 20 * np.log10(mag)
>>> response = np.clip(response, -100, 100)
>>> plt.plot(freq, response)
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.title("Frequency response of Blackman window")
<matplotlib.text.Text object at 0x...>
>>> plt.ylabel("Magnitude [dB]")
<matplotlib.text.Text object at 0x...>
>>> plt.xlabel("Normalized frequency [cycles per sample]")
<matplotlib.text.Text object at 0x...>
>>> plt.axis('tight')
(-0.5, 0.5, -100.0, ...)
>>> plt.show()


numpy.hamming

  • Window functions
  • next
  • previous

Previous topic

numpy.blackman

Next topic

numpy.hanning

numpy.hamming

numpy.hamming(M) [source]

Return the Hamming window.

The Hamming window is a taper formed by using a weighted cosine.

Parameters:

M : int

Number of points in the output window. If zero or less, an empty array is returned.
Returns:

out : ndarray

The window, with the maximum value normalized to one (the value one appears only if the number of samples is odd).

See also

bartlett, blackman, hanning, kaiser

Notes

The Hamming window is defined as

The Hamming was named for R. W. Hamming, an associate of J. W. Tukey and is described in Blackman and Tukey. It was recommended for smoothing the truncated autocovariance function in the time domain. Most references to the Hamming window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. It is also known as an apodization (which means “removing the foot”, i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function.

References

[R21] Blackman, R.B. and Tukey, J.W., (1958) The measurement of power spectra, Dover Publications, New York.
[R22] E.R. Kanasewich, “Time Sequence Analysis in Geophysics”, The University of Alberta Press, 1975, pp. 109-110.
[R23] Wikipedia, “Window function”, http://en.wikipedia.org/wiki/Window_function
[R24] W.H. Press, B.P. Flannery, S.A. Teukolsky, and W.T. Vetterling, “Numerical Recipes”, Cambridge University Press, 1986, page 425.

Examples

>>> np.hamming(12)
array([ 0.08      ,  0.15302337,  0.34890909,  0.60546483,  0.84123594,
        0.98136677,  0.98136677,  0.84123594,  0.60546483,  0.34890909,
        0.15302337,  0.08      ])

Plot the window and the frequency response:

>>> from numpy.fft import fft, fftshift
>>> window = np.hamming(51)
>>> plt.plot(window)
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.title("Hamming window")
<matplotlib.text.Text object at 0x...>
>>> plt.ylabel("Amplitude")
<matplotlib.text.Text object at 0x...>
>>> plt.xlabel("Sample")
<matplotlib.text.Text object at 0x...>
>>> plt.show()

>>> plt.figure()
<matplotlib.figure.Figure object at 0x...>
>>> A = fft(window, 2048) / 25.5
>>> mag = np.abs(fftshift(A))
>>> freq = np.linspace(-0.5, 0.5, len(A))
>>> response = 20 * np.log10(mag)
>>> response = np.clip(response, -100, 100)
>>> plt.plot(freq, response)
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.title("Frequency response of Hamming window")
<matplotlib.text.Text object at 0x...>
>>> plt.ylabel("Magnitude [dB]")
<matplotlib.text.Text object at 0x...>
>>> plt.xlabel("Normalized frequency [cycles per sample]")
<matplotlib.text.Text object at 0x...>
>>> plt.axis('tight')
(-0.5, 0.5, -100.0, ...)
>>> plt.show()


numpy.hanning

  • Window functions
  • next
  • previous

Previous topic

numpy.hamming

Next topic

numpy.kaiser

numpy.hanning

numpy.hanning(M) [source]

Return the Hanning window.

The Hanning window is a taper formed by using a weighted cosine.

Parameters:

M : int

Number of points in the output window. If zero or less, an empty array is returned.
Returns:

out : ndarray, shape(M,)

The window, with the maximum value normalized to one (the value one appears only if M is odd).

See also

bartlett, blackman, hamming, kaiser

Notes

The Hanning window is defined as

The Hanning was named for Julius van Hann, an Austrian meteorologist. It is also known as the Cosine Bell. Some authors prefer that it be called a Hann window, to help avoid confusion with the very similar Hamming window.

Most references to the Hanning window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. It is also known as an apodization (which means “removing the foot”, i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function.

References

[R25] Blackman, R.B. and Tukey, J.W., (1958) The measurement of power spectra, Dover Publications, New York.
[R26] E.R. Kanasewich, “Time Sequence Analysis in Geophysics”, The University of Alberta Press, 1975, pp. 106-108.
[R27] Wikipedia, “Window function”, http://en.wikipedia.org/wiki/Window_function
[R28] W.H. Press, B.P. Flannery, S.A. Teukolsky, and W.T. Vetterling, “Numerical Recipes”, Cambridge University Press, 1986, page 425.

Examples

>>> np.hanning(12)
array([ 0.        ,  0.07937323,  0.29229249,  0.57115742,  0.82743037,
        0.97974649,  0.97974649,  0.82743037,  0.57115742,  0.29229249,
        0.07937323,  0.        ])

Plot the window and its frequency response:

>>> from numpy.fft import fft, fftshift
>>> window = np.hanning(51)
>>> plt.plot(window)
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.title("Hann window")
<matplotlib.text.Text object at 0x...>
>>> plt.ylabel("Amplitude")
<matplotlib.text.Text object at 0x...>
>>> plt.xlabel("Sample")
<matplotlib.text.Text object at 0x...>
>>> plt.show()

>>> plt.figure()
<matplotlib.figure.Figure object at 0x...>
>>> A = fft(window, 2048) / 25.5
>>> mag = np.abs(fftshift(A))
>>> freq = np.linspace(-0.5, 0.5, len(A))
>>> response = 20 * np.log10(mag)
>>> response = np.clip(response, -100, 100)
>>> plt.plot(freq, response)
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.title("Frequency response of the Hann window")
<matplotlib.text.Text object at 0x...>
>>> plt.ylabel("Magnitude [dB]")
<matplotlib.text.Text object at 0x...>
>>> plt.xlabel("Normalized frequency [cycles per sample]")
<matplotlib.text.Text object at 0x...>
>>> plt.axis('tight')
(-0.5, 0.5, -100.0, ...)
>>> plt.show()


numpy.kaiser

  • Window functions
  • next
  • previous

Previous topic

numpy.hanning

Next topic

Packaging (numpy.distutils)

numpy.kaiser

numpy.kaiser(M, beta) [source]

Return the Kaiser window.

The Kaiser window is a taper formed by using a Bessel function.

Parameters:

M : int

Number of points in the output window. If zero or less, an empty array is returned.

beta : float

Shape parameter for window.
Returns:

out : array

The window, with the maximum value normalized to one (the value one appears only if the number of samples is odd).

See also

bartlett, blackman, hamming, hanning

Notes

The Kaiser window is defined as

with

where [image] is the modified zeroth-order Bessel function.

The Kaiser was named for Jim Kaiser, who discovered a simple approximation to the DPSS window based on Bessel functions. The Kaiser window is a very good approximation to the Digital Prolate Spheroidal Sequence, or Slepian window, which is the transform which maximizes the energy in the main lobe of the window relative to total energy.

The Kaiser can approximate many other windows by varying the beta parameter.

beta | Window shape
0 | Rectangular
5 | Similar to a Hamming
6 | Similar to a Hanning
8.6 | Similar to a Blackman

A beta value of 14 is probably a good starting point. Note that as beta gets large, the window narrows, and so the number of samples needs to be large enough to sample the increasingly narrow spike, otherwise NaNs will get returned.

Most references to the Kaiser window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. It is also known as an apodization (which means “removing the foot”, i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function.

References

[R34] J. F. Kaiser, “Digital Filters” - Ch 7 in “Systems analysis by digital computer”, Editors: F.F. Kuo and J.F. Kaiser, p 218-285. John Wiley and Sons, New York, (1966).
[R35] E.R. Kanasewich, “Time Sequence Analysis in Geophysics”, The University of Alberta Press, 1975, pp. 177-178.
[R36] Wikipedia, “Window function”, http://en.wikipedia.org/wiki/Window_function

Examples

>>> np.kaiser(12, 14)
array([  7.72686684e-06,   3.46009194e-03,   4.65200189e-02,
         2.29737120e-01,   5.99885316e-01,   9.45674898e-01,
         9.45674898e-01,   5.99885316e-01,   2.29737120e-01,
         4.65200189e-02,   3.46009194e-03,   7.72686684e-06])

Plot the window and the frequency response:

>>> from numpy.fft import fft, fftshift
>>> window = np.kaiser(51, 14)
>>> plt.plot(window)
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.title("Kaiser window")
<matplotlib.text.Text object at 0x...>
>>> plt.ylabel("Amplitude")
<matplotlib.text.Text object at 0x...>
>>> plt.xlabel("Sample")
<matplotlib.text.Text object at 0x...>
>>> plt.show()

>>> plt.figure()
<matplotlib.figure.Figure object at 0x...>
>>> A = fft(window, 2048) / 25.5
>>> mag = np.abs(fftshift(A))
>>> freq = np.linspace(-0.5, 0.5, len(A))
>>> response = 20 * np.log10(mag)
>>> response = np.clip(response, -100, 100)
>>> plt.plot(freq, response)
[<matplotlib.lines.Line2D object at 0x...>]
>>> plt.title("Frequency response of Kaiser window")
<matplotlib.text.Text object at 0x...>
>>> plt.ylabel("Magnitude [dB]")
<matplotlib.text.Text object at 0x...>
>>> plt.xlabel("Normalized frequency [cycles per sample]")
<matplotlib.text.Text object at 0x...>
>>> plt.axis('tight')
(-0.5, 0.5, -100.0, ...)
>>> plt.show()


Packaging (numpy.distutils)

  • next
  • previous

Table Of Contents

  • Packaging (numpy.distutils)
    • Modules in numpy.distutils
      • misc_util
      • Other modules
    • Building Installable C libraries
      • npy-pkg-config files
      • Reusing a C library from another package
    • Conversion of .src files
      • Fortran files
        • Named repeat rule
        • Short repeat rule
        • Pre-defined names
      • Other files

Previous topic

numpy.kaiser

Next topic

numpy.distutils.misc_util.get_numpy_include_dirs

Packaging (numpy.distutils)

NumPy provides enhanced distutils functionality to make it easier to build and install sub-packages, auto-generate code, and extension modules that use Fortran-compiled libraries. To use features of NumPy distutils, use the setup command from numpy.distutils.core. A useful Configuration class is also provided in numpy.distutils.misc_util that can make it easier to construct keyword arguments to pass to the setup function (by passing the dictionary obtained from the todict() method of the class). More information is available in the NumPy Distutils Users Guide in <site-packages>/numpy/doc/DISTUTILS.txt.

Modules in numpy.distutils

misc_util

get_numpy_include_dirs() |
dict_append(d, **kws) |
appendpath(prefix, path) |
allpath(name) | Convert a /-separated pathname to one using the OS’s path separator.
dot_join(*args) |
generate_config_py(target) | Generate config.py file containing system_info information used during building the package.
get_cmd(cmdname[, _cache]) |
terminal_has_colors() |
red_text(s) |
green_text(s) |
yellow_text(s) |
blue_text(s) |
cyan_text(s) |
cyg2win32(path) |
all_strings(lst) | Return True if all items in lst are string objects.
has_f_sources(sources) | Return True if sources contains Fortran files
has_cxx_sources(sources) | Return True if sources contains C++ files
filter_sources(sources) | Return four lists of filenames containing C, C++, Fortran, and Fortran 90 module sources, respectively.
get_dependencies(sources) |
is_local_src_dir(directory) | Return true if directory is local directory.
get_ext_source_files(ext) |
get_script_files(scripts) |
class numpy.distutils.misc_util.Configuration(package_name=None, parent_name=None, top_path=None, package_path=None, **attrs) [source]

Construct a configuration instance for the given package name. If parent_name is not None, then construct the package as a sub-package of the parent_name package. If top_path and package_path are None then they are assumed equal to the path of the file this instance was created in. The setup.py files in the numpy distribution are good examples of how to use the Configuration instance.

todict() [source]

Return a dictionary compatible with the keyword arguments of distutils setup function.

Examples

>>> setup(**config.todict())
get_distribution() [source]

Return the distutils distribution object for self.

get_subpackage(subpackage_name, subpackage_path=None, parent_name=None, caller_level=1) [source]

Return list of subpackage configurations.

Parameters:

subpackage_name : str or None

Name of the subpackage to get the configuration. ‘*’ in subpackage_name is handled as a wildcard.

subpackage_path : str

If None, then the path is assumed to be the local path plus the subpackage_name. If a setup.py file is not found in the subpackage_path, then a default configuration is used.

parent_name : str

Parent name.
add_subpackage(subpackage_name, subpackage_path=None, standalone=False) [source]

Add a sub-package to the current Configuration instance.

This is useful in a setup.py script for adding sub-packages to a package.

Parameters:

subpackage_name : str

name of the subpackage

subpackage_path : str

if given, the subpackage path such as the subpackage is in subpackage_path / subpackage_name. If None,the subpackage is assumed to be located in the local path / subpackage_name.

standalone : bool
add_data_files(*files) [source]

Add data files to configuration data_files.

Parameters:

files : sequence

Argument(s) can be either

  • 2-sequence (<datadir prefix>,<path to data file(s)>)
  • paths to data files where python datadir prefix defaults to package dir.

Notes

The form of each element of the files sequence is very flexible allowing many combinations of where to get the files from the package and where they should ultimately be installed on the system. The most basic usage is for an element of the files argument sequence to be a simple filename. This will cause that file from the local path to be installed to the installation path of the self.name package (package path). The file argument can also be a relative path in which case the entire relative path will be installed into the package directory. Finally, the file can be an absolute path name in which case the file will be found at the absolute path name but installed to the package path.

This basic behavior can be augmented by passing a 2-tuple in as the file argument. The first element of the tuple should specify the relative path (under the package install directory) where the remaining sequence of files should be installed to (it has nothing to do with the file-names in the source distribution). The second element of the tuple is the sequence of files that should be installed. The files in this sequence can be filenames, relative paths, or absolute paths. For absolute paths the file will be installed in the top-level package installation directory (regardless of the first argument). Filenames and relative path names will be installed in the package install directory under the path name given as the first element of the tuple.

Rules for installation paths:

  1. file.txt -> (., file.txt)-> parent/file.txt
  2. foo/file.txt -> (foo, foo/file.txt) -> parent/foo/file.txt
  3. /foo/bar/file.txt -> (., /foo/bar/file.txt) -> parent/file.txt
  4. *.txt -> parent/a.txt, parent/b.txt
  5. foo/*.txt -> parent/foo/a.txt, parent/foo/b.txt
  6. /.txt -> (, */.txt) -> parent/c/a.txt, parent/d/b.txt
  7. (sun, file.txt) -> parent/sun/file.txt
  8. (sun, bar/file.txt) -> parent/sun/file.txt
  9. (sun, /foo/bar/file.txt) -> parent/sun/file.txt
  10. (sun, *.txt) -> parent/sun/a.txt, parent/sun/b.txt
  11. (sun, bar/*.txt) -> parent/sun/a.txt, parent/sun/b.txt
  12. (sun/, */.txt) -> parent/sun/c/a.txt, parent/d/b.txt

An additional feature is that the path to a data-file can actually be a function that takes no arguments and returns the actual path(s) to the data-files. This is useful when the data files are generated while building the package.

Examples

Add files to the list of data_files to be included with the package.

>>> self.add_data_files('foo.dat',
...     ('fun', ['gun.dat', 'nun/pun.dat', '/tmp/sun.dat']),
...     'bar/cat.dat',
...     '/full/path/to/can.dat')

will install these data files to:

<package install directory>/
 foo.dat
 fun/
   gun.dat
   nun/
     pun.dat
 sun.dat
 bar/
   car.dat
 can.dat

where <package install directory> is the package (or sub-package) directory such as ‘/usr/lib/python2.4/site-packages/mypackage’ (‘C: Python2.4 Lib site-packages mypackage’) or ‘/usr/lib/python2.4/site- packages/mypackage/mysubpackage’ (‘C: Python2.4 Lib site-packages mypackage mysubpackage’).

add_data_dir(data_path) [source]

Recursively add files under data_path to data_files list.

Recursively add files under data_path to the list of data_files to be installed (and distributed). The data_path can be either a relative path-name, or an absolute path-name, or a 2-tuple where the first argument shows where in the install directory the data directory should be installed to.

Parameters:

data_path : seq or str

Argument can be either

  • 2-sequence (<datadir suffix>, <path to data directory>)
  • path to data directory where python datadir suffix defaults to package dir.

Notes

Rules for installation paths:
foo/bar -> (foo/bar, foo/bar) -> parent/foo/bar (gun, foo/bar) -> parent/gun foo/* -> (foo/a, foo/a), (foo/b, foo/b) -> parent/foo/a, parent/foo/b (gun, foo/) -> (gun, foo/a), (gun, foo/b) -> gun (gun/, foo/) -> parent/gun/a, parent/gun/b /foo/bar -> (bar, /foo/bar) -> parent/bar (gun, /foo/bar) -> parent/gun (fun//gun/*, sun/foo/bar) -> parent/fun/foo/gun/bar

Examples

For example suppose the source directory contains fun/foo.dat and fun/bar/car.dat:

>>> self.add_data_dir('fun')
>>> self.add_data_dir(('sun', 'fun'))
>>> self.add_data_dir(('gun', '/full/path/to/fun'))

Will install data-files to the locations:

<package install directory>/
  fun/
    foo.dat
    bar/
      car.dat
  sun/
    foo.dat
    bar/
      car.dat
  gun/
    foo.dat
    car.dat
add_include_dirs(*paths) [source]

Add paths to configuration include directories.

Add the given sequence of paths to the beginning of the include_dirs list. This list will be visible to all extension modules of the current package.

add_headers(*files) [source]

Add installable headers to configuration.

Add the given sequence of files to the beginning of the headers list. By default, headers will be installed under <python- include>/<self.name.replace(‘.’,’/’)>/ directory. If an item of files is a tuple, then its first argument specifies the actual installation location relative to the <python-include> path.

Parameters:

files : str or seq

Argument(s) can be either:

  • 2-sequence (<includedir suffix>,<path to header file(s)>)
  • path(s) to header file(s) where python includedir suffix will default to package name.
add_extension(name, sources, **kw) [source]

Add extension to configuration.

Create and add an Extension instance to the ext_modules list. This method also takes the following optional keyword arguments that are passed on to the Extension constructor.

Parameters:

name : str

name of the extension

sources : seq

list of the sources. The list of sources may contain functions (called source generators) which must take an extension instance and a build directory as inputs and return a source file or list of source files or None. If None is returned then no sources are generated. If the Extension instance has no sources after processing all source generators, then no extension module is built.

include_dirs :

define_macros :

undef_macros :

library_dirs :

libraries :

runtime_library_dirs :

extra_objects :

extra_compile_args :

extra_link_args :

extra_f77_compile_args :

extra_f90_compile_args :

export_symbols :

swig_opts :

depends :

The depends list contains paths to files or directories that the sources of the extension module depend on. If any path in the depends list is newer than the extension module, then the module will be rebuilt.

language :

f2py_options :

module_dirs :

extra_info : dict or list

dict or list of dict of keywords to be appended to keywords.

Notes

The self.paths(...) method is applied to all lists that may contain paths.

add_library(name, sources, **build_info) [source]

Add library to configuration.

Parameters:

name : str

Name of the extension.

sources : sequence

List of the sources. The list of sources may contain functions (called source generators) which must take an extension instance and a build directory as inputs and return a source file or list of source files or None. If None is returned then no sources are generated. If the Extension instance has no sources after processing all source generators, then no extension module is built.

build_info : dict, optional

The following keys are allowed:

  • depends
  • macros
  • include_dirs
  • extra_compiler_args
  • extra_f77_compiler_args
  • extra_f90_compiler_args
  • f2py_options
  • language
add_scripts(*files) [source]

Add scripts to configuration.

Add the sequence of files to the beginning of the scripts list. Scripts will be installed under the <prefix>/bin/ directory.

add_installed_library(name, sources, install_dir, build_info=None) [source]

Similar to add_library, but the specified library is installed.

Most C libraries used with distutils are only used to build python extensions, but libraries built through this method will be installed so that they can be reused by third-party packages.

Parameters:

name : str

Name of the installed library.

sources : sequence

List of the library’s source files. See add_library for details.

install_dir : str

Path to install the library, relative to the current sub-package.

build_info : dict, optional

The following keys are allowed:

  • depends
  • macros
  • include_dirs
  • extra_compiler_args
  • extra_f77_compiler_args
  • extra_f90_compiler_args
  • f2py_options
  • language
Returns:

None

See also

add_library, add_npy_pkg_config, get_info

Notes

The best way to encode the options required to link against the specified C libraries is to use a “libname.ini” file, and use get_info to retrieve the required options (see add_npy_pkg_config for more information).

add_npy_pkg_config(template, install_dir, subst_dict=None) [source]

Generate and install a npy-pkg config file from a template.

The config file generated from template is installed in the given install directory, using subst_dict for variable substitution.

Parameters:

template : str

The path of the template, relatively to the current package path.

install_dir : str

Where to install the npy-pkg config file, relatively to the current package path.

subst_dict : dict, optional

If given, any string of the form @key@ will be replaced by subst_dict[key] in the template file when installed. The install prefix is always available through the variable @prefix@, since the install prefix is not easy to get reliably from setup.py.

See also

add_installed_library, get_info

Notes

This works for both standard installs and in-place builds, i.e. the @prefix@ refer to the source directory for in-place builds.

Examples

config.add_npy_pkg_config('foo.ini.in', 'lib', {'foo': bar})

Assuming the foo.ini.in file has the following content:

[meta]
Name=@foo@
Version=1.0
Description=dummy description

[default]
Cflags=-I@prefix@/include
Libs=

The generated file will have the following content:

[meta]
Name=bar
Version=1.0
Description=dummy description

[default]
Cflags=-Iprefix_dir/include
Libs=

and will be installed as foo.ini in the ‘lib’ subpath.

paths(*paths, **kws) [source]

Apply glob to paths and prepend local_path if needed.

Applies glob.glob(...) to each path in the sequence (if needed) and pre-pends the local_path if needed. Because this is called on all source lists, this allows wildcard characters to be specified in lists of sources for extension modules and libraries and scripts and allows path-names be relative to the source directory.

get_config_cmd() [source]

Returns the numpy.distutils config command instance.

get_build_temp_dir() [source]

Return a path to a temporary directory where temporary files should be placed.

have_f77c() [source]

Check for availability of Fortran 77 compiler.

Use it inside source generating function to ensure that setup distribution instance has been initialized.

Notes

True if a Fortran 77 compiler is available (because a simple Fortran 77 code was able to be compiled successfully).

have_f90c() [source]

Check for availability of Fortran 90 compiler.

Use it inside source generating function to ensure that setup distribution instance has been initialized.

Notes

True if a Fortran 90 compiler is available (because a simple Fortran 90 code was able to be compiled successfully)

get_version(version_file=None, version_variable=None) [source]

Try to get version string of a package.

Return a version string of the current package or None if the version information could not be detected.

Notes

This method scans files named __version__.py, <packagename>_version.py, version.py, and __svn_version__.py for string variables version, __version__, and <packagename>_version, until a version number is found.

make_svn_version_py(delete=True) [source]

Appends a data function to the data_files list that will generate __svn_version__.py file to the current package directory.

Generate package __svn_version__.py file from SVN revision number, it will be removed after python exits but will be available when sdist, etc commands are executed.

Notes

If __svn_version__.py existed before, nothing is done.

This is intended for working with source directories that are in an SVN repository.

make_config_py(name='__config__') [source]

Generate package __config__.py file containing system_info information used during building the package.

This file is installed to the package installation directory.

get_info(*names) [source]

Get resources information.

Return information (from system_info.get_info) for all of the names in the argument list in a single dictionary.

Other modules

system_info.get_info(name[, notfound_action]) | notfound_action:
system_info.get_standard_file(fname) | Returns a list of files named ‘fname’ from
cpuinfo.cpu |
log.set_verbosity(v[, force]) |
exec_command |

Building Installable C libraries

Conventional C libraries (installed through add_library) are not installed, and are just used during the build (they are statically linked). An installable C library is a pure C library, which does not depend on the python C runtime, and is installed such that it may be used by third-party packages. To build and install the C library, you just use the method add_installed_library instead of add_library, which takes the same arguments except for an additional install_dir argument:

>>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')

npy-pkg-config files

To make the necessary build options available to third parties, you could use the npy-pkg-config mechanism implemented in numpy.distutils. This mechanism is based on a .ini file which contains all the options. A .ini file is very similar to .pc files as used by the pkg-config unix utility:

[meta]
Name: foo
Version: 1.0
Description: foo library

[variables]
prefix = /home/user/local
libdir = ${prefix}/lib
includedir = ${prefix}/include

[default]
cflags = -I${includedir}
libs = -L${libdir} -lfoo

Generally, the file needs to be generated during the build, since it needs some information known at build time only (e.g. prefix). This is mostly automatic if one uses the Configuration method add_npy_pkg_config. Assuming we have a template file foo.ini.in as follows:

[meta]
Name: foo
Version: @version@
Description: foo library

[variables]
prefix = @prefix@
libdir = ${prefix}/lib
includedir = ${prefix}/include

[default]
cflags = -I${includedir}
libs = -L${libdir} -lfoo

and the following code in setup.py:

>>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')
>>> subst = {'version': '1.0'}
>>> config.add_npy_pkg_config('foo.ini.in', 'lib', subst_dict=subst)

This will install the file foo.ini into the directory package_dir/lib, and the foo.ini file will be generated from foo.ini.in, where each @version@ will be replaced by subst_dict['version']. The dictionary has an additional prefix substitution rule automatically added, which contains the install prefix (since this is not easy to get from setup.py). npy-pkg-config files can also be installed at the same location as used for numpy, using the path returned from get_npy_pkg_dir function.

Reusing a C library from another package

Info are easily retrieved from the get_info function in numpy.distutils.misc_util:

>>> info = get_info('npymath')
>>> config.add_extension('foo', sources=['foo.c'], extra_info=**info)

An additional list of paths to look for .ini files can be given to get_info.

Conversion of .src files

NumPy distutils supports automatic conversion of source files named <somefile>.src. This facility can be used to maintain very similar code blocks requiring only simple changes between blocks. During the build phase of setup, if a template file named <somefile>.src is encountered, a new file named <somefile> is constructed from the template and placed in the build directory to be used instead. Two forms of template conversion are supported. The first form occurs for files named named <file>.ext.src where ext is a recognized Fortran extension (f, f90, f95, f77, for, ftn, pyf). The second form is used for all other cases.

Fortran files

This template converter will replicate all function and subroutine blocks in the file with names that contain ‘<...>’ according to the rules in ‘<...>’. The number of comma-separated words in ‘<...>’ determines the number of times the block is repeated. What these words are indicates what that repeat rule, ‘<...>’, should be replaced with in each block. All of the repeat rules in a block must contain the same number of comma-separated words indicating the number of times that block should be repeated. If the word in the repeat rule needs a comma, leftarrow, or rightarrow, then prepend it with a backslash ‘ ‘. If a word in the repeat rule matches ‘ \<index>’ then it will be replaced with the <index>-th word in the same repeat specification. There are two forms for the repeat rule: named and short.

Named repeat rule

A named repeat rule is useful when the same set of repeats must be used several times in a block. It is specified using <rule1=item1, item2, item3,..., itemN>, where N is the number of times the block should be repeated. On each repeat of the block, the entire expression, ‘<...>’ will be replaced first with item1, and then with item2, and so forth until N repeats are accomplished. Once a named repeat specification has been introduced, the same repeat rule may be used in the current block by referring only to the name (i.e. <rule1>.

Short repeat rule

A short repeat rule looks like <item1, item2, item3, ..., itemN>. The rule specifies that the entire expression, ‘<...>’ should be replaced first with item1, and then with item2, and so forth until N repeats are accomplished.

Pre-defined names

The following predefined named repeat rules are available:

  • <prefix=s,d,c,z>
  • <_c=s,d,c,z>
  • <_t=real, double precision, complex, double complex>
  • <ftype=real, double precision, complex, double complex>
  • <ctype=float, double, complex_float, complex_double>
  • <ftypereal=float, double precision, \0, \1>
  • <ctypereal=float, double, \0, \1>

Other files

Non-Fortran files use a separate syntax for defining template blocks that should be repeated using a variable expansion similar to the named repeat rules of the Fortran-specific repeats. The template rules for these files are:

  1. “/**begin repeat “on a line by itself marks the beginning of a segment that should be repeated.
  2. Named variable expansions are defined using #name=item1, item2, item3, ..., itemN# and placed on successive lines. These variables are replaced in each repeat block with corresponding word. All named variables in the same repeat block must define the same number of words.
  3. In specifying the repeat rule for a named variable, item*N is short- hand for item, item, ..., item repeated N times. In addition, parenthesis in combination with *N can be used for grouping several items that should be repeated. Thus, #name=(item1, item2)*4# is equivalent to #name=item1, item2, item1, item2, item1, item2, item1, item2#
  4. “*/ “on a line by itself marks the end of the the variable expansion naming. The next line is the first line that will be repeated using the named rules.
  5. Inside the block to be repeated, the variables that should be expanded are specified as @name@.
  6. “/**end repeat**/ “on a line by itself marks the previous line as the last line of the block to be repeated.


numpy.distutils.misc_util.get_numpy_include_dirs

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.exec_command

Next topic

numpy.distutils.misc_util.dict_append

numpy.distutils.misc_util.get_numpy_include_dirs

numpy.distutils.misc_util.get_numpy_include_dirs() [source]


numpy.distutils.misc_util.dict_append

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.get_numpy_include_dirs

Next topic

numpy.distutils.misc_util.appendpath

numpy.distutils.misc_util.dict_append

numpy.distutils.misc_util.dict_append(d, **kws) [source]


numpy.distutils.misc_util.appendpath

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.dict_append

Next topic

numpy.distutils.misc_util.allpath

numpy.distutils.misc_util.appendpath

numpy.distutils.misc_util.appendpath(prefix, path) [source]


numpy.distutils.misc_util.allpath

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.appendpath

Next topic

numpy.distutils.misc_util.dot_join

numpy.distutils.misc_util.allpath

numpy.distutils.misc_util.allpath(name) [source]

Convert a /-separated pathname to one using the OS’s path separator.


numpy.distutils.misc_util.dot_join

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.allpath

Next topic

numpy.distutils.misc_util.generate_config_py

numpy.distutils.misc_util.dot_join

numpy.distutils.misc_util.dot_join(*args) [source]


numpy.distutils.misc_util.generate_config_py

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.dot_join

Next topic

numpy.distutils.misc_util.get_cmd

numpy.distutils.misc_util.generate_config_py

numpy.distutils.misc_util.generate_config_py(target) [source]

Generate config.py file containing system_info information used during building the package.

Usage:
config[‘py_modules’].append((packagename, ‘__config__’,generate_config_py))


numpy.distutils.misc_util.get_cmd

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.generate_config_py

Next topic

numpy.distutils.misc_util.terminal_has_colors

numpy.distutils.misc_util.get_cmd

numpy.distutils.misc_util.get_cmd(cmdname, _cache={}) [source]


numpy.distutils.misc_util.terminal_has_colors

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.get_cmd

Next topic

numpy.distutils.misc_util.red_text

numpy.distutils.misc_util.terminal_has_colors

numpy.distutils.misc_util.terminal_has_colors() [source]


numpy.distutils.misc_util.red_text

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.terminal_has_colors

Next topic

numpy.distutils.misc_util.green_text

numpy.distutils.misc_util.red_text

numpy.distutils.misc_util.red_text(s) [source]


numpy.distutils.misc_util.green_text

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.red_text

Next topic

numpy.distutils.misc_util.yellow_text

numpy.distutils.misc_util.green_text

numpy.distutils.misc_util.green_text(s) [source]


numpy.distutils.misc_util.yellow_text

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.green_text

Next topic

numpy.distutils.misc_util.blue_text

numpy.distutils.misc_util.yellow_text

numpy.distutils.misc_util.yellow_text(s) [source]


numpy.distutils.misc_util.blue_text

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.yellow_text

Next topic

numpy.distutils.misc_util.cyan_text

numpy.distutils.misc_util.blue_text

numpy.distutils.misc_util.blue_text(s) [source]


numpy.distutils.misc_util.cyan_text

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.blue_text

Next topic

numpy.distutils.misc_util.cyg2win32

numpy.distutils.misc_util.cyan_text

numpy.distutils.misc_util.cyan_text(s) [source]


numpy.distutils.misc_util.cyg2win32

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.cyan_text

Next topic

numpy.distutils.misc_util.all_strings

numpy.distutils.misc_util.cyg2win32

numpy.distutils.misc_util.cyg2win32(path) [source]


numpy.distutils.misc_util.all_strings

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.cyg2win32

Next topic

numpy.distutils.misc_util.has_f_sources

numpy.distutils.misc_util.all_strings

numpy.distutils.misc_util.all_strings(lst) [source]

Return True if all items in lst are string objects.


numpy.distutils.misc_util.has_f_sources

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.all_strings

Next topic

numpy.distutils.misc_util.has_cxx_sources

numpy.distutils.misc_util.has_f_sources

numpy.distutils.misc_util.has_f_sources(sources) [source]

Return True if sources contains Fortran files


numpy.distutils.misc_util.has_cxx_sources

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.has_f_sources

Next topic

numpy.distutils.misc_util.filter_sources

numpy.distutils.misc_util.has_cxx_sources

numpy.distutils.misc_util.has_cxx_sources(sources) [source]

Return True if sources contains C++ files


numpy.distutils.misc_util.filter_sources

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.has_cxx_sources

Next topic

numpy.distutils.misc_util.get_dependencies

numpy.distutils.misc_util.filter_sources

numpy.distutils.misc_util.filter_sources(sources) [source]

Return four lists of filenames containing C, C++, Fortran, and Fortran 90 module sources, respectively.


numpy.distutils.misc_util.get_dependencies

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.filter_sources

Next topic

numpy.distutils.misc_util.is_local_src_dir

numpy.distutils.misc_util.get_dependencies

numpy.distutils.misc_util.get_dependencies(sources) [source]


numpy.distutils.misc_util.is_local_src_dir

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.get_dependencies

Next topic

numpy.distutils.misc_util.get_ext_source_files

numpy.distutils.misc_util.is_local_src_dir

numpy.distutils.misc_util.is_local_src_dir(directory) [source]

Return true if directory is local directory.


numpy.distutils.misc_util.get_ext_source_files

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.is_local_src_dir

Next topic

numpy.distutils.misc_util.get_script_files

numpy.distutils.misc_util.get_ext_source_files

numpy.distutils.misc_util.get_ext_source_files(ext) [source]


numpy.distutils.misc_util.get_script_files

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.get_ext_source_files

Next topic

numpy.distutils.system_info.get_info

numpy.distutils.misc_util.get_script_files

numpy.distutils.misc_util.get_script_files(scripts) [source]


numpy.distutils.system_info.get_info

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.misc_util.get_script_files

Next topic

numpy.distutils.system_info.get_standard_file

numpy.distutils.system_info.get_info

numpy.distutils.system_info.get_info(name, notfound_action=0) [source]
notfound_action:
0 - do nothing 1 - display warning message 2 - raise error


numpy.distutils.system_info.get_standard_file

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.system_info.get_info

Next topic

numpy.distutils.cpuinfo.cpu

numpy.distutils.system_info.get_standard_file

numpy.distutils.system_info.get_standard_file(fname) [source]

Returns a list of files named ‘fname’ from 1) System-wide directory (directory-location of this module) 2) Users HOME directory (os.environ[‘HOME’]) 3) Local directory


numpy.distutils.cpuinfo.cpu

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.system_info.get_standard_file

Next topic

numpy.distutils.log.set_verbosity

numpy.distutils.cpuinfo.cpu

numpy.distutils.cpuinfo.cpu = <numpy.distutils.cpuinfo.Win32CPUInfo object at 0x000000000BAA0908>


numpy.distutils.log.set_verbosity

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.cpuinfo.cpu

Next topic

numpy.distutils.exec_command

numpy.distutils.log.set_verbosity

numpy.distutils.log.set_verbosity(v, force=False) [source]


numpy.distutils.exec_command

  • Packaging (numpy.distutils)
  • index
  • next
  • previous

Previous topic

numpy.distutils.log.set_verbosity

Next topic

Numpy C-API

numpy.distutils.exec_command

exec_command

Implements exec_command function that is (almost) equivalent to commands.getstatusoutput function but on NT, DOS systems the returned status is actually correct (though, the returned status values may be different by a factor). In addition, exec_command takes keyword arguments for (re-)defining environment variables.

Provides functions:
exec_command — execute command in a specified directory and
in the modified environment.
find_executable — locate a command using info from environment
variable PATH. Equivalent to posix which command.

Author: Pearu Peterson <pearu@cens.ioc.ee> Created: 11 January 2003

Requires: Python 2.x

Succesfully tested on:

os.name | sys.platform | comments ——–+————–+———- posix | linux2 | Debian (sid) Linux, Python 2.1.3+, 2.2.3+, 2.3.3

PyCrust 0.9.3, Idle 1.0.2

posix | linux2 | Red Hat 9 Linux, Python 2.1.3, 2.2.2, 2.3.2 posix | sunos5 | SunOS 5.9, Python 2.2, 2.3.2 posix | darwin | Darwin 7.2.0, Python 2.3 nt | win32 | Windows Me

Python 2.3(EE), Idle 1.0, PyCrust 0.7.2 Python 2.1.1 Idle 0.8

nt | win32 | Windows 98, Python 2.1.1. Idle 0.8 nt | win32 | Cygwin 98-4.10, Python 2.1.1(MSC) - echo tests

fail i.e. redefining environment variables may not work. FIXED: don’t use cygwin echo! Comment: also cmd /c echo will not work but redefining environment variables do work.

posix | cygwin | Cygwin 98-4.10, Python 2.3.3(cygming special) nt | win32 | Windows XP, Python 2.3.3

Known bugs: - Tests, that send messages to stderr, fail when executed from MSYS prompt

because the messages are lost at some point.

Functions

exec_command(command[, execute_in, ...]) | Return (status,output) of executed command.
find_executable(exe[, path, _cache]) | Return full path of a executable or None.
get_exception() |
get_pythonexe() |
is_sequence(seq) |
make_temp_file([suffix, prefix, text]) |
open_latin1(filename[, mode]) |
quote_arg(arg) |
splitcmdline(line) |
temp_file_name() |
test(**kws) |
test_cl(**kws) |
test_execute_in(**kws) |
test_nt(**kws) |
test_posix(**kws) |
test_svn(**kws) |


Numpy C-API

  • next
  • previous

Previous topic

numpy.distutils.exec_command

Next topic

Python Types and C-Structures

Numpy C-API

Beware of the man who won’t be bothered with details.
— William Feather, Sr.
The truth is out there.
— Chris Carter, The X Files

NumPy provides a C-API to enable users to extend the system and get access to the array object for use in other routines. The best way to truly understand the C-API is to read the source code. If you are unfamiliar with (C) source code, however, this can be a daunting experience at first. Be assured that the task becomes easier with practice, and you may be surprised at how simple the C-code can be to understand. Even if you don’t think you can write C-code from scratch, it is much easier to understand and modify already-written source code then create it de novo.

Python extensions are especially straightforward to understand because they all have a very similar structure. Admittedly, NumPy is not a trivial extension to Python, and may take a little more snooping to grasp. This is especially true because of the code-generation techniques, which simplify maintenance of very similar code, but can make the code a little less readable to beginners. Still, with a little persistence, the code can be opened to your understanding. It is my hope, that this guide to the C-API can assist in the process of becoming familiar with the compiled-level work that can be done with NumPy in order to squeeze that last bit of necessary speed out of your code.

  • Python Types and C-Structures
    • New Python Types Defined
    • Other C-Structures
  • System configuration
    • Data type sizes
    • Platform information
  • Data Type API
    • Enumerated Types
    • Defines
    • C-type names
    • Printf Formatting
  • Array API
    • Array structure and data access
    • Creating arrays
    • Dealing with types
    • Array flags
    • Array method alternative API
    • Functions
    • Auxiliary Data With Object Semantics
    • Array Iterators
    • Broadcasting (multi-iterators)
    • Neighborhood iterator
    • Array Scalars
    • Data-type descriptors
    • Conversion Utilities
    • Miscellaneous
  • Array Iterator API
    • Array Iterator
    • Converting from Previous NumPy Iterators
    • Simple Iteration Example
    • Simple Multi-Iteration Example
    • Iterator Data Types
    • Construction and Destruction
    • Functions For Iteration
  • UFunc API
    • Constants
    • Macros
    • Functions
    • Generic functions
    • Importing the API
  • Generalized Universal Function API
    • Definitions
    • Details of Signature
    • C-API for implementing Elementary Functions
  • Numpy core libraries
    • Numpy core math library
  • C API Deprecations
    • Background
    • Deprecation Mechanism NPY_NO_DEPRECATED_API


Python Types and C-Structures

  • Numpy C-API
  • next
  • previous

Table Of Contents

  • Python Types and C-Structures
    • New Python Types Defined
      • PyArray_Type
      • PyArrayDescr_Type
      • PyUFunc_Type
      • PyArrayIter_Type
      • PyArrayMultiIter_Type
      • PyArrayNeighborhoodIter_Type
      • PyArrayFlags_Type
      • ScalarArrayTypes
    • Other C-Structures
      • PyArray_Dims
      • PyArray_Chunk
      • PyArrayInterface
      • Internally used structures

Previous topic

Numpy C-API

Next topic

System configuration

Python Types and C-Structures

Several new types are defined in the C-code. Most of these are accessible from Python, but a few are not exposed due to their limited use. Every new Python type has an associated PyObject * with an internal structure that includes a pointer to a “method table” that defines how the new object behaves in Python. When you receive a Python object into C code, you always get a pointer to a PyObject structure. Because a PyObject structure is very generic and defines only PyObject_HEAD, by itself it is not very interesting. However, different objects contain more details after the PyObject_HEAD (but you have to cast to the correct type to access them — or use accessor functions or macros).

New Python Types Defined

Python types are the functional equivalent in C of classes in Python. By constructing a new Python type you make available a new object for Python. The ndarray object is an example of a new type defined in C. New types are defined in C by two basic steps:

  1. creating a C-structure (usually named Py{Name}Object) that is binary- compatible with the PyObject structure itself but holds the additional information needed for that particular object;
  2. populating the PyTypeObject table (pointed to by the ob_type member of the PyObject structure) with pointers to functions that implement the desired behavior for the type.

Instead of special method names which define behavior for Python classes, there are “function tables” which point to functions that implement the desired results. Since Python 2.2, the PyTypeObject itself has become dynamic which allows C types that can be “sub-typed “from other C-types in C, and sub-classed in Python. The children types inherit the attributes and methods from their parent(s).

There are two major new types: the ndarray ( PyArray_Type ) and the ufunc ( PyUFunc_Type ). Additional types play a supportive role: the PyArrayIter_Type, the PyArrayMultiIter_Type, and the PyArrayDescr_Type . The PyArrayIter_Type is the type for a flat iterator for an ndarray (the object that is returned when getting the flat attribute). The PyArrayMultiIter_Type is the type of the object returned when calling broadcast (). It handles iteration and broadcasting over a collection of nested sequences. Also, the PyArrayDescr_Type is the data-type-descriptor type whose instances describe the data. Finally, there are 21 new scalar-array types which are new Python scalars corresponding to each of the fundamental data types available for arrays. An additional 10 other types are place holders that allow the array scalars to fit into a hierarchy of actual Python types.

PyArray_Type

PyArray_Type

The Python type of the ndarray is PyArray_Type. In C, every ndarray is a pointer to a PyArrayObject structure. The ob_type member of this structure contains a pointer to the PyArray_Type typeobject.

PyArrayObject

The PyArrayObject C-structure contains all of the required information for an array. All instances of an ndarray (and its subclasses) will have this structure. For future compatibility, these structure members should normally be accessed using the provided macros. If you need a shorter name, then you can make use of NPY_AO which is defined to be equivalent to PyArrayObject.

typedef struct PyArrayObject {
    PyObject_HEAD
    char *data;
    int nd;
    npy_intp *dimensions;
    npy_intp *strides;
    PyObject *base;
    PyArray_Descr *descr;
    int flags;
    PyObject *weakreflist;
} PyArrayObject;
PyArrayObject.PyObject_HEAD

This is needed by all Python objects. It consists of (at least) a reference count member ( ob_refcnt ) and a pointer to the typeobject ( ob_type ). (Other elements may also be present if Python was compiled with special options see Include/object.h in the Python source tree for more information). The ob_type member points to a Python type object.

char *PyArrayObject.data

A pointer to the first element of the array. This pointer can (and normally should) be recast to the data type of the array.

int PyArrayObject.nd

An integer providing the number of dimensions for this array. When nd is 0, the array is sometimes called a rank-0 array. Such arrays have undefined dimensions and strides and cannot be accessed. NPY_MAXDIMS is the largest number of dimensions for any array.

npy_intp PyArrayObject.dimensions

An array of integers providing the shape in each dimension as long as nd [image] 1. The integer is always large enough to hold a pointer on the platform, so the dimension size is only limited by memory.

npy_intp *PyArrayObject.strides

An array of integers providing for each dimension the number of bytes that must be skipped to get to the next element in that dimension.

PyObject *PyArrayObject.base

This member is used to hold a pointer to another Python object that is related to this array. There are two use cases: 1) If this array does not own its own memory, then base points to the Python object that owns it (perhaps another array object), 2) If this array has the NPY_ARRAY_UPDATEIFCOPY flag set, then this array is a working copy of a “misbehaved” array. As soon as this array is deleted, the array pointed to by base will be updated with the contents of this array.

PyArray_Descr *PyArrayObject.descr

A pointer to a data-type descriptor object (see below). The data-type descriptor object is an instance of a new built-in type which allows a generic description of memory. There is a descriptor structure for each data type supported. This descriptor structure contains useful information about the type as well as a pointer to a table of function pointers to implement specific functionality.

int PyArrayObject.flags

Flags indicating how the memory pointed to by data is to be interpreted. Possible flags are NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_F_CONTIGUOUS, NPY_ARRAY_OWNDATA, NPY_ARRAY_ALIGNED, NPY_ARRAY_WRITEABLE, and NPY_ARRAY_UPDATEIFCOPY.

PyObject *PyArrayObject.weakreflist

This member allows array objects to have weak references (using the weakref module).

PyArrayDescr_Type

PyArrayDescr_Type

The PyArrayDescr_Type is the built-in type of the data-type-descriptor objects used to describe how the bytes comprising the array are to be interpreted. There are 21 statically-defined PyArray_Descr objects for the built-in data-types. While these participate in reference counting, their reference count should never reach zero. There is also a dynamic table of user-defined PyArray_Descr objects that is also maintained. Once a data-type-descriptor object is “registered” it should never be deallocated either. The function PyArray_DescrFromType (...) can be used to retrieve a PyArray_Descr object from an enumerated type-number (either built-in or user- defined).

PyArray_Descr

The format of the PyArray_Descr structure that lies at the heart of the PyArrayDescr_Type is

typedef struct {
    PyObject_HEAD
    PyTypeObject *typeobj;
    char kind;
    char type;
    char byteorder;
    char unused;
    int flags;
    int type_num;
    int elsize;
    int alignment;
    PyArray_ArrayDescr *subarray;
    PyObject *fields;
    PyArray_ArrFuncs *f;
} PyArray_Descr;
PyTypeObject *PyArray_Descr.typeobj

Pointer to a typeobject that is the corresponding Python type for the elements of this array. For the builtin types, this points to the corresponding array scalar. For user-defined types, this should point to a user-defined typeobject. This typeobject can either inherit from array scalars or not. If it does not inherit from array scalars, then the NPY_USE_GETITEM and NPY_USE_SETITEM flags should be set in the flags member.

char PyArray_Descr.kind

A character code indicating the kind of array (using the array interface typestring notation). A ‘b’ represents Boolean, a ‘i’ represents signed integer, a ‘u’ represents unsigned integer, ‘f’ represents floating point, ‘c’ represents complex floating point, ‘S’ represents 8-bit character string, ‘U’ represents 32-bit/character unicode string, and ‘V’ repesents arbitrary.

char PyArray_Descr.type

A traditional character code indicating the data type.

char PyArray_Descr.byteorder

A character indicating the byte-order: ‘>’ (big-endian), ‘<’ (little- endian), ‘=’ (native), ‘|’ (irrelevant, ignore). All builtin data- types have byteorder ‘=’.

int PyArray_Descr.flags

A data-type bit-flag that determines if the data-type exhibits object- array like behavior. Each bit in this member is a flag which are named as:

NPY_ITEM_REFCOUNT
NPY_ITEM_HASOBJECT

Indicates that items of this data-type must be reference counted (using Py_INCREF and Py_DECREF ).

NPY_LIST_PICKLE

Indicates arrays of this data-type must be converted to a list before pickling.

NPY_ITEM_IS_POINTER

Indicates the item is a pointer to some other data-type

NPY_NEEDS_INIT

Indicates memory for this data-type must be initialized (set to 0) on creation.

NPY_NEEDS_PYAPI

Indicates this data-type requires the Python C-API during access (so don’t give up the GIL if array access is going to be needed).

NPY_USE_GETITEM

On array access use the f->getitem function pointer instead of the standard conversion to an array scalar. Must use if you don’t define an array scalar to go along with the data-type.

NPY_USE_SETITEM

When creating a 0-d array from an array scalar use f->setitem instead of the standard copy from an array scalar. Must use if you don’t define an array scalar to go along with the data-type.

NPY_FROM_FIELDS

The bits that are inherited for the parent data-type if these bits are set in any field of the data-type. Currently ( NPY_NEEDS_INIT | NPY_LIST_PICKLE | NPY_ITEM_REFCOUNT | NPY_NEEDS_PYAPI ).

NPY_OBJECT_DTYPE_FLAGS

Bits set for the object data-type: ( NPY_LIST_PICKLE | NPY_USE_GETITEM | NPY_ITEM_IS_POINTER | NPY_REFCOUNT | NPY_NEEDS_INIT | NPY_NEEDS_PYAPI).

PyDataType_FLAGCHK( PyArray_Descr *dtype, int flags)

Return true if all the given flags are set for the data-type object.

PyDataType_REFCHK( PyArray_Descr *dtype)

Equivalent to PyDataType_FLAGCHK (dtype, NPY_ITEM_REFCOUNT).

int PyArray_Descr.type_num

A number that uniquely identifies the data type. For new data-types, this number is assigned when the data-type is registered.

int PyArray_Descr.elsize

For data types that are always the same size (such as long), this holds the size of the data type. For flexible data types where different arrays can have a different elementsize, this should be 0.

int PyArray_Descr.alignment

A number providing alignment information for this data type. Specifically, it shows how far from the start of a 2-element structure (whose first element is a char ), the compiler places an item of this type: offsetof(struct {char c; type v;}, v)

PyArray_ArrayDescr *PyArray_Descr.subarray

If this is non- NULL, then this data-type descriptor is a C-style contiguous array of another data-type descriptor. In other-words, each element that this descriptor describes is actually an array of some other base descriptor. This is most useful as the data-type descriptor for a field in another data-type descriptor. The fields member should be NULL if this is non- NULL (the fields member of the base descriptor can be non- NULL however). The PyArray_ArrayDescr structure is defined using

typedef struct {
    PyArray_Descr *base;
    PyObject *shape;
} PyArray_ArrayDescr;

The elements of this structure are:

PyArray_Descr *PyArray_ArrayDescr.base

The data-type-descriptor object of the base-type.

PyObject *PyArray_ArrayDescr.shape

The shape (always C-style contiguous) of the sub-array as a Python tuple.

PyObject *PyArray_Descr.fields

If this is non-NULL, then this data-type-descriptor has fields described by a Python dictionary whose keys are names (and also titles if given) and whose values are tuples that describe the fields. Recall that a data-type-descriptor always describes a fixed-length set of bytes. A field is a named sub-region of that total, fixed-length collection. A field is described by a tuple composed of another data- type-descriptor and a byte offset. Optionally, the tuple may contain a title which is normally a Python string. These tuples are placed in this dictionary keyed by name (and also title if given).

PyArray_ArrFuncs *PyArray_Descr.f

A pointer to a structure containing functions that the type needs to implement internal features. These functions are not the same thing as the universal functions (ufuncs) described later. Their signatures can vary arbitrarily.

PyArray_ArrFuncs

Functions implementing internal features. Not all of these function pointers must be defined for a given type. The required members are nonzero, copyswap, copyswapn, setitem, getitem, and cast. These are assumed to be non- NULL and NULL entries will cause a program crash. The other functions may be NULL which will just mean reduced functionality for that data-type. (Also, the nonzero function will be filled in with a default function if it is NULL when you register a user-defined data-type).

typedef struct {
    PyArray_VectorUnaryFunc *cast[NPY_NTYPES];
    PyArray_GetItemFunc *getitem;
    PyArray_SetItemFunc *setitem;
    PyArray_CopySwapNFunc *copyswapn;
    PyArray_CopySwapFunc *copyswap;
    PyArray_CompareFunc *compare;
    PyArray_ArgFunc *argmax;
    PyArray_DotFunc *dotfunc;
    PyArray_ScanFunc *scanfunc;
    PyArray_FromStrFunc *fromstr;
    PyArray_NonzeroFunc *nonzero;
    PyArray_FillFunc *fill;
    PyArray_FillWithScalarFunc *fillwithscalar;
    PyArray_SortFunc *sort[NPY_NSORTS];
    PyArray_ArgSortFunc *argsort[NPY_NSORTS];
    PyObject *castdict;
    PyArray_ScalarKindFunc *scalarkind;
    int **cancastscalarkindto;
    int *cancastto;
    int listpickle
} PyArray_ArrFuncs;

The concept of a behaved segment is used in the description of the function pointers. A behaved segment is one that is aligned and in native machine byte-order for the data-type. The nonzero, copyswap, copyswapn, getitem, and setitem functions can (and must) deal with mis-behaved arrays. The other functions require behaved memory segments.

void cast(void *from, void *to, npy_intp n, void *fromarr,
void *toarr)

An array of function pointers to cast from the current type to all of the other builtin types. Each function casts a contiguous, aligned, and notswapped buffer pointed at by from to a contiguous, aligned, and notswapped buffer pointed at by to The number of items to cast is given by n, and the arguments fromarr and toarr are interpreted as PyArrayObjects for flexible arrays to get itemsize information.

PyObject *getitem(void *data, void *arr)

A pointer to a function that returns a standard Python object from a single element of the array object arr pointed to by data. This function must be able to deal with “misbehaved “(misaligned and/or swapped) arrays correctly.

int setitem( PyObject *item, void *data, void *arr)

A pointer to a function that sets the Python object item into the array, arr, at the position pointed to by data . This function deals with “misbehaved” arrays. If successful, a zero is returned, otherwise, a negative one is returned (and a Python error set).

void copyswapn(void *dest, npy_intp dstride, void *src,
npy_intp sstride, npy_intp n, int swap, void *arr)
void copyswap(void *dest, void *src, int swap, void *arr)

These members are both pointers to functions to copy data from src to dest and swap if indicated. The value of arr is only used for flexible ( NPY_STRING, NPY_UNICODE, and NPY_VOID ) arrays (and is obtained from arr->descr->elsize ). The second function copies a single value, while the first loops over n values with the provided strides. These functions can deal with misbehaved src data. If src is NULL then no copy is performed. If swap is 0, then no byteswapping occurs. It is assumed that dest and src do not overlap. If they overlap, then use memmove (...) first followed by copyswap(n) with NULL valued src.

int compare(const void* d1, const void* d2, void* arr)

A pointer to a function that compares two elements of the array, arr, pointed to by d1 and d2. This function requires behaved (aligned and not swapped) arrays. The return value is 1 if * d1 > * d2, 0 if * d1 == * d2, and -1 if * d1 < * d2. The array object arr is used to retrieve itemsize and field information for flexible arrays.

int argmax(void* data, npy_intp n, npy_intp* max_ind,
void* arr)

A pointer to a function that retrieves the index of the largest of n elements in arr beginning at the element pointed to by data. This function requires that the memory segment be contiguous and behaved. The return value is always 0. The index of the largest element is returned in max_ind.

void dotfunc(void* ip1, npy_intp is1, void* ip2, npy_intp is2,
void* op, npy_intp n, void* arr)

A pointer to a function that multiplies two n -length sequences together, adds them, and places the result in element pointed to by op of arr. The start of the two sequences are pointed to by ip1 and ip2. To get to the next element in each sequence requires a jump of is1 and is2 bytes, respectively. This function requires behaved (though not necessarily contiguous) memory.

int scanfunc(FILE* fd, void* ip, void* sep, void* arr)

A pointer to a function that scans (scanf style) one element of the corresponding type from the file descriptor fd into the array memory pointed to by ip. The array is assumed to be behaved. If sep is not NULL, then a separator string is also scanned from the file before returning. The last argument arr is the array to be scanned into. A 0 is returned if the scan is successful. A negative number indicates something went wrong: -1 means the end of file was reached before the separator string could be scanned, -4 means that the end of file was reached before the element could be scanned, and -3 means that the element could not be interpreted from the format string. Requires a behaved array.

int fromstr(char* str, void* ip, char** endptr, void* arr)

A pointer to a function that converts the string pointed to by str to one element of the corresponding type and places it in the memory location pointed to by ip. After the conversion is completed, *endptr points to the rest of the string. The last argument arr is the array into which ip points (needed for variable-size data- types). Returns 0 on success or -1 on failure. Requires a behaved array.

Bool nonzero(void* data, void* arr)

A pointer to a function that returns TRUE if the item of arr pointed to by data is nonzero. This function can deal with misbehaved arrays.

void fill(void* data, npy_intp length, void* arr)

A pointer to a function that fills a contiguous array of given length with data. The first two elements of the array must already be filled- in. From these two values, a delta will be computed and the values from item 3 to the end will be computed by repeatedly adding this computed delta. The data buffer must be well-behaved.

void fillwithscalar(void* buffer, npy_intp length,
void* value, void* arr)

A pointer to a function that fills a contiguous buffer of the given length with a single scalar value whose address is given. The final argument is the array which is needed to get the itemsize for variable-length arrays.

int sort(void* start, npy_intp length, void* arr)

An array of function pointers to a particular sorting algorithms. A particular sorting algorithm is obtained using a key (so far NPY_QUICKSORT, :data`NPY_HEAPSORT`, and NPY_MERGESORT are defined). These sorts are done in-place assuming contiguous and aligned data.

int argsort(void* start, npy_intp* result, npy_intp length,
void *arr)

An array of function pointers to sorting algorithms for this data type. The same sorting algorithms as for sort are available. The indices producing the sort are returned in result (which must be initialized with indices 0 to length-1 inclusive).

PyObject *castdict

Either NULL or a dictionary containing low-level casting functions for user- defined data-types. Each function is wrapped in a PyCObject * and keyed by the data-type number.

NPY_SCALARKIND scalarkind( PyArrayObject* arr)

A function to determine how scalars of this type should be interpreted. The argument is NULL or a 0-dimensional array containing the data (if that is needed to determine the kind of scalar). The return value must be of type NPY_SCALARKIND.

int **cancastscalarkindto

Either NULL or an array of NPY_NSCALARKINDS pointers. These pointers should each be either NULL or a pointer to an array of integers (terminated by NPY_NOTYPE) indicating data-types that a scalar of this data-type of the specified kind can be cast to safely (this usually means without losing precision).

int *cancastto

Either NULL or an array of integers (terminated by NPY_NOTYPE ) indicated data-types that this data-type can be cast to safely (this usually means without losing precision).

int listpickle

Unused.

The PyArray_Type typeobject implements many of the features of Python objects including the tp_as_number, tp_as_sequence, tp_as_mapping, and tp_as_buffer interfaces. The rich comparison (tp_richcompare) is also used along with new-style attribute lookup for methods (tp_methods) and properties (tp_getset). The PyArray_Type can also be sub-typed.

Tip

The tp_as_number methods use a generic approach to call whatever function has been registered for handling the operation. The function PyNumeric_SetOps(..) can be used to register functions to handle particular mathematical operations (for all arrays). When the umath module is imported, it sets the numeric operations for all arrays to the corresponding ufuncs. The tp_str and tp_repr methods can also be altered using PyString_SetStringFunction(...).

PyUFunc_Type

PyUFunc_Type

The ufunc object is implemented by creation of the PyUFunc_Type. It is a very simple type that implements only basic getattribute behavior, printing behavior, and has call behavior which allows these objects to act like functions. The basic idea behind the ufunc is to hold a reference to fast 1-dimensional (vector) loops for each data type that supports the operation. These one-dimensional loops all have the same signature and are the key to creating a new ufunc. They are called by the generic looping code as appropriate to implement the N-dimensional function. There are also some generic 1-d loops defined for floating and complexfloating arrays that allow you to define a ufunc using a single scalar function (e.g. atanh).

PyUFuncObject

The core of the ufunc is the PyUFuncObject which contains all the information needed to call the underlying C-code loops that perform the actual work. It has the following structure:

typedef struct {
    PyObject_HEAD
    int nin;
    int nout;
    int nargs;
    int identity;
    PyUFuncGenericFunction *functions;
    void **data;
    int ntypes;
    int check_return;
    const char *name;
    char *types;
    const char *doc;
    void *ptr;
    PyObject *obj;
    PyObject *userloops;
    npy_uint32 *op_flags;
    npy_uint32 *iter_flags;
} PyUFuncObject;
PyUFuncObject.PyObject_HEAD

required for all Python objects.

int PyUFuncObject.nin

The number of input arguments.

int PyUFuncObject.nout

The number of output arguments.

int PyUFuncObject.nargs

The total number of arguments (nin + nout). This must be less than NPY_MAXARGS.

int PyUFuncObject.identity

Either PyUFunc_One, PyUFunc_Zero, or PyUFunc_None to indicate the identity for this operation. It is only used for a reduce-like call on an empty array.

void PyUFuncObject.functions(char** args, npy_intp* dims,
npy_intp* steps, void* extradata)

An array of function pointers — one for each data type supported by the ufunc. This is the vector loop that is called to implement the underlying function dims [0] times. The first argument, args, is an array of nargs pointers to behaved memory. Pointers to the data for the input arguments are first, followed by the pointers to the data for the output arguments. How many bytes must be skipped to get to the next element in the sequence is specified by the corresponding entry in the steps array. The last argument allows the loop to receive extra information. This is commonly used so that a single, generic vector loop can be used for multiple functions. In this case, the actual scalar function to call is passed in as extradata. The size of this function pointer array is ntypes.

void **PyUFuncObject.data

Extra data to be passed to the 1-d vector loops or NULL if no extra-data is needed. This C-array must be the same size ( i.e. ntypes) as the functions array. NULL is used if extra_data is not needed. Several C-API calls for UFuncs are just 1-d vector loops that make use of this extra data to receive a pointer to the actual function to call.

int PyUFuncObject.ntypes

The number of supported data types for the ufunc. This number specifies how many different 1-d loops (of the builtin data types) are available.

int PyUFuncObject.check_return

Obsolete and unused. However, it is set by the corresponding entry in the main ufunc creation routine: PyUFunc_FromFuncAndData (...).

char *PyUFuncObject.name

A string name for the ufunc. This is used dynamically to build the __doc__ attribute of ufuncs.

char *PyUFuncObject.types

An array of nargs [image] ntypes 8-bit type_numbers which contains the type signature for the function for each of the supported (builtin) data types. For each of the ntypes functions, the corresponding set of type numbers in this array shows how the args argument should be interpreted in the 1-d vector loop. These type numbers do not have to be the same type and mixed-type ufuncs are supported.

char *PyUFuncObject.doc

Documentation for the ufunc. Should not contain the function signature as this is generated dynamically when __doc__ is retrieved.

void *PyUFuncObject.ptr

Any dynamically allocated memory. Currently, this is used for dynamic ufuncs created from a python function to store room for the types, data, and name members.

PyObject *PyUFuncObject.obj

For ufuncs dynamically created from python functions, this member holds a reference to the underlying Python function.

PyObject *PyUFuncObject.userloops

A dictionary of user-defined 1-d vector loops (stored as CObject ptrs) for user-defined types. A loop may be registered by the user for any user-defined type. It is retrieved by type number. User defined type numbers are always larger than NPY_USERDEF.

npy_uint32 PyUFuncObject.op_flags

Override the default operand flags for each ufunc operand.

npy_uint32 PyUFuncObject.iter_flags

Override the default nditer flags for the ufunc.

PyArrayIter_Type

PyArrayIter_Type

This is an iterator object that makes it easy to loop over an N-dimensional array. It is the object returned from the flat attribute of an ndarray. It is also used extensively throughout the implementation internals to loop over an N-dimensional array. The tp_as_mapping interface is implemented so that the iterator object can be indexed (using 1-d indexing), and a few methods are implemented through the tp_methods table. This object implements the next method and can be used anywhere an iterator can be used in Python.

PyArrayIterObject

The C-structure corresponding to an object of PyArrayIter_Type is the PyArrayIterObject. The PyArrayIterObject is used to keep track of a pointer into an N-dimensional array. It contains associated information used to quickly march through the array. The pointer can be adjusted in three basic ways: 1) advance to the “next” position in the array in a C-style contiguous fashion, 2) advance to an arbitrary N-dimensional coordinate in the array, and 3) advance to an arbitrary one-dimensional index into the array. The members of the PyArrayIterObject structure are used in these calculations. Iterator objects keep their own dimension and strides information about an array. This can be adjusted as needed for “broadcasting,” or to loop over only specific dimensions.

typedef struct {
    PyObject_HEAD
    int   nd_m1;
    npy_intp  index;
    npy_intp  size;
    npy_intp  coordinates[NPY_MAXDIMS];
    npy_intp  dims_m1[NPY_MAXDIMS];
    npy_intp  strides[NPY_MAXDIMS];
    npy_intp  backstrides[NPY_MAXDIMS];
    npy_intp  factors[NPY_MAXDIMS];
    PyArrayObject *ao;
    char  *dataptr;
    Bool  contiguous;
} PyArrayIterObject;
int PyArrayIterObject.nd_m1

N-1 where N is the number of dimensions in the underlying array.

npy_intp PyArrayIterObject.index

The current 1-d index into the array.

npy_intp PyArrayIterObject.size

The total size of the underlying array.

npy_intp *PyArrayIterObject.coordinates

An N -dimensional index into the array.

npy_intp *PyArrayIterObject.dims_m1

The size of the array minus 1 in each dimension.

npy_intp *PyArrayIterObject.strides

The strides of the array. How many bytes needed to jump to the next element in each dimension.

npy_intp *PyArrayIterObject.backstrides

How many bytes needed to jump from the end of a dimension back to its beginning. Note that backstrides [k]= strides [k]*d ims_m1 [k], but it is stored here as an optimization.

npy_intp *PyArrayIterObject.factors

This array is used in computing an N-d index from a 1-d index. It contains needed products of the dimensions.

PyArrayObject *PyArrayIterObject.ao

A pointer to the underlying ndarray this iterator was created to represent.

char *PyArrayIterObject.dataptr

This member points to an element in the ndarray indicated by the index.

Bool PyArrayIterObject.contiguous

This flag is true if the underlying array is NPY_ARRAY_C_CONTIGUOUS. It is used to simplify calculations when possible.

How to use an array iterator on a C-level is explained more fully in later sections. Typically, you do not need to concern yourself with the internal structure of the iterator object, and merely interact with it through the use of the macros PyArray_ITER_NEXT (it), PyArray_ITER_GOTO (it, dest), or PyArray_ITER_GOTO1D (it, index). All of these macros require the argument it to be a PyArrayIterObject *.

PyArrayMultiIter_Type

PyArrayMultiIter_Type

This type provides an iterator that encapsulates the concept of broadcasting. It allows N arrays to be broadcast together so that the loop progresses in C-style contiguous fashion over the broadcasted array. The corresponding C-structure is the PyArrayMultiIterObject whose memory layout must begin any object, obj, passed in to the PyArray_Broadcast (obj) function. Broadcasting is performed by adjusting array iterators so that each iterator represents the broadcasted shape and size, but has its strides adjusted so that the correct element from the array is used at each iteration.

PyArrayMultiIterObject
typedef struct {
    PyObject_HEAD
    int numiter;
    npy_intp size;
    npy_intp index;
    int nd;
    npy_intp dimensions[NPY_MAXDIMS];
    PyArrayIterObject *iters[NPY_MAXDIMS];
} PyArrayMultiIterObject;
PyArrayMultiIterObject.PyObject_HEAD

Needed at the start of every Python object (holds reference count and type identification).

int PyArrayMultiIterObject.numiter

The number of arrays that need to be broadcast to the same shape.

npy_intp PyArrayMultiIterObject.size

The total broadcasted size.

npy_intp PyArrayMultiIterObject.index

The current (1-d) index into the broadcasted result.

int PyArrayMultiIterObject.nd

The number of dimensions in the broadcasted result.

npy_intp *PyArrayMultiIterObject.dimensions

The shape of the broadcasted result (only nd slots are used).

PyArrayIterObject **PyArrayMultiIterObject.iters

An array of iterator objects that holds the iterators for the arrays to be broadcast together. On return, the iterators are adjusted for broadcasting.

PyArrayNeighborhoodIter_Type

PyArrayNeighborhoodIter_Type

This is an iterator object that makes it easy to loop over an N-dimensional neighborhood.

PyArrayNeighborhoodIterObject

The C-structure corresponding to an object of PyArrayNeighborhoodIter_Type is the PyArrayNeighborhoodIterObject.

PyArrayFlags_Type

PyArrayFlags_Type

When the flags attribute is retrieved from Python, a special builtin object of this type is constructed. This special type makes it easier to work with the different flags by accessing them as attributes or by accessing them as if the object were a dictionary with the flag names as entries.

ScalarArrayTypes

There is a Python type for each of the different built-in data types that can be present in the array Most of these are simple wrappers around the corresponding data type in C. The C-names for these types are Py{TYPE}ArrType_Type where {TYPE} can be

Bool, Byte, Short, Int, Long, LongLong, UByte, UShort, UInt, ULong, ULongLong, Half, Float, Double, LongDouble, CFloat, CDouble, CLongDouble, String, Unicode, Void, and Object.

These type names are part of the C-API and can therefore be created in extension C-code. There is also a PyIntpArrType_Type and a PyUIntpArrType_Type that are simple substitutes for one of the integer types that can hold a pointer on the platform. The structure of these scalar objects is not exposed to C-code. The function PyArray_ScalarAsCtype (..) can be used to extract the C-type value from the array scalar and the function PyArray_Scalar (...) can be used to construct an array scalar from a C-value.

Other C-Structures

A few new C-structures were found to be useful in the development of NumPy. These C-structures are used in at least one C-API call and are therefore documented here. The main reason these structures were defined is to make it easy to use the Python ParseTuple C-API to convert from Python objects to a useful C-Object.

PyArray_Dims

PyArray_Dims

This structure is very useful when shape and/or strides information is supposed to be interpreted. The structure is:

typedef struct {
    npy_intp *ptr;
    int len;
} PyArray_Dims;

The members of this structure are

npy_intp *PyArray_Dims.ptr

A pointer to a list of (npy_intp) integers which usually represent array shape or array strides.

int PyArray_Dims.len

The length of the list of integers. It is assumed safe to access ptr [0] to ptr [len-1].

PyArray_Chunk

PyArray_Chunk

This is equivalent to the buffer object structure in Python up to the ptr member. On 32-bit platforms (i.e. if NPY_SIZEOF_INT == NPY_SIZEOF_INTP), the len member also matches an equivalent member of the buffer object. It is useful to represent a generic single-segment chunk of memory.

typedef struct {
    PyObject_HEAD
    PyObject *base;
    void *ptr;
    npy_intp len;
    int flags;
} PyArray_Chunk;

The members are

PyArray_Chunk.PyObject_HEAD

Necessary for all Python objects. Included here so that the PyArray_Chunk structure matches that of the buffer object (at least to the len member).

PyObject *PyArray_Chunk.base

The Python object this chunk of memory comes from. Needed so that memory can be accounted for properly.

void *PyArray_Chunk.ptr

A pointer to the start of the single-segment chunk of memory.

npy_intp PyArray_Chunk.len

The length of the segment in bytes.

int PyArray_Chunk.flags

Any data flags (e.g. NPY_ARRAY_WRITEABLE ) that should be used to interpret the memory.

PyArrayInterface

See also

The Array Interface

PyArrayInterface

The PyArrayInterface structure is defined so that NumPy and other extension modules can use the rapid array interface protocol. The __array_struct__ method of an object that supports the rapid array interface protocol should return a PyCObject that contains a pointer to a PyArrayInterface structure with the relevant details of the array. After the new array is created, the attribute should be DECREF‘d which will free the PyArrayInterface structure. Remember to INCREF the object (whose __array_struct__ attribute was retrieved) and point the base member of the new PyArrayObject to this same object. In this way the memory for the array will be managed correctly.

typedef struct {
    int two;
    int nd;
    char typekind;
    int itemsize;
    int flags;
    npy_intp *shape;
    npy_intp *strides;
    void *data;
    PyObject *descr;
} PyArrayInterface;
int PyArrayInterface.two

the integer 2 as a sanity check.

int PyArrayInterface.nd

the number of dimensions in the array.

char PyArrayInterface.typekind

A character indicating what kind of array is present according to the typestring convention with ‘t’ -> bitfield, ‘b’ -> Boolean, ‘i’ -> signed integer, ‘u’ -> unsigned integer, ‘f’ -> floating point, ‘c’ -> complex floating point, ‘O’ -> object, ‘S’ -> (byte-)string, ‘U’ -> unicode, ‘V’ -> void.

int PyArrayInterface.itemsize

The number of bytes each item in the array requires.

int PyArrayInterface.flags

Any of the bits NPY_ARRAY_C_CONTIGUOUS (1), NPY_ARRAY_F_CONTIGUOUS (2), NPY_ARRAY_ALIGNED (0x100), NPY_ARRAY_NOTSWAPPED (0x200), or NPY_ARRAY_WRITEABLE (0x400) to indicate something about the data. The NPY_ARRAY_ALIGNED, NPY_ARRAY_C_CONTIGUOUS, and NPY_ARRAY_F_CONTIGUOUS flags can actually be determined from the other parameters. The flag NPY_ARR_HAS_DESCR (0x800) can also be set to indicate to objects consuming the version 3 array interface that the descr member of the structure is present (it will be ignored by objects consuming version 2 of the array interface).

npy_intp *PyArrayInterface.shape

An array containing the size of the array in each dimension.

npy_intp *PyArrayInterface.strides

An array containing the number of bytes to jump to get to the next element in each dimension.

void *PyArrayInterface.data

A pointer to the first element of the array.

PyObject *PyArrayInterface.descr

A Python object describing the data-type in more detail (same as the descr key in __array_interface__). This can be NULL if typekind and itemsize provide enough information. This field is also ignored unless ARR_HAS_DESCR flag is on in flags.

Internally used structures

Internally, the code uses some additional Python objects primarily for memory management. These types are not accessible directly from Python, and are not exposed to the C-API. They are included here only for completeness and assistance in understanding the code.

PyUFuncLoopObject

A loose wrapper for a C-structure that contains the information needed for looping. This is useful if you are trying to understand the ufunc looping code. The PyUFuncLoopObject is the associated C-structure. It is defined in the ufuncobject.h header.

PyUFuncReduceObject

A loose wrapper for the C-structure that contains the information needed for reduce-like methods of ufuncs. This is useful if you are trying to understand the reduce, accumulate, and reduce-at code. The PyUFuncReduceObject is the associated C-structure. It is defined in the ufuncobject.h header.

PyUFunc_Loop1d

A simple linked-list of C-structures containing the information needed to define a 1-d loop for a ufunc for every defined signature of a user-defined data-type.

PyArrayMapIter_Type

Advanced indexing is handled with this Python type. It is simply a loose wrapper around the C-structure containing the variables needed for advanced array indexing. The associated C-structure, PyArrayMapIterObject, is useful if you are trying to understand the advanced-index mapping code. It is defined in the arrayobject.h header. This type is not exposed to Python and could be replaced with a C-structure. As a Python type it takes advantage of reference- counted memory management.


System configuration

  • Numpy C-API
  • next
  • previous

Table Of Contents

  • System configuration
    • Data type sizes
    • Platform information

Previous topic

Python Types and C-Structures

Next topic

Data Type API

System configuration

When NumPy is built, information about system configuration is recorded, and is made available for extension modules using Numpy’s C API. These are mostly defined in numpyconfig.h (included in ndarrayobject.h). The public symbols are prefixed by NPY_*. Numpy also offers some functions for querying information about the platform in use.

For private use, Numpy also constructs a config.h in the NumPy include directory, which is not exported by Numpy (that is a python extension which use the numpy C API will not see those symbols), to avoid namespace pollution.

Data type sizes

The NPY_SIZEOF_{CTYPE} constants are defined so that sizeof information is available to the pre-processor.

NPY_SIZEOF_SHORT
NPY_SIZEOF_INT
NPY_SIZEOF_LONG
NPY_SIZEOF_LONGLONG

sizeof(longlong) where longlong is defined appropriately on the platform.

NPY_SIZEOF_PY_LONG_LONG
NPY_SIZEOF_FLOAT
NPY_SIZEOF_DOUBLE
NPY_SIZEOF_LONG_DOUBLE
NPY_SIZEOF_PY_INTPTR_T

Size of a pointer on this platform (sizeof(void *)) (A macro defines NPY_SIZEOF_INTP as well.)

Platform information

NPY_CPU_X86
NPY_CPU_AMD64
NPY_CPU_IA64
NPY_CPU_PPC
NPY_CPU_PPC64
NPY_CPU_SPARC
NPY_CPU_SPARC64
NPY_CPU_S390
NPY_CPU_PARISC

New in version 1.3.0.

CPU architecture of the platform; only one of the above is defined.

Defined in numpy/npy_cpu.h

NPY_LITTLE_ENDIAN
NPY_BIG_ENDIAN
NPY_BYTE_ORDER

New in version 1.3.0.

Portable alternatives to the endian.h macros of GNU Libc. If big endian, NPY_BYTE_ORDER == NPY_BIG_ENDIAN, and similarly for little endian architectures.

Defined in numpy/npy_endian.h.

PyArray_GetEndianness()

New in version 1.3.0.

Returns the endianness of the current platform. One of NPY_CPU_BIG, NPY_CPU_LITTLE, or NPY_CPU_UNKNOWN_ENDIAN.


Data Type API

  • Numpy C-API
  • next
  • previous

Table Of Contents

  • Data Type API
    • Enumerated Types
    • Defines
      • Max and min values for integers
      • Number of bits in data types
      • Bit-width references to enumerated typenums
      • Integer that can hold a pointer
    • C-type names
      • Boolean
      • (Un)Signed Integer
      • (Complex) Floating point
      • Bit-width names
    • Printf Formatting

Previous topic

System configuration

Next topic

Array API

Data Type API

The standard array can have 24 different data types (and has some support for adding your own types). These data types all have an enumerated type, an enumerated type-character, and a corresponding array scalar Python type object (placed in a hierarchy). There are also standard C typedefs to make it easier to manipulate elements of the given data type. For the numeric types, there are also bit-width equivalent C typedefs and named typenumbers that make it easier to select the precision desired.

Warning

The names for the types in c code follows c naming conventions more closely. The Python names for these types follow Python conventions. Thus, NPY_FLOAT picks up a 32-bit float in C, but numpy.float_ in Python corresponds to a 64-bit double. The bit-width names can be used in both Python and C for clarity.

Enumerated Types

There is a list of enumerated types defined providing the basic 24 data types plus some useful generic names. Whenever the code requires a type number, one of these enumerated types is requested. The types are all called NPY_{NAME}:

NPY_BOOL

The enumeration value for the boolean type, stored as one byte. It may only be set to the values 0 and 1.

NPY_BYTE
NPY_INT8

The enumeration value for an 8-bit/1-byte signed integer.

NPY_SHORT
NPY_INT16

The enumeration value for a 16-bit/2-byte signed integer.

NPY_INT
NPY_INT32

The enumeration value for a 32-bit/4-byte signed integer.

NPY_LONG

Equivalent to either NPY_INT or NPY_LONGLONG, depending on the platform.

NPY_LONGLONG
NPY_INT64

The enumeration value for a 64-bit/8-byte signed integer.

NPY_UBYTE
NPY_UINT8

The enumeration value for an 8-bit/1-byte unsigned integer.

NPY_USHORT
NPY_UINT16

The enumeration value for a 16-bit/2-byte unsigned integer.

NPY_UINT
NPY_UINT32

The enumeration value for a 32-bit/4-byte unsigned integer.

NPY_ULONG

Equivalent to either NPY_UINT or NPY_ULONGLONG, depending on the platform.

NPY_ULONGLONG
NPY_UINT64

The enumeration value for a 64-bit/8-byte unsigned integer.

NPY_HALF
NPY_FLOAT16

The enumeration value for a 16-bit/2-byte IEEE 754-2008 compatible floating point type.

NPY_FLOAT
NPY_FLOAT32

The enumeration value for a 32-bit/4-byte IEEE 754 compatible floating point type.

NPY_DOUBLE
NPY_FLOAT64

The enumeration value for a 64-bit/8-byte IEEE 754 compatible floating point type.

NPY_LONGDOUBLE

The enumeration value for a platform-specific floating point type which is at least as large as NPY_DOUBLE, but larger on many platforms.

NPY_CFLOAT
NPY_COMPLEX64

The enumeration value for a 64-bit/8-byte complex type made up of two NPY_FLOAT values.

NPY_CDOUBLE
NPY_COMPLEX128

The enumeration value for a 128-bit/16-byte complex type made up of two NPY_DOUBLE values.

NPY_CLONGDOUBLE

The enumeration value for a platform-specific complex floating point type which is made up of two NPY_LONGDOUBLE values.

NPY_DATETIME

The enumeration value for a data type which holds dates or datetimes with a precision based on selectable date or time units.

NPY_TIMEDELTA

The enumeration value for a data type which holds lengths of times in integers of selectable date or time units.

NPY_STRING

The enumeration value for ASCII strings of a selectable size. The strings have a fixed maximum size within a given array.

NPY_UNICODE

The enumeration value for UCS4 strings of a selectable size. The strings have a fixed maximum size within a given array.

NPY_OBJECT

The enumeration value for references to arbitrary Python objects.

NPY_VOID

Primarily used to hold struct dtypes, but can contain arbitrary binary data.

Some useful aliases of the above types are

NPY_INTP

The enumeration value for a signed integer type which is the same size as a (void *) pointer. This is the type used by all arrays of indices.

NPY_UINTP

The enumeration value for an unsigned integer type which is the same size as a (void *) pointer.

NPY_MASK

The enumeration value of the type used for masks, such as with the NPY_ITER_ARRAYMASK iterator flag. This is equivalent to NPY_UINT8.

NPY_DEFAULT_TYPE

The default type to use when no dtype is explicitly specified, for example when calling np.zero(shape). This is equivalent to NPY_DOUBLE.

Other useful related constants are

NPY_NTYPES

The total number of built-in NumPy types. The enumeration covers the range from 0 to NPY_NTYPES-1.

NPY_NOTYPE

A signal value guaranteed not to be a valid type enumeration number.

NPY_USERDEF

The start of type numbers used for Custom Data types.

The various character codes indicating certain types are also part of an enumerated list. References to type characters (should they be needed at all) should always use these enumerations. The form of them is NPY_{NAME}LTR where {NAME} can be

BOOL, BYTE, UBYTE, SHORT, USHORT, INT, UINT, LONG, ULONG, LONGLONG, ULONGLONG, HALF, FLOAT, DOUBLE, LONGDOUBLE, CFLOAT, CDOUBLE, CLONGDOUBLE, DATETIME, TIMEDELTA, OBJECT, STRING, VOID

INTP, UINTP

GENBOOL, SIGNED, UNSIGNED, FLOATING, COMPLEX

The latter group of {NAME}s corresponds to letters used in the array interface typestring specification.

Defines

Max and min values for integers

NPY_MAX_INT{bits}
NPY_MAX_UINT{bits}
NPY_MIN_INT{bits}

These are defined for {bits} = 8, 16, 32, 64, 128, and 256 and provide the maximum (minimum) value of the corresponding (unsigned) integer type. Note: the actual integer type may not be available on all platforms (i.e. 128-bit and 256-bit integers are rare).

NPY_MIN_{type}

This is defined for {type} = BYTE, SHORT, INT, LONG, LONGLONG, INTP

NPY_MAX_{type}

This is defined for all defined for {type} = BYTE, UBYTE, SHORT, USHORT, INT, UINT, LONG, ULONG, LONGLONG, ULONGLONG, INTP, UINTP

Number of bits in data types

All NPY_SIZEOF_{CTYPE} constants have corresponding NPY_BITSOF_{CTYPE} constants defined. The NPY_BITSOF_{CTYPE} constants provide the number of bits in the data type. Specifically, the available {CTYPE}s are

BOOL, CHAR, SHORT, INT, LONG, LONGLONG, FLOAT, DOUBLE, LONGDOUBLE

Bit-width references to enumerated typenums

All of the numeric data types (integer, floating point, and complex) have constants that are defined to be a specific enumerated type number. Exactly which enumerated type a bit-width type refers to is platform dependent. In particular, the constants available are PyArray_{NAME}{BITS} where {NAME} is INT, UINT, FLOAT, COMPLEX and {BITS} can be 8, 16, 32, 64, 80, 96, 128, 160, 192, 256, and 512. Obviously not all bit-widths are available on all platforms for all the kinds of numeric types. Commonly 8-, 16-, 32-, 64-bit integers; 32-, 64-bit floats; and 64-, 128-bit complex types are available.

Integer that can hold a pointer

The constants NPY_INTP and NPY_UINTP refer to an enumerated integer type that is large enough to hold a pointer on the platform. Index arrays should always be converted to NPY_INTP , because the dimension of the array is of type npy_intp.

C-type names

There are standard variable types for each of the numeric data types and the bool data type. Some of these are already available in the C-specification. You can create variables in extension code with these types.

Boolean

npy_bool

unsigned char; The constants NPY_FALSE and NPY_TRUE are also defined.

(Un)Signed Integer

Unsigned versions of the integers can be defined by pre-pending a ‘u’ to the front of the integer name.

npy_(u)byte

(unsigned) char

npy_(u)short

(unsigned) short

npy_(u)int

(unsigned) int

npy_(u)long

(unsigned) long int

npy_(u)longlong

(unsigned long long int)

npy_(u)intp

(unsigned) Py_intptr_t (an integer that is the size of a pointer on the platform).

(Complex) Floating point

npy_(c)float

float

npy_(c)double

double

npy_(c)longdouble

long double

complex types are structures with .real and .imag members (in that order).

Bit-width names

There are also typedefs for signed integers, unsigned integers, floating point, and complex floating point types of specific bit- widths. The available type names are

npy_int{bits}, npy_uint{bits}, npy_float{bits}, and npy_complex{bits}

where {bits} is the number of bits in the type and can be 8, 16, 32, 64, 128, and 256 for integer types; 16, 32 , 64, 80, 96, 128, and 256 for floating-point types; and 32, 64, 128, 160, 192, and 512 for complex-valued types. Which bit-widths are available is platform dependent. The bolded bit-widths are usually available on all platforms.

Printf Formatting

For help in printing, the following strings are defined as the correct format specifier in printf and related commands.

NPY_LONGLONG_FMT, NPY_ULONGLONG_FMT, NPY_INTP_FMT, NPY_UINTP_FMT, NPY_LONGDOUBLE_FMT


Array API

  • Numpy C-API
  • next
  • previous

Table Of Contents

  • Array API
    • Array structure and data access
      • Data access
    • Creating arrays
      • From scratch
      • From other objects
    • Dealing with types
      • General check of Python Type
      • Data-type checking
      • Converting data types
      • New data types
      • Special functions for NPY_OBJECT
    • Array flags
      • Basic Array Flags
      • Combinations of array flags
      • Flag-like constants
      • Flag checking
    • Array method alternative API
      • Conversion
      • Shape Manipulation
      • Item selection and manipulation
      • Calculation
    • Functions
      • Array Functions
      • Other functions
    • Auxiliary Data With Object Semantics
    • Array Iterators
    • Broadcasting (multi-iterators)
    • Neighborhood iterator
    • Array Scalars
    • Data-type descriptors
    • Conversion Utilities
      • For use with PyArg_ParseTuple
      • Other conversions
    • Miscellaneous
      • Importing the API
      • Checking the API Version
      • Internal Flexibility
      • Memory management
      • Threading support
        • Group 1
        • Group 2
      • Priority
      • Default buffers
      • Other constants
      • Miscellaneous Macros
      • Enumerated Types

Previous topic

Data Type API

Next topic

Array Iterator API

Array API

The test of a first-rate intelligence is the ability to hold two
opposed ideas in the mind at the same time, and still retain the
ability to function.
— F. Scott Fitzgerald
For a successful technology, reality must take precedence over public
relations, for Nature cannot be fooled.
— Richard P. Feynman

Array structure and data access

These macros all access the PyArrayObject structure members. The input argument, arr, can be any PyObject * that is directly interpretable as a PyArrayObject * (any instance of the PyArray_Type and its sub-types).

int PyArray_NDIM( PyArrayObject *arr)

The number of dimensions in the array.

npy_intp *PyArray_DIMS( PyArrayObject *arr)

Returns a pointer to the dimensions/shape of the array. The number of elements matches the number of dimensions of the array.

npy_intp *PyArray_SHAPE( PyArrayObject *arr)

New in version 1.7.

A synonym for PyArray_DIMS, named to be consistent with the ‘shape’ usage within Python.

void *PyArray_DATA( PyArrayObject *arr)
char *PyArray_BYTES( PyArrayObject *arr)

These two macros are similar and obtain the pointer to the data-buffer for the array. The first macro can (and should be) assigned to a particular pointer where the second is for generic processing. If you have not guaranteed a contiguous and/or aligned array then be sure you understand how to access the data in the array to avoid memory and/or alignment problems.

npy_intp *PyArray_STRIDES( PyArrayObject* arr)

Returns a pointer to the strides of the array. The number of elements matches the number of dimensions of the array.

npy_intp PyArray_DIM( PyArrayObject* arr, int n)

Return the shape in the n [image] dimension.

npy_intp PyArray_STRIDE( PyArrayObject* arr, int n)

Return the stride in the n [image] dimension.

PyObject *PyArray_BASE( PyArrayObject* arr)

This returns the base object of the array. In most cases, this means the object which owns the memory the array is pointing at.

If you are constructing an array using the C API, and specifying your own memory, you should use the function PyArray_SetBaseObject to set the base to an object which owns the memory.

If the NPY_ARRAY_UPDATEIFCOPY flag is set, it has a different meaning, namely base is the array into which the current array will be copied upon destruction. This overloading of the base property for two functions is likely to change in a future version of NumPy.

PyArray_Descr *PyArray_DESCR( PyArrayObject* arr)

Returns a borrowed reference to the dtype property of the array.

PyArray_Descr *PyArray_DTYPE( PyArrayObject* arr)

New in version 1.7.

A synonym for PyArray_DESCR, named to be consistent with the ‘dtype’ usage within Python.

void PyArray_ENABLEFLAGS( PyArrayObject* arr, int flags)

New in version 1.7.

Enables the specified array flags. This function does no validation, and assumes that you know what you’re doing.

void PyArray_CLEARFLAGS( PyArrayObject* arr, int flags)

New in version 1.7.

Clears the specified array flags. This function does no validation, and assumes that you know what you’re doing.

int PyArray_FLAGS( PyArrayObject* arr)
int PyArray_ITEMSIZE( PyArrayObject* arr)

Return the itemsize for the elements of this array.

int PyArray_TYPE( PyArrayObject* arr)

Return the (builtin) typenumber for the elements of this array.

PyObject *PyArray_GETITEM( PyArrayObject* arr, void* itemptr)

Get a Python object from the ndarray, arr, at the location pointed to by itemptr. Return NULL on failure.

int PyArray_SETITEM( PyArrayObject* arr, void* itemptr, PyObject* obj)

Convert obj and place it in the ndarray, arr, at the place pointed to by itemptr. Return -1 if an error occurs or 0 on success.

npy_intp PyArray_SIZE( PyArrayObject* arr)

Returns the total size (in number of elements) of the array.

npy_intp PyArray_Size( PyArrayObject* obj)

Returns 0 if obj is not a sub-class of bigndarray. Otherwise, returns the total number of elements in the array. Safer version of PyArray_SIZE (obj).

npy_intp PyArray_NBYTES( PyArrayObject* arr)

Returns the total number of bytes consumed by the array.

Data access

These functions and macros provide easy access to elements of the ndarray from C. These work for all arrays. You may need to take care when accessing the data in the array, however, if it is not in machine byte-order, misaligned, or not writeable. In other words, be sure to respect the state of the flags unless you know what you are doing, or have previously guaranteed an array that is writeable, aligned, and in machine byte-order using PyArray_FromAny. If you wish to handle all types of arrays, the copyswap function for each type is useful for handling misbehaved arrays. Some platforms (e.g. Solaris) do not like misaligned data and will crash if you de-reference a misaligned pointer. Other platforms (e.g. x86 Linux) will just work more slowly with misaligned data.

void* PyArray_GetPtr( PyArrayObject* aobj, npy_intp* ind)

Return a pointer to the data of the ndarray, aobj, at the N-dimensional index given by the c-array, ind, (which must be at least aobj ->nd in size). You may want to typecast the returned pointer to the data type of the ndarray.

void* PyArray_GETPTR1( PyArrayObject* obj, npy_intp i)
void* PyArray_GETPTR2( PyArrayObject* obj, npy_intp i, npy_intp j)
void* PyArray_GETPTR3( PyArrayObject* obj, npy_intp i, npy_intp j, npy_intp k)
void* PyArray_GETPTR4( PyArrayObject* obj, npy_intp i, npy_intp j, npy_intp k, npy_intp l)

Quick, inline access to the element at the given coordinates in the ndarray, obj, which must have respectively 1, 2, 3, or 4 dimensions (this is not checked). The corresponding i, j, k, and l coordinates can be any integer but will be interpreted as npy_intp. You may want to typecast the returned pointer to the data type of the ndarray.

Creating arrays

From scratch

PyObject* PyArray_NewFromDescr( PyTypeObject* subtype, PyArray_Descr* descr, int nd, npy_intp* dims, npy_intp* strides, void* data, int flags, PyObject* obj)

This function steals a reference to descr.

This is the main array creation function. Most new arrays are created with this flexible function.

The returned object is an object of Python-type subtype, which must be a subtype of PyArray_Type. The array has nd dimensions, described by dims. The data-type descriptor of the new array is descr.

If subtype is of an array subclass instead of the base &PyArray_Type, then obj is the object to pass to the __array_finalize__ method of the subclass.

If data is NULL, then new memory will be allocated and flags can be non-zero to indicate a Fortran-style contiguous array. If data is not NULL, then it is assumed to point to the memory to be used for the array and the flags argument is used as the new flags for the array (except the state of NPY_OWNDATA and NPY_ARRAY_UPDATEIFCOPY flags of the new array will be reset).

In addition, if data is non-NULL, then strides can also be provided. If strides is NULL, then the array strides are computed as C-style contiguous (default) or Fortran-style contiguous (flags is nonzero for data = NULL or flags & NPY_ARRAY_F_CONTIGUOUS is nonzero non-NULL data). Any provided dims and strides are copied into newly allocated dimension and strides arrays for the new array object.

PyObject* PyArray_NewLikeArray( PyArrayObject* prototype, NPY_ORDER order, PyArray_Descr* descr, int subok)

New in version 1.6.

This function steals a reference to descr if it is not NULL.

This array creation routine allows for the convenient creation of a new array matching an existing array’s shapes and memory layout, possibly changing the layout and/or data type.

When order is NPY_ANYORDER, the result order is NPY_FORTRANORDER if prototype is a fortran array, NPY_CORDER otherwise. When order is NPY_KEEPORDER, the result order matches that of prototype, even when the axes of prototype aren’t in C or Fortran order.

If descr is NULL, the data type of prototype is used.

If subok is 1, the newly created array will use the sub-type of prototype to create the new array, otherwise it will create a base-class array.

PyObject* PyArray_New( PyTypeObject* subtype, int nd, npy_intp* dims, int type_num, npy_intp* strides, void* data, int itemsize, int flags, PyObject* obj)

This is similar to PyArray_DescrNew (...) except you specify the data-type descriptor with type_num and itemsize, where type_num corresponds to a builtin (or user-defined) type. If the type always has the same number of bytes, then itemsize is ignored. Otherwise, itemsize specifies the particular size of this array.

Warning

If data is passed to PyArray_NewFromDescr or PyArray_New, this memory must not be deallocated until the new array is deleted. If this data came from another Python object, this can be accomplished using Py_INCREF on that object and setting the base member of the new array to point to that object. If strides are passed in they must be consistent with the dimensions, the itemsize, and the data of the array.

PyObject* PyArray_SimpleNew(int nd, npy_intp* dims, int typenum)

Create a new unitialized array of type, typenum, whose size in each of nd dimensions is given by the integer array, dims. This function cannot be used to create a flexible-type array (no itemsize given).

PyObject* PyArray_SimpleNewFromData(int nd, npy_intp* dims, int typenum, void* data)

Create an array wrapper around data pointed to by the given pointer. The array flags will have a default that the data area is well-behaved and C-style contiguous. The shape of the array is given by the dims c-array of length nd. The data-type of the array is indicated by typenum.

PyObject* PyArray_SimpleNewFromDescr(int nd, npy_intp* dims, PyArray_Descr* descr)

This function steals a reference to descr if it is not NULL.

Create a new array with the provided data-type descriptor, descr , of the shape deteremined by nd and dims.

PyArray_FILLWBYTE( PyObject* obj, int val)

Fill the array pointed to by obj —which must be a (subclass of) bigndarray—with the contents of val (evaluated as a byte). This macro calls memset, so obj must be contiguous.

PyObject* PyArray_Zeros(int nd, npy_intp* dims, PyArray_Descr* dtype, int fortran)

Construct a new nd -dimensional array with shape given by dims and data type given by dtype. If fortran is non-zero, then a Fortran-order array is created, otherwise a C-order array is created. Fill the memory with zeros (or the 0 object if dtype corresponds to NPY_OBJECT ).

PyObject* PyArray_ZEROS(int nd, npy_intp* dims, int type_num, int fortran)

Macro form of PyArray_Zeros which takes a type-number instead of a data-type object.

PyObject* PyArray_Empty(int nd, npy_intp* dims, PyArray_Descr* dtype, int fortran)

Construct a new nd -dimensional array with shape given by dims and data type given by dtype. If fortran is non-zero, then a Fortran-order array is created, otherwise a C-order array is created. The array is uninitialized unless the data type corresponds to NPY_OBJECT in which case the array is filled with Py_None.

PyObject* PyArray_EMPTY(int nd, npy_intp* dims, int typenum, int fortran)

Macro form of PyArray_Empty which takes a type-number, typenum, instead of a data-type object.

PyObject* PyArray_Arange(double start, double stop, double step, int typenum)

Construct a new 1-dimensional array of data-type, typenum, that ranges from start to stop (exclusive) in increments of step . Equivalent to arange (start, stop, step, dtype).

PyObject* PyArray_ArangeObj( PyObject* start, PyObject* stop, PyObject* step, PyArray_Descr* descr)

Construct a new 1-dimensional array of data-type determined by descr, that ranges from start to stop (exclusive) in increments of step. Equivalent to arange( start, stop, step, typenum ).

int PyArray_SetBaseObject( PyArrayObject* arr, PyObject* obj)

New in version 1.7.

This function steals a reference to obj and sets it as the base property of arr.

If you construct an array by passing in your own memory buffer as a parameter, you need to set the array’s base property to ensure the lifetime of the memory buffer is appropriate.

The return value is 0 on success, -1 on failure.

If the object provided is an array, this function traverses the chain of base pointers so that each array points to the owner of the memory directly. Once the base is set, it may not be changed to another value.

From other objects

PyObject* PyArray_FromAny( PyObject* op, PyArray_Descr* dtype, int min_depth, int max_depth, int requirements, PyObject* context)

This is the main function used to obtain an array from any nested sequence, or object that exposes the array interface, op. The parameters allow specification of the required dtype, the minimum (min_depth) and maximum (max_depth) number of dimensions acceptable, and other requirements for the array. The dtype argument needs to be a PyArray_Descr structure indicating the desired data-type (including required byteorder). The dtype argument may be NULL, indicating that any data-type (and byteorder) is acceptable. Unless FORCECAST is present in flags, this call will generate an error if the data type cannot be safely obtained from the object. If you want to use NULL for the dtype and ensure the array is notswapped then use PyArray_CheckFromAny. A value of 0 for either of the depth parameters causes the parameter to be ignored. Any of the following array flags can be added (e.g. using |) to get the requirements argument. If your code can handle general (e.g. strided, byte-swapped, or unaligned arrays) then requirements may be 0. Also, if op is not already an array (or does not expose the array interface), then a new array will be created (and filled from op using the sequence protocol). The new array will have NPY_DEFAULT as its flags member. The context argument is passed to the __array__ method of op and is only used if the array is constructed that way. Almost always this parameter is NULL.

In versions 1.6 and earlier of NumPy, the following flags did not have the _ARRAY_ macro namespace in them. That form of the constant names is deprecated in 1.7.

NPY_ARRAY_C_CONTIGUOUS

Make sure the returned array is C-style contiguous

NPY_ARRAY_F_CONTIGUOUS

Make sure the returned array is Fortran-style contiguous.

NPY_ARRAY_ALIGNED

Make sure the returned array is aligned on proper boundaries for its data type. An aligned array has the data pointer and every strides factor as a multiple of the alignment factor for the data-type- descriptor.

NPY_ARRAY_WRITEABLE

Make sure the returned array can be written to.

NPY_ARRAY_ENSURECOPY

Make sure a copy is made of op. If this flag is not present, data is not copied if it can be avoided.

NPY_ARRAY_ENSUREARRAY

Make sure the result is a base-class ndarray or bigndarray. By default, if op is an instance of a subclass of the bigndarray, an instance of that same subclass is returned. If this flag is set, an ndarray object will be returned instead.

NPY_ARRAY_FORCECAST

Force a cast to the output type even if it cannot be done safely. Without this flag, a data cast will occur only if it can be done safely, otherwise an error is reaised.

NPY_ARRAY_UPDATEIFCOPY

If op is already an array, but does not satisfy the requirements, then a copy is made (which will satisfy the requirements). If this flag is present and a copy (of an object that is already an array) must be made, then the corresponding NPY_ARRAY_UPDATEIFCOPY flag is set in the returned copy and op is made to be read-only. When the returned copy is deleted (presumably after your calculations are complete), its contents will be copied back into op and the op array will be made writeable again. If op is not writeable to begin with, then an error is raised. If op is not already an array, then this flag has no effect.

NPY_ARRAY_BEHAVED

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE

NPY_ARRAY_CARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_CARRAY_RO

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_FARRAY_RO

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_DEFAULT

NPY_ARRAY_CARRAY

NPY_ARRAY_IN_ARRAY

NPY_ARRAY_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_IN_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_OUT_ARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED

NPY_ARRAY_OUT_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED

NPY_ARRAY_INOUT_ARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED | NPY_ARRAY_UPDATEIFCOPY

NPY_ARRAY_INOUT_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_WRITEABLE | NPY_ARRAY_ALIGNED | NPY_ARRAY_UPDATEIFCOPY

int PyArray_GetArrayParamsFromObject( PyObject* op, PyArray_Descr* requested_dtype, npy_bool writeable, PyArray_Descr** out_dtype, int* out_ndim, npy_intp* out_dims, PyArrayObject** out_arr, PyObject* context)

New in version 1.6.

Retrieves the array parameters for viewing/converting an arbitrary PyObject* to a NumPy array. This allows the “innate type and shape” of Python list-of-lists to be discovered without actually converting to an array. PyArray_FromAny calls this function to analyze its input.

In some cases, such as structured arrays and the __array__ interface, a data type needs to be used to make sense of the object. When this is needed, provide a Descr for ‘requested_dtype’, otherwise provide NULL. This reference is not stolen. Also, if the requested dtype doesn’t modify the interpretation of the input, out_dtype will still get the “innate” dtype of the object, not the dtype passed in ‘requested_dtype’.

If writing to the value in ‘op’ is desired, set the boolean ‘writeable’ to 1. This raises an error when ‘op’ is a scalar, list of lists, or other non-writeable ‘op’. This differs from passing NPY_ARRAY_WRITEABLE to PyArray_FromAny, where the writeable array may be a copy of the input.

When success (0 return value) is returned, either out_arr is filled with a non-NULL PyArrayObject and the rest of the parameters are untouched, or out_arr is filled with NULL, and the rest of the parameters are filled.

Typical usage:

PyArrayObject *arr = NULL;
PyArray_Descr *dtype = NULL;
int ndim = 0;
npy_intp dims[NPY_MAXDIMS];

if (PyArray_GetArrayParamsFromObject(op, NULL, 1, &dtype,
                                    &ndim, &dims, &arr, NULL) < 0) {
    return NULL;
}
if (arr == NULL) {
    ... validate/change dtype, validate flags, ndim, etc ...
    // Could make custom strides here too
    arr = PyArray_NewFromDescr(&PyArray_Type, dtype, ndim,
                                dims, NULL,
                                fortran ? NPY_ARRAY_F_CONTIGUOUS : 0,
                                NULL);
    if (arr == NULL) {
        return NULL;
    }
    if (PyArray_CopyObject(arr, op) < 0) {
        Py_DECREF(arr);
        return NULL;
    }
}
else {
    ... in this case the other parameters weren't filled, just
        validate and possibly copy arr itself ...
}
... use arr ...
PyObject* PyArray_CheckFromAny( PyObject* op, PyArray_Descr* dtype, int min_depth, int max_depth, int requirements, PyObject* context)

Nearly identical to PyArray_FromAny (...) except requirements can contain NPY_ARRAY_NOTSWAPPED (over-riding the specification in dtype) and NPY_ARRAY_ELEMENTSTRIDES which indicates that the array should be aligned in the sense that the strides are multiples of the element size.

In versions 1.6 and earlier of NumPy, the following flags did not have the _ARRAY_ macro namespace in them. That form of the constant names is deprecated in 1.7.

NPY_ARRAY_NOTSWAPPED

Make sure the returned array has a data-type descriptor that is in machine byte-order, over-riding any specification in the dtype argument. Normally, the byte-order requirement is determined by the dtype argument. If this flag is set and the dtype argument does not indicate a machine byte-order descriptor (or is NULL and the object is already an array with a data-type descriptor that is not in machine byte- order), then a new data-type descriptor is created and used with its byte-order field set to native.

NPY_ARRAY_BEHAVED_NS

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE | NPY_ARRAY_NOTSWAPPED

NPY_ARRAY_ELEMENTSTRIDES

Make sure the returned array has strides that are multiples of the element size.

PyObject* PyArray_FromArray( PyArrayObject* op, PyArray_Descr* newtype, int requirements)

Special case of PyArray_FromAny for when op is already an array but it needs to be of a specific newtype (including byte-order) or has certain requirements.

PyObject* PyArray_FromStructInterface( PyObject* op)

Returns an ndarray object from a Python object that exposes the __array_struct__` method and follows the array interface protocol. If the object does not contain this method then a borrowed reference to Py_NotImplemented is returned.

PyObject* PyArray_FromInterface( PyObject* op)

Returns an ndarray object from a Python object that exposes the __array_shape__ and __array_typestr__ methods following the array interface protocol. If the object does not contain one of these method then a borrowed reference to Py_NotImplemented is returned.

PyObject* PyArray_FromArrayAttr( PyObject* op, PyArray_Descr* dtype, PyObject* context)

Return an ndarray object from a Python object that exposes the __array__ method. The __array__ method can take 0, 1, or 2 arguments ([dtype, context]) where context is used to pass information about where the __array__ method is being called from (currently only used in ufuncs).

PyObject* PyArray_ContiguousFromAny( PyObject* op, int typenum, int min_depth, int max_depth)

This function returns a (C-style) contiguous and behaved function array from any nested sequence or array interface exporting object, op, of (non-flexible) type given by the enumerated typenum, of minimum depth min_depth, and of maximum depth max_depth. Equivalent to a call to PyArray_FromAny with requirements set to NPY_DEFAULT and the type_num member of the type argument set to typenum.

PyObject *PyArray_FromObject( PyObject *op, int typenum, int min_depth, int max_depth)

Return an aligned and in native-byteorder array from any nested sequence or array-interface exporting object, op, of a type given by the enumerated typenum. The minimum number of dimensions the array can have is given by min_depth while the maximum is max_depth. This is equivalent to a call to PyArray_FromAny with requirements set to BEHAVED.

PyObject* PyArray_EnsureArray( PyObject* op)

This function steals a reference to op and makes sure that op is a base-class ndarray. It special cases array scalars, but otherwise calls PyArray_FromAny ( op, NULL, 0, 0, NPY_ARRAY_ENSUREARRAY).

PyObject* PyArray_FromString(char* string, npy_intp slen, PyArray_Descr* dtype, npy_intp num, char* sep)

Construct a one-dimensional ndarray of a single type from a binary or (ASCII) text string of length slen. The data-type of the array to-be-created is given by dtype. If num is -1, then copy the entire string and return an appropriately sized array, otherwise, num is the number of items to copy from the string. If sep is NULL (or “”), then interpret the string as bytes of binary data, otherwise convert the sub-strings separated by sep to items of data-type dtype. Some data-types may not be readable in text mode and an error will be raised if that occurs. All errors return NULL.

PyObject* PyArray_FromFile(FILE* fp, PyArray_Descr* dtype, npy_intp num, char* sep)

Construct a one-dimensional ndarray of a single type from a binary or text file. The open file pointer is fp, the data-type of the array to be created is given by dtype. This must match the data in the file. If num is -1, then read until the end of the file and return an appropriately sized array, otherwise, num is the number of items to read. If sep is NULL (or “”), then read from the file in binary mode, otherwise read from the file in text mode with sep providing the item separator. Some array types cannot be read in text mode in which case an error is raised.

PyObject* PyArray_FromBuffer( PyObject* buf, PyArray_Descr* dtype, npy_intp count, npy_intp offset)

Construct a one-dimensional ndarray of a single type from an object, buf, that exports the (single-segment) buffer protocol (or has an attribute __buffer__ that returns an object that exports the buffer protocol). A writeable buffer will be tried first followed by a read- only buffer. The NPY_ARRAY_WRITEABLE flag of the returned array will reflect which one was successful. The data is assumed to start at offset bytes from the start of the memory location for the object. The type of the data in the buffer will be interpreted depending on the data- type descriptor, dtype. If count is negative then it will be determined from the size of the buffer and the requested itemsize, otherwise, count represents how many elements should be converted from the buffer.

int PyArray_CopyInto( PyArrayObject* dest, PyArrayObject* src)

Copy from the source array, src, into the destination array, dest, performing a data-type conversion if necessary. If an error occurs return -1 (otherwise 0). The shape of src must be broadcastable to the shape of dest. The data areas of dest and src must not overlap.

int PyArray_MoveInto( PyArrayObject* dest, PyArrayObject* src)

Move data from the source array, src, into the destination array, dest, performing a data-type conversion if necessary. If an error occurs return -1 (otherwise 0). The shape of src must be broadcastable to the shape of dest. The data areas of dest and src may overlap.

PyArrayObject* PyArray_GETCONTIGUOUS( PyObject* op)

If op is already (C-style) contiguous and well-behaved then just return a reference, otherwise return a (contiguous and well-behaved) copy of the array. The parameter op must be a (sub-class of an) ndarray and no checking for that is done.

PyObject* PyArray_FROM_O( PyObject* obj)

Convert obj to an ndarray. The argument can be any nested sequence or object that exports the array interface. This is a macro form of PyArray_FromAny using NULL, 0, 0, 0 for the other arguments. Your code must be able to handle any data-type descriptor and any combination of data-flags to use this macro.

PyObject* PyArray_FROM_OF( PyObject* obj, int requirements)

Similar to PyArray_FROM_O except it can take an argument of requirements indicating properties the resulting array must have. Available requirements that can be enforced are NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_F_CONTIGUOUS, NPY_ARRAY_ALIGNED, NPY_ARRAY_WRITEABLE, NPY_ARRAY_NOTSWAPPED, NPY_ARRAY_ENSURECOPY, NPY_ARRAY_UPDATEIFCOPY, NPY_ARRAY_FORCECAST, and NPY_ARRAY_ENSUREARRAY. Standard combinations of flags can also be used:

PyObject* PyArray_FROM_OT( PyObject* obj, int typenum)

Similar to PyArray_FROM_O except it can take an argument of typenum specifying the type-number the returned array.

PyObject* PyArray_FROM_OTF( PyObject* obj, int typenum, int requirements)

Combination of PyArray_FROM_OF and PyArray_FROM_OT allowing both a typenum and a flags argument to be provided..

PyObject* PyArray_FROMANY( PyObject* obj, int typenum, int min, int max, int requirements)

Similar to PyArray_FromAny except the data-type is specified using a typenumber. PyArray_DescrFromType (typenum) is passed directly to PyArray_FromAny. This macro also adds NPY_DEFAULT to requirements if NPY_ARRAY_ENSURECOPY is passed in as requirements.

PyObject *PyArray_CheckAxis( PyObject* obj, int* axis, int requirements)

Encapsulate the functionality of functions and methods that take the axis= keyword and work properly with None as the axis argument. The input array is obj, while *axis is a converted integer (so that >=MAXDIMS is the None value), and requirements gives the needed properties of obj. The output is a converted version of the input so that requirements are met and if needed a flattening has occurred. On output negative values of *axis are converted and the new value is checked to ensure consistency with the shape of obj.

Dealing with types

General check of Python Type

PyArray_Check(op)

Evaluates true if op is a Python object whose type is a sub-type of PyArray_Type.

PyArray_CheckExact(op)

Evaluates true if op is a Python object with type PyArray_Type.

PyArray_HasArrayInterface(op, out)

If op implements any part of the array interface, then out will contain a new reference to the newly created ndarray using the interface or out will contain NULL if an error during conversion occurs. Otherwise, out will contain a borrowed reference to Py_NotImplemented and no error condition is set.

PyArray_HasArrayInterfaceType(op, type, context, out)

If op implements any part of the array interface, then out will contain a new reference to the newly created ndarray using the interface or out will contain NULL if an error during conversion occurs. Otherwise, out will contain a borrowed reference to Py_NotImplemented and no error condition is set. This version allows setting of the type and context in the part of the array interface that looks for the __array__ attribute.

PyArray_IsZeroDim(op)

Evaluates true if op is an instance of (a subclass of) PyArray_Type and has 0 dimensions.

PyArray_IsScalar(op, cls)

Evaluates true if op is an instance of Py{cls}ArrType_Type.

PyArray_CheckScalar(op)

Evaluates true if op is either an array scalar (an instance of a sub-type of PyGenericArr_Type ), or an instance of (a sub-class of) PyArray_Type whose dimensionality is 0.

PyArray_IsPythonScalar(op)

Evaluates true if op is a builtin Python “scalar” object (int, float, complex, str, unicode, long, bool).

PyArray_IsAnyScalar(op)

Evaluates true if op is either a Python scalar or an array scalar (an instance of a sub- type of PyGenericArr_Type ).

Data-type checking

For the typenum macros, the argument is an integer representing an enumerated array data type. For the array type checking macros the argument must be a PyObject * that can be directly interpreted as a PyArrayObject *.

PyTypeNum_ISUNSIGNED(num)
PyDataType_ISUNSIGNED(descr)
PyArray_ISUNSIGNED(obj)

Type represents an unsigned integer.

PyTypeNum_ISSIGNED(num)
PyDataType_ISSIGNED(descr)
PyArray_ISSIGNED(obj)

Type represents a signed integer.

PyTypeNum_ISINTEGER(num)
PyDataType_ISINTEGER(descr)
PyArray_ISINTEGER(obj)

Type represents any integer.

PyTypeNum_ISFLOAT(num)
PyDataType_ISFLOAT(descr)
PyArray_ISFLOAT(obj)

Type represents any floating point number.

PyTypeNum_ISCOMPLEX(num)
PyDataType_ISCOMPLEX(descr)
PyArray_ISCOMPLEX(obj)

Type represents any complex floating point number.

PyTypeNum_ISNUMBER(num)
PyDataType_ISNUMBER(descr)
PyArray_ISNUMBER(obj)

Type represents any integer, floating point, or complex floating point number.

PyTypeNum_ISSTRING(num)
PyDataType_ISSTRING(descr)
PyArray_ISSTRING(obj)

Type represents a string data type.

PyTypeNum_ISPYTHON(num)
PyDataType_ISPYTHON(descr)
PyArray_ISPYTHON(obj)

Type represents an enumerated type corresponding to one of the standard Python scalar (bool, int, float, or complex).

PyTypeNum_ISFLEXIBLE(num)
PyDataType_ISFLEXIBLE(descr)
PyArray_ISFLEXIBLE(obj)

Type represents one of the flexible array types ( NPY_STRING, NPY_UNICODE, or NPY_VOID ).

PyTypeNum_ISUSERDEF(num)
PyDataType_ISUSERDEF(descr)
PyArray_ISUSERDEF(obj)

Type represents a user-defined type.

PyTypeNum_ISEXTENDED(num)
PyDataType_ISEXTENDED(descr)
PyArray_ISEXTENDED(obj)

Type is either flexible or user-defined.

PyTypeNum_ISOBJECT(num)
PyDataType_ISOBJECT(descr)
PyArray_ISOBJECT(obj)

Type represents object data type.

PyTypeNum_ISBOOL(num)
PyDataType_ISBOOL(descr)
PyArray_ISBOOL(obj)

Type represents Boolean data type.

PyDataType_HASFIELDS(descr)
PyArray_HASFIELDS(obj)

Type has fields associated with it.

PyArray_ISNOTSWAPPED(m)

Evaluates true if the data area of the ndarray m is in machine byte-order according to the array’s data-type descriptor.

PyArray_ISBYTESWAPPED(m)

Evaluates true if the data area of the ndarray m is not in machine byte-order according to the array’s data-type descriptor.

Bool PyArray_EquivTypes( PyArray_Descr* type1, PyArray_Descr* type2)

Return NPY_TRUE if type1 and type2 actually represent equivalent types for this platform (the fortran member of each type is ignored). For example, on 32-bit platforms, NPY_LONG and NPY_INT are equivalent. Otherwise return NPY_FALSE.

Bool PyArray_EquivArrTypes( PyArrayObject* a1, PyArrayObject * a2)

Return NPY_TRUE if a1 and a2 are arrays with equivalent types for this platform.

Bool PyArray_EquivTypenums(int typenum1, int typenum2)

Special case of PyArray_EquivTypes (...) that does not accept flexible data types but may be easier to call.

int PyArray_EquivByteorders({byteorder} b1, {byteorder} b2)

True if byteorder characters ( NPY_LITTLE, NPY_BIG, NPY_NATIVE, NPY_IGNORE ) are either equal or equivalent as to their specification of a native byte order. Thus, on a little-endian machine NPY_LITTLE and NPY_NATIVE are equivalent where they are not equivalent on a big-endian machine.

Converting data types

PyObject* PyArray_Cast( PyArrayObject* arr, int typenum)

Mainly for backwards compatibility to the Numeric C-API and for simple casts to non-flexible types. Return a new array object with the elements of arr cast to the data-type typenum which must be one of the enumerated types and not a flexible type.

PyObject* PyArray_CastToType( PyArrayObject* arr, PyArray_Descr* type, int fortran)

Return a new array of the type specified, casting the elements of arr as appropriate. The fortran argument specifies the ordering of the output array.

int PyArray_CastTo( PyArrayObject* out, PyArrayObject* in)

As of 1.6, this function simply calls PyArray_CopyInto, which handles the casting.

Cast the elements of the array in into the array out. The output array should be writeable, have an integer-multiple of the number of elements in the input array (more than one copy can be placed in out), and have a data type that is one of the builtin types. Returns 0 on success and -1 if an error occurs.

PyArray_VectorUnaryFunc* PyArray_GetCastFunc( PyArray_Descr* from, int totype)

Return the low-level casting function to cast from the given descriptor to the builtin type number. If no casting function exists return NULL and set an error. Using this function instead of direct access to from ->f->cast will allow support of any user-defined casting functions added to a descriptors casting dictionary.

int PyArray_CanCastSafely(int fromtype, int totype)

Returns non-zero if an array of data type fromtype can be cast to an array of data type totype without losing information. An exception is that 64-bit integers are allowed to be cast to 64-bit floating point values even though this can lose precision on large integers so as not to proliferate the use of long doubles without explict requests. Flexible array types are not checked according to their lengths with this function.

int PyArray_CanCastTo( PyArray_Descr* fromtype, PyArray_Descr* totype)

PyArray_CanCastTypeTo supercedes this function in NumPy 1.6 and later.

Equivalent to PyArray_CanCastTypeTo(fromtype, totype, NPY_SAFE_CASTING).

int PyArray_CanCastTypeTo( PyArray_Descr* fromtype, PyArray_Descr* totype, NPY_CASTING casting)

New in version 1.6.

Returns non-zero if an array of data type fromtype (which can include flexible types) can be cast safely to an array of data type totype (which can include flexible types) according to the casting rule casting. For simple types with NPY_SAFE_CASTING, this is basically a wrapper around PyArray_CanCastSafely, but for flexible types such as strings or unicode, it produces results taking into account their sizes. Integer and float types can only be cast to a string or unicode type using NPY_SAFE_CASTING if the string or unicode type is big enough to hold the max value of the integer/float type being cast from.

int PyArray_CanCastArrayTo( PyArrayObject* arr, PyArray_Descr* totype, NPY_CASTING casting)

New in version 1.6.

Returns non-zero if arr can be cast to totype according to the casting rule given in casting. If arr is an array scalar, its value is taken into account, and non-zero is also returned when the value will not overflow or be truncated to an integer when converting to a smaller type.

This is almost the same as the result of PyArray_CanCastTypeTo(PyArray_MinScalarType(arr), totype, casting), but it also handles a special case arising because the set of uint values is not a subset of the int values for types with the same number of bits.

PyArray_Descr* PyArray_MinScalarType( PyArrayObject* arr)

New in version 1.6.

If arr is an array, returns its data type descriptor, but if arr is an array scalar (has 0 dimensions), it finds the data type of smallest size to which the value may be converted without overflow or truncation to an integer.

This function will not demote complex to float or anything to boolean, but will demote a signed integer to an unsigned integer when the scalar value is positive.

PyArray_Descr* PyArray_PromoteTypes( PyArray_Descr* type1, PyArray_Descr* type2)

New in version 1.6.

Finds the data type of smallest size and kind to which type1 and type2 may be safely converted. This function is symmetric and associative. A string or unicode result will be the proper size for storing the max value of the input types converted to a string or unicode.

PyArray_Descr* PyArray_ResultType(npy_intp narrs, PyArrayObject**arrs, npy_intp ndtypes, PyArray_Descr**dtypes)

New in version 1.6.

This applies type promotion to all the inputs, using the NumPy rules for combining scalars and arrays, to determine the output type of a set of operands. This is the same result type that ufuncs produce. The specific algorithm used is as follows.

Categories are determined by first checking which of boolean, integer (int/uint), or floating point (float/complex) the maximum kind of all the arrays and the scalars are.

If there are only scalars or the maximum category of the scalars is higher than the maximum category of the arrays, the data types are combined with PyArray_PromoteTypes to produce the return value.

Otherwise, PyArray_MinScalarType is called on each array, and the resulting data types are all combined with PyArray_PromoteTypes to produce the return value.

The set of int values is not a subset of the uint values for types with the same number of bits, something not reflected in PyArray_MinScalarType, but handled as a special case in PyArray_ResultType.

int PyArray_ObjectType( PyObject* op, int mintype)

This function is superceded by PyArray_MinScalarType and/or PyArray_ResultType.

This function is useful for determining a common type that two or more arrays can be converted to. It only works for non-flexible array types as no itemsize information is passed. The mintype argument represents the minimum type acceptable, and op represents the object that will be converted to an array. The return value is the enumerated typenumber that represents the data-type that op should have.

void PyArray_ArrayType( PyObject* op, PyArray_Descr* mintype, PyArray_Descr* outtype)

This function is superceded by PyArray_ResultType.

This function works similarly to PyArray_ObjectType (...) except it handles flexible arrays. The mintype argument can have an itemsize member and the outtype argument will have an itemsize member at least as big but perhaps bigger depending on the object op.

PyArrayObject** PyArray_ConvertToCommonType( PyObject* op, int* n)

The functionality this provides is largely superceded by iterator NpyIter introduced in 1.6, with flag NPY_ITER_COMMON_DTYPE or with the same dtype parameter for all operands.

Convert a sequence of Python objects contained in op to an array of ndarrays each having the same data type. The type is selected based on the typenumber (larger type number is chosen over a smaller one) ignoring objects that are only scalars. The length of the sequence is returned in n, and an n -length array of PyArrayObject pointers is the return value (or NULL if an error occurs). The returned array must be freed by the caller of this routine (using PyDataMem_FREE ) and all the array objects in it DECREF ‘d or a memory-leak will occur. The example template-code below shows a typically usage:

mps = PyArray_ConvertToCommonType(obj, &n);
if (mps==NULL) return NULL;
{code}
<before return>
for (i=0; i<n; i++) Py_DECREF(mps[i]);
PyDataMem_FREE(mps);
{return}
char* PyArray_Zero( PyArrayObject* arr)

A pointer to newly created memory of size arr ->itemsize that holds the representation of 0 for that type. The returned pointer, ret, must be freed using PyDataMem_FREE (ret) when it is not needed anymore.

char* PyArray_One( PyArrayObject* arr)

A pointer to newly created memory of size arr ->itemsize that holds the representation of 1 for that type. The returned pointer, ret, must be freed using PyDataMem_FREE (ret) when it is not needed anymore.

int PyArray_ValidType(int typenum)

Returns NPY_TRUE if typenum represents a valid type-number (builtin or user-defined or character code). Otherwise, this function returns NPY_FALSE.

New data types

void PyArray_InitArrFuncs( PyArray_ArrFuncs* f)

Initialize all function pointers and members to NULL.

int PyArray_RegisterDataType( PyArray_Descr* dtype)

Register a data-type as a new user-defined data type for arrays. The type must have most of its entries filled in. This is not always checked and errors can produce segfaults. In particular, the typeobj member of the dtype structure must be filled with a Python type that has a fixed-size element-size that corresponds to the elsize member of dtype. Also the f member must have the required functions: nonzero, copyswap, copyswapn, getitem, setitem, and cast (some of the cast functions may be NULL if no support is desired). To avoid confusion, you should choose a unique character typecode but this is not enforced and not relied on internally.

A user-defined type number is returned that uniquely identifies the type. A pointer to the new structure can then be obtained from PyArray_DescrFromType using the returned type number. A -1 is returned if an error occurs. If this dtype has already been registered (checked only by the address of the pointer), then return the previously-assigned type-number.

int PyArray_RegisterCastFunc( PyArray_Descr* descr, int totype, PyArray_VectorUnaryFunc* castfunc)

Register a low-level casting function, castfunc, to convert from the data-type, descr, to the given data-type number, totype. Any old casting function is over-written. A 0 is returned on success or a -1 on failure.

int PyArray_RegisterCanCast( PyArray_Descr* descr, int totype, NPY_SCALARKIND scalar)

Register the data-type number, totype, as castable from data-type object, descr, of the given scalar kind. Use scalar = NPY_NOSCALAR to register that an array of data-type descr can be cast safely to a data-type whose type_number is totype.

Special functions for NPY_OBJECT

int PyArray_INCREF( PyArrayObject* op)

Used for an array, op, that contains any Python objects. It increments the reference count of every object in the array according to the data-type of op. A -1 is returned if an error occurs, otherwise 0 is returned.

void PyArray_Item_INCREF(char* ptr, PyArray_Descr* dtype)

A function to INCREF all the objects at the location ptr according to the data-type dtype. If ptr is the start of a record with an object at any offset, then this will (recursively) increment the reference count of all object-like items in the record.

int PyArray_XDECREF( PyArrayObject* op)

Used for an array, op, that contains any Python objects. It decrements the reference count of every object in the array according to the data-type of op. Normal return value is 0. A -1 is returned if an error occurs.

void PyArray_Item_XDECREF(char* ptr, PyArray_Descr* dtype)

A function to XDECREF all the object-like items at the loacation ptr as recorded in the data-type, dtype. This works recursively so that if dtype itself has fields with data-types that contain object-like items, all the object-like fields will be XDECREF 'd.

void PyArray_FillObjectArray( PyArrayObject* arr, PyObject* obj)

Fill a newly created array with a single value obj at all locations in the structure with object data-types. No checking is performed but arr must be of data-type NPY_OBJECT and be single-segment and uninitialized (no previous objects in position). Use PyArray_DECREF (arr) if you need to decrement all the items in the object array prior to calling this function.

Array flags

The flags attribute of the PyArrayObject structure contains important information about the memory used by the array (pointed to by the data member) This flag information must be kept accurate or strange results and even segfaults may result.

There are 6 (binary) flags that describe the memory area used by the data buffer. These constants are defined in arrayobject.h and determine the bit-position of the flag. Python exposes a nice attribute- based interface as well as a dictionary-like interface for getting (and, if appropriate, setting) these flags.

Memory areas of all kinds can be pointed to by an ndarray, necessitating these flags. If you get an arbitrary PyArrayObject in C-code, you need to be aware of the flags that are set. If you need to guarantee a certain kind of array (like NPY_ARRAY_C_CONTIGUOUS and NPY_ARRAY_BEHAVED), then pass these requirements into the PyArray_FromAny function.

Basic Array Flags

An ndarray can have a data segment that is not a simple contiguous chunk of well-behaved memory you can manipulate. It may not be aligned with word boundaries (very important on some platforms). It might have its data in a different byte-order than the machine recognizes. It might not be writeable. It might be in Fortan-contiguous order. The array flags are used to indicate what can be said about data associated with an array.

In versions 1.6 and earlier of NumPy, the following flags did not have the _ARRAY_ macro namespace in them. That form of the constant names is deprecated in 1.7.

NPY_ARRAY_C_CONTIGUOUS

The data area is in C-style contiguous order (last index varies the fastest).

NPY_ARRAY_F_CONTIGUOUS

The data area is in Fortran-style contiguous order (first index varies the fastest).

Note

Arrays can be both C-style and Fortran-style contiguous simultaneously. This is clear for 1-dimensional arrays, but can also be true for higher dimensional arrays.

Even for contiguous arrays a stride for a given dimension arr.strides[dim] may be arbitrary if arr.shape[dim] == 1 or the array has no elements. It does not generally hold that self.strides[-1] == self.itemsize for C-style contiguous arrays or self.strides[0] == self.itemsize for Fortran-style contiguous arrays is true. The correct way to access the itemsize of an array from the C API is PyArray_ITEMSIZE(arr).

See also

Internal memory layout of an ndarray

NPY_ARRAY_OWNDATA

The data area is owned by this array.

NPY_ARRAY_ALIGNED

The data area and all array elements are aligned appropriately.

NPY_ARRAY_WRITEABLE

The data area can be written to.

Notice that the above 3 flags are are defined so that a new, well- behaved array has these flags defined as true.

NPY_ARRAY_UPDATEIFCOPY

The data area represents a (well-behaved) copy whose information should be transferred back to the original when this array is deleted.

This is a special flag that is set if this array represents a copy made because a user required certain flags in PyArray_FromAny and a copy had to be made of some other array (and the user asked for this flag to be set in such a situation). The base attribute then points to the “misbehaved” array (which is set read_only). When the array with this flag set is deallocated, it will copy its contents back to the “misbehaved” array (casting if necessary) and will reset the “misbehaved” array to NPY_ARRAY_WRITEABLE. If the “misbehaved” array was not NPY_ARRAY_WRITEABLE to begin with then PyArray_FromAny would have returned an error because NPY_ARRAY_UPDATEIFCOPY would not have been possible.

PyArray_UpdateFlags (obj, flags) will update the obj->flags for flags which can be any of NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_F_CONTIGUOUS, NPY_ARRAY_ALIGNED, or NPY_ARRAY_WRITEABLE.

Combinations of array flags

NPY_ARRAY_BEHAVED

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE

NPY_ARRAY_CARRAY

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_CARRAY_RO

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_FARRAY

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_BEHAVED

NPY_ARRAY_FARRAY_RO

NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

NPY_ARRAY_DEFAULT

NPY_ARRAY_CARRAY

NPY_ARRAY_UPDATE_ALL

NPY_ARRAY_C_CONTIGUOUS | NPY_ARRAY_F_CONTIGUOUS | NPY_ARRAY_ALIGNED

Flag-like constants

These constants are used in PyArray_FromAny (and its macro forms) to specify desired properties of the new array.

NPY_ARRAY_FORCECAST

Cast to the desired type, even if it can’t be done without losing information.

NPY_ARRAY_ENSURECOPY

Make sure the resulting array is a copy of the original.

NPY_ARRAY_ENSUREARRAY

Make sure the resulting object is an actual ndarray (or bigndarray), and not a sub-class.

NPY_ARRAY_NOTSWAPPED

Only used in PyArray_CheckFromAny to over-ride the byteorder of the data-type object passed in.

NPY_ARRAY_BEHAVED_NS

NPY_ARRAY_ALIGNED | NPY_ARRAY_WRITEABLE | NPY_ARRAY_NOTSWAPPED

Flag checking

For all of these macros arr must be an instance of a (subclass of) PyArray_Type, but no checking is done.

PyArray_CHKFLAGS(arr, flags)

The first parameter, arr, must be an ndarray or subclass. The parameter, flags, should be an integer consisting of bitwise combinations of the possible flags an array can have: NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_F_CONTIGUOUS, NPY_ARRAY_OWNDATA, NPY_ARRAY_ALIGNED, NPY_ARRAY_WRITEABLE, NPY_ARRAY_UPDATEIFCOPY.

PyArray_IS_C_CONTIGUOUS(arr)

Evaluates true if arr is C-style contiguous.

PyArray_IS_F_CONTIGUOUS(arr)

Evaluates true if arr is Fortran-style contiguous.

PyArray_ISFORTRAN(arr)

Evaluates true if arr is Fortran-style contiguous and not C-style contiguous. PyArray_IS_F_CONTIGUOUS is the correct way to test for Fortran-style contiguity.

PyArray_ISWRITEABLE(arr)

Evaluates true if the data area of arr can be written to

PyArray_ISALIGNED(arr)

Evaluates true if the data area of arr is properly aligned on the machine.

PyArray_ISBEHAVED(arr)

Evalutes true if the data area of arr is aligned and writeable and in machine byte-order according to its descriptor.

PyArray_ISBEHAVED_RO(arr)

Evaluates true if the data area of arr is aligned and in machine byte-order.

PyArray_ISCARRAY(arr)

Evaluates true if the data area of arr is C-style contiguous, and PyArray_ISBEHAVED (arr) is true.

PyArray_ISFARRAY(arr)

Evaluates true if the data area of arr is Fortran-style contiguous and PyArray_ISBEHAVED (arr) is true.

PyArray_ISCARRAY_RO(arr)

Evaluates true if the data area of arr is C-style contiguous, aligned, and in machine byte-order.

PyArray_ISFARRAY_RO(arr)

Evaluates true if the data area of arr is Fortran-style contiguous, aligned, and in machine byte-order .

PyArray_ISONESEGMENT(arr)

Evaluates true if the data area of arr consists of a single (C-style or Fortran-style) contiguous segment.

void PyArray_UpdateFlags( PyArrayObject* arr, int flagmask)

The NPY_ARRAY_C_CONTIGUOUS, NPY_ARRAY_ALIGNED, and NPY_ARRAY_F_CONTIGUOUS array flags can be “calculated” from the array object itself. This routine updates one or more of these flags of arr as specified in flagmask by performing the required calculation.

Warning

It is important to keep the flags updated (using PyArray_UpdateFlags can help) whenever a manipulation with an array is performed that might cause them to change. Later calculations in NumPy that rely on the state of these flags do not repeat the calculation to update them.

Array method alternative API

Conversion

PyObject* PyArray_GetField( PyArrayObject* self, PyArray_Descr* dtype, int offset)

Equivalent to ndarray.getfield (self, dtype, offset). Return a new array of the given dtype using the data in the current array at a specified offset in bytes. The offset plus the itemsize of the new array type must be less than self ->descr->elsize or an error is raised. The same shape and strides as the original array are used. Therefore, this function has the effect of returning a field from a record array. But, it can also be used to select specific bytes or groups of bytes from any array type.

int PyArray_SetField( PyArrayObject* self, PyArray_Descr* dtype, int offset, PyObject* val)

Equivalent to ndarray.setfield (self, val, dtype, offset ). Set the field starting at offset in bytes and of the given dtype to val. The offset plus dtype ->elsize must be less than self ->descr->elsize or an error is raised. Otherwise, the val argument is converted to an array and copied into the field pointed to. If necessary, the elements of val are repeated to fill the destination array, But, the number of elements in the destination must be an integer multiple of the number of elements in val.

PyObject* PyArray_Byteswap( PyArrayObject* self, Bool inplace)

Equivalent to ndarray.byteswap (self, inplace). Return an array whose data area is byteswapped. If inplace is non-zero, then do the byteswap inplace and return a reference to self. Otherwise, create a byteswapped copy and leave self unchanged.

PyObject* PyArray_NewCopy( PyArrayObject* old, NPY_ORDER order)

Equivalent to ndarray.copy (self, fortran). Make a copy of the old array. The returned array is always aligned and writeable with data interpreted the same as the old array. If order is NPY_CORDER, then a C-style contiguous array is returned. If order is NPY_FORTRANORDER, then a Fortran-style contiguous array is returned. If order is NPY_ANYORDER, then the array returned is Fortran-style contiguous only if the old one is; otherwise, it is C-style contiguous.

PyObject* PyArray_ToList( PyArrayObject* self)

Equivalent to ndarray.tolist (self). Return a nested Python list from self.

PyObject* PyArray_ToString( PyArrayObject* self, NPY_ORDER order)

Equivalent to ndarray.tobytes (self, order). Return the bytes of this array in a Python string.

PyObject* PyArray_ToFile( PyArrayObject* self, FILE* fp, char* sep, char* format)

Write the contents of self to the file pointer fp in C-style contiguous fashion. Write the data as binary bytes if sep is the string “”or NULL. Otherwise, write the contents of self as text using the sep string as the item separator. Each item will be printed to the file. If the format string is not NULL or “”, then it is a Python print statement format string showing how the items are to be written.

int PyArray_Dump( PyObject* self, PyObject* file, int protocol)

Pickle the object in self to the given file (either a string or a Python file object). If file is a Python string it is considered to be the name of a file which is then opened in binary mode. The given protocol is used (if protocol is negative, or the highest available is used). This is a simple wrapper around cPickle.dump(self, file, protocol).

PyObject* PyArray_Dumps( PyObject* self, int protocol)

Pickle the object in self to a Python string and return it. Use the Pickle protocol provided (or the highest available if protocol is negative).

int PyArray_FillWithScalar( PyArrayObject* arr, PyObject* obj)

Fill the array, arr, with the given scalar object, obj. The object is first converted to the data type of arr, and then copied into every location. A -1 is returned if an error occurs, otherwise 0 is returned.

PyObject* PyArray_View( PyArrayObject* self, PyArray_Descr* dtype, PyTypeObject *ptype)

Equivalent to ndarray.view (self, dtype). Return a new view of the array self as possibly a different data-type, dtype, and different array subclass ptype.

If dtype is NULL, then the returned array will have the same data type as self. The new data-type must be consistent with the size of self. Either the itemsizes must be identical, or self must be single-segment and the total number of bytes must be the same. In the latter case the dimensions of the returned array will be altered in the last (or first for Fortran-style contiguous arrays) dimension. The data area of the returned array and self is exactly the same.

Shape Manipulation

PyObject* PyArray_Newshape( PyArrayObject* self, PyArray_Dims* newshape, NPY_ORDER order)

Result will be a new array (pointing to the same memory location as self if possible), but having a shape given by newshape. If the new shape is not compatible with the strides of self, then a copy of the array with the new specified shape will be returned.

PyObject* PyArray_Reshape( PyArrayObject* self, PyObject* shape)

Equivalent to ndarray.reshape (self, shape) where shape is a sequence. Converts shape to a PyArray_Dims structure and calls PyArray_Newshape internally. For back-ward compatability – Not recommended

PyObject* PyArray_Squeeze( PyArrayObject* self)

Equivalent to ndarray.squeeze (self). Return a new view of self with all of the dimensions of length 1 removed from the shape.

Warning

matrix objects are always 2-dimensional. Therefore, PyArray_Squeeze has no effect on arrays of matrix sub-class.

PyObject* PyArray_SwapAxes( PyArrayObject* self, int a1, int a2)

Equivalent to ndarray.swapaxes (self, a1, a2). The returned array is a new view of the data in self with the given axes, a1 and a2, swapped.

PyObject* PyArray_Resize( PyArrayObject* self, PyArray_Dims* newshape, int refcheck, NPY_ORDER fortran)

Equivalent to ndarray.resize (self, newshape, refcheck = refcheck, order= fortran ). This function only works on single-segment arrays. It changes the shape of self inplace and will reallocate the memory for self if newshape has a different total number of elements then the old shape. If reallocation is necessary, then self must own its data, have self - >base==NULL, have self - >weakrefs==NULL, and (unless refcheck is 0) not be referenced by any other array. A reference to the new array is returned. The fortran argument can be NPY_ANYORDER, NPY_CORDER, or NPY_FORTRANORDER. It currently has no effect. Eventually it could be used to determine how the resize operation should view the data when constructing a differently-dimensioned array.

PyObject* PyArray_Transpose( PyArrayObject* self, PyArray_Dims* permute)

Equivalent to ndarray.transpose (self, permute). Permute the axes of the ndarray object self according to the data structure permute and return the result. If permute is NULL, then the resulting array has its axes reversed. For example if self has shape [image], and permute .ptr is (0,2,1) the shape of the result is [image] If permute is NULL, the shape of the result is

PyObject* PyArray_Flatten( PyArrayObject* self, NPY_ORDER order)

Equivalent to ndarray.flatten (self, order). Return a 1-d copy of the array. If order is NPY_FORTRANORDER the elements are scanned out in Fortran order (first-dimension varies the fastest). If order is NPY_CORDER, the elements of self are scanned in C-order (last dimension varies the fastest). If order NPY_ANYORDER, then the result of PyArray_ISFORTRAN (self) is used to determine which order to flatten.

PyObject* PyArray_Ravel( PyArrayObject* self, NPY_ORDER order)

Equivalent to self.ravel(order). Same basic functionality as PyArray_Flatten (self, order) except if order is 0 and self is C-style contiguous, the shape is altered but no copy is performed.

Item selection and manipulation

PyObject* PyArray_TakeFrom( PyArrayObject* self, PyObject* indices, int axis, PyArrayObject* ret, NPY_CLIPMODE clipmode)

Equivalent to ndarray.take (self, indices, axis, ret, clipmode) except axis =None in Python is obtained by setting axis = NPY_MAXDIMS in C. Extract the items from self indicated by the integer-valued indices along the given axis. The clipmode argument can be NPY_RAISE, NPY_WRAP, or NPY_CLIP to indicate what to do with out-of-bound indices. The ret argument can specify an output array rather than having one created internally.

PyObject* PyArray_PutTo( PyArrayObject* self, PyObject* values, PyObject* indices, NPY_CLIPMODE clipmode)

Equivalent to self.put(values, indices, clipmode ). Put values into self at the corresponding (flattened) indices. If values is too small it will be repeated as necessary.

PyObject* PyArray_PutMask( PyArrayObject* self, PyObject* values, PyObject* mask)

Place the values in self wherever corresponding positions (using a flattened context) in mask are true. The mask and self arrays must have the same total number of elements. If values is too small, it will be repeated as necessary.

PyObject* PyArray_Repeat( PyArrayObject* self, PyObject* op, int axis)

Equivalent to ndarray.repeat (self, op, axis). Copy the elements of self, op times along the given axis. Either op is a scalar integer or a sequence of length self ->dimensions[ axis ] indicating how many times to repeat each item along the axis.

PyObject* PyArray_Choose( PyArrayObject* self, PyObject* op, PyArrayObject* ret, NPY_CLIPMODE clipmode)

Equivalent to ndarray.choose (self, op, ret, clipmode). Create a new array by selecting elements from the sequence of arrays in op based on the integer values in self. The arrays must all be broadcastable to the same shape and the entries in self should be between 0 and len(op). The output is placed in ret unless it is NULL in which case a new output is created. The clipmode argument determines behavior for when entries in self are not between 0 and len(op).

NPY_RAISE

raise a ValueError;

NPY_WRAP

wrap values < 0 by adding len(op) and values >=len(op) by subtracting len(op) until they are in range;

NPY_CLIP

all values are clipped to the region [0, len(op) ).

PyObject* PyArray_Sort( PyArrayObject* self, int axis)

Equivalent to ndarray.sort (self, axis). Return an array with the items of self sorted along axis.

PyObject* PyArray_ArgSort( PyArrayObject* self, int axis)

Equivalent to ndarray.argsort (self, axis). Return an array of indices such that selection of these indices along the given axis would return a sorted version of self. If self ->descr is a data-type with fields defined, then self->descr->names is used to determine the sort order. A comparison where the first field is equal will use the second field and so on. To alter the sort order of a record array, create a new data-type with a different order of names and construct a view of the array with that new data-type.

PyObject* PyArray_LexSort( PyObject* sort_keys, int axis)

Given a sequence of arrays (sort_keys) of the same shape, return an array of indices (similar to PyArray_ArgSort (...)) that would sort the arrays lexicographically. A lexicographic sort specifies that when two keys are found to be equal, the order is based on comparison of subsequent keys. A merge sort (which leaves equal entries unmoved) is required to be defined for the types. The sort is accomplished by sorting the indices first using the first sort_key and then using the second sort_key and so forth. This is equivalent to the lexsort(sort_keys, axis) Python command. Because of the way the merge-sort works, be sure to understand the order the sort_keys must be in (reversed from the order you would use when comparing two elements).

If these arrays are all collected in a record array, then PyArray_Sort (...) can also be used to sort the array directly.

PyObject* PyArray_SearchSorted( PyArrayObject* self, PyObject* values, NPY_SEARCHSIDE side, PyObject* perm)

Equivalent to ndarray.searchsorted (self, values, side, perm). Assuming self is a 1-d array in ascending order, then the output is an array of indices the same shape as values such that, if the elements in values were inserted before the indices, the order of self would be preserved. No checking is done on whether or not self is in ascending order.

The side argument indicates whther the index returned should be that of the first suitable location (if NPY_SEARCHLEFT) or of the last (if NPY_SEARCHRIGHT).

The sorter argument, if not NULL, must be a 1D array of integer indices the same length as self, that sorts it into ascending order. This is typically the result of a call to PyArray_ArgSort (...) Binary search is used to find the required insertion points.

int PyArray_Partition( PyArrayObject *self, PyArrayObject * ktharray, int axis, NPY_SELECTKIND which)

Equivalent to ndarray.partition (self, ktharray, axis, kind). Partitions the array so that the values of the element indexed by ktharray are in the positions they would be if the array is fully sorted and places all elements smaller than the kth before and all elements equal or greater after the kth element. The ordering of all elements within the partitions is undefined. If self->descr is a data-type with fields defined, then self->descr->names is used to determine the sort order. A comparison where the first field is equal will use the second field and so on. To alter the sort order of a record array, create a new data-type with a different order of names and construct a view of the array with that new data-type. Returns zero on success and -1 on failure.

PyObject* PyArray_ArgPartition( PyArrayObject *op, PyArrayObject * ktharray, int axis, NPY_SELECTKIND which)

Equivalent to ndarray.argpartition (self, ktharray, axis, kind). Return an array of indices such that selection of these indices along the given axis would return a partitioned version of self.

PyObject* PyArray_Diagonal( PyArrayObject* self, int offset, int axis1, int axis2)

Equivalent to ndarray.diagonal (self, offset, axis1, axis2 ). Return the offset diagonals of the 2-d arrays defined by axis1 and axis2.

npy_intp PyArray_CountNonzero( PyArrayObject* self)

New in version 1.6.

Counts the number of non-zero elements in the array object self.

PyObject* PyArray_Nonzero( PyArrayObject* self)

Equivalent to ndarray.nonzero (self). Returns a tuple of index arrays that select elements of self that are nonzero. If (nd= PyArray_NDIM ( self ))==1, then a single index array is returned. The index arrays have data type NPY_INTP. If a tuple is returned (nd [image] 1), then its length is nd.

PyObject* PyArray_Compress( PyArrayObject* self, PyObject* condition, int axis, PyArrayObject* out)

Equivalent to ndarray.compress (self, condition, axis ). Return the elements along axis corresponding to elements of condition that are true.

Calculation

Tip

Pass in NPY_MAXDIMS for axis in order to achieve the same effect that is obtained by passing in axis = None in Python (treating the array as a 1-d array).

PyObject* PyArray_ArgMax( PyArrayObject* self, int axis, PyArrayObject* out)

Equivalent to ndarray.argmax (self, axis). Return the index of the largest element of self along axis.

PyObject* PyArray_ArgMin( PyArrayObject* self, int axis, PyArrayObject* out)

Equivalent to ndarray.argmin (self, axis). Return the index of the smallest element of self along axis.

Note

The out argument specifies where to place the result. If out is NULL, then the output array is created, otherwise the output is placed in out which must be the correct size and type. A new reference to the ouput array is always returned even when out is not NULL. The caller of the routine has the responsability to DECREF out if not NULL or a memory-leak will occur.

PyObject* PyArray_Max( PyArrayObject* self, int axis, PyArrayObject* out)

Equivalent to ndarray.max (self, axis). Return the largest element of self along the given axis.

PyObject* PyArray_Min( PyArrayObject* self, int axis, PyArrayObject* out)

Equivalent to ndarray.min (self, axis). Return the smallest element of self along the given axis.

PyObject* PyArray_Ptp( PyArrayObject* self, int axis, PyArrayObject* out)

Equivalent to ndarray.ptp (self, axis). Return the difference between the largest element of self along axis and the smallest element of self along axis.

Note

The rtype argument specifies the data-type the reduction should take place over. This is important if the data-type of the array is not “large” enough to handle the output. By default, all integer data-types are made at least as large as NPY_LONG for the “add” and “multiply” ufuncs (which form the basis for mean, sum, cumsum, prod, and cumprod functions).

PyObject* PyArray_Mean( PyArrayObject* self, int axis, int rtype, PyArrayObject* out)

Equivalent to ndarray.mean (self, axis, rtype). Returns the mean of the elements along the given axis, using the enumerated type rtype as the data type to sum in. Default sum behavior is obtained using NPY_NOTYPE for rtype.

PyObject* PyArray_Trace( PyArrayObject* self, int offset, int axis1, int axis2, int rtype, PyArrayObject* out)

Equivalent to ndarray.trace (self, offset, axis1, axis2, rtype). Return the sum (using rtype as the data type of summation) over the offset diagonal elements of the 2-d arrays defined by axis1 and axis2 variables. A positive offset chooses diagonals above the main diagonal. A negative offset selects diagonals below the main diagonal.

PyObject* PyArray_Clip( PyArrayObject* self, PyObject* min, PyObject* max)

Equivalent to ndarray.clip (self, min, max). Clip an array, self, so that values larger than max are fixed to max and values less than min are fixed to min.

PyObject* PyArray_Conjugate( PyArrayObject* self)

Equivalent to ndarray.conjugate (self). Return the complex conjugate of self. If self is not of complex data type, then return self with an reference.

PyObject* PyArray_Round( PyArrayObject* self, int decimals, PyArrayObject* out)

Equivalent to ndarray.round (self, decimals, out). Returns the array with elements rounded to the nearest decimal place. The decimal place is defined as the [image] digit so that negative decimals cause rounding to the nearest 10’s, 100’s, etc. If out is NULL, then the output array is created, otherwise the output is placed in out which must be the correct size and type.

PyObject* PyArray_Std( PyArrayObject* self, int axis, int rtype, PyArrayObject* out)

Equivalent to ndarray.std (self, axis, rtype). Return the standard deviation using data along axis converted to data type rtype.

PyObject* PyArray_Sum( PyArrayObject* self, int axis, int rtype, PyArrayObject* out)

Equivalent to ndarray.sum (self, axis, rtype). Return 1-d vector sums of elements in self along axis. Perform the sum after converting data to data type rtype.

PyObject* PyArray_CumSum( PyArrayObject* self, int axis, int rtype, PyArrayObject* out)

Equivalent to ndarray.cumsum (self, axis, rtype). Return cumulative 1-d sums of elements in self along axis. Perform the sum after converting data to data type rtype.

PyObject* PyArray_Prod( PyArrayObject* self, int axis, int rtype, PyArrayObject* out)

Equivalent to ndarray.prod (self, axis, rtype). Return 1-d products of elements in self along axis. Perform the product after converting data to data type rtype.

PyObject* PyArray_CumProd( PyArrayObject* self, int axis, int rtype, PyArrayObject* out)

Equivalent to ndarray.cumprod (self, axis, rtype). Return 1-d cumulative products of elements in self along axis. Perform the product after converting data to data type rtype.

PyObject* PyArray_All( PyArrayObject* self, int axis, PyArrayObject* out)

Equivalent to ndarray.all (self, axis). Return an array with True elements for every 1-d sub-array of self defined by axis in which all the elements are True.

PyObject* PyArray_Any( PyArrayObject* self, int axis, PyArrayObject* out)

Equivalent to ndarray.any (self, axis). Return an array with True elements for every 1-d sub-array of self defined by axis in which any of the elements are True.

Functions

Array Functions

int PyArray_AsCArray( PyObject** op, void* ptr, npy_intp* dims, int nd, int typenum, int itemsize)

Sometimes it is useful to access a multidimensional array as a C-style multi-dimensional array so that algorithms can be implemented using C’s a[i][j][k] syntax. This routine returns a pointer, ptr, that simulates this kind of C-style array, for 1-, 2-, and 3-d ndarrays.

Parameters:
  • op – The address to any Python object. This Python object will be replaced with an equivalent well-behaved, C-style contiguous, ndarray of the given data type specifice by the last two arguments. Be sure that stealing a reference in this way to the input object is justified.
  • ptr – The address to a (ctype* for 1-d, ctype** for 2-d or ctype*** for 3-d) variable where ctype is the equivalent C-type for the data type. On return, ptr will be addressable as a 1-d, 2-d, or 3-d array.
  • dims – An output array that contains the shape of the array object. This array gives boundaries on any looping that will take place.
  • nd – The dimensionality of the array (1, 2, or 3).
  • typenum – The expected data type of the array.
  • itemsize – This argument is only needed when typenum represents a flexible array. Otherwise it should be 0.

Note

The simulation of a C-style array is not complete for 2-d and 3-d arrays. For example, the simulated arrays of pointers cannot be passed to subroutines expecting specific, statically-defined 2-d and 3-d arrays. To pass to functions requiring those kind of inputs, you must statically define the required array and copy data.

int PyArray_Free( PyObject* op, void* ptr)

Must be called with the same objects and memory locations returned from PyArray_AsCArray (...). This function cleans up memory that otherwise would get leaked.

PyObject* PyArray_Concatenate( PyObject* obj, int axis)

Join the sequence of objects in obj together along axis into a single array. If the dimensions or types are not compatible an error is raised.

PyObject* PyArray_InnerProduct( PyObject* obj1, PyObject* obj2)

Compute a product-sum over the last dimensions of obj1 and obj2. Neither array is conjugated.

PyObject* PyArray_MatrixProduct( PyObject* obj1, PyObject* obj)

Compute a product-sum over the last dimension of obj1 and the second-to-last dimension of obj2. For 2-d arrays this is a matrix-product. Neither array is conjugated.

PyObject* PyArray_MatrixProduct2( PyObject* obj1, PyObject* obj, PyObject* out)

New in version 1.6.

Same as PyArray_MatrixProduct, but store the result in out. The output array must have the correct shape, type, and be C-contiguous, or an exception is raised.

PyObject* PyArray_EinsteinSum(char* subscripts, npy_intp nop, PyArrayObject** op_in, PyArray_Descr* dtype, NPY_ORDER order, NPY_CASTING casting, PyArrayObject* out)

New in version 1.6.

Applies the einstein summation convention to the array operands provided, returning a new array or placing the result in out. The string in subscripts is a comma separated list of index letters. The number of operands is in nop, and op_in is an array containing those operands. The data type of the output can be forced with dtype, the output order can be forced with order (NPY_KEEPORDER is recommended), and when dtype is specified, casting indicates how permissive the data conversion should be.

See the einsum function for more details.

PyObject* PyArray_CopyAndTranspose( PyObject * op)

A specialized copy and transpose function that works only for 2-d arrays. The returned array is a transposed copy of op.

PyObject* PyArray_Correlate( PyObject* op1, PyObject* op2, int mode)

Compute the 1-d correlation of the 1-d arrays op1 and op2 . The correlation is computed at each output point by multiplying op1 by a shifted version of op2 and summing the result. As a result of the shift, needed values outside of the defined range of op1 and op2 are interpreted as zero. The mode determines how many shifts to return: 0 - return only shifts that did not need to assume zero- values; 1 - return an object that is the same size as op1, 2 - return all possible shifts (any overlap at all is accepted).

Notes

This does not compute the usual correlation: if op2 is larger than op1, the arguments are swapped, and the conjugate is never taken for complex arrays. See PyArray_Correlate2 for the usual signal processing correlation.

PyObject* PyArray_Correlate2( PyObject* op1, PyObject* op2, int mode)

Updated version of PyArray_Correlate, which uses the usual definition of correlation for 1d arrays. The correlation is computed at each output point by multiplying op1 by a shifted version of op2 and summing the result. As a result of the shift, needed values outside of the defined range of op1 and op2 are interpreted as zero. The mode determines how many shifts to return: 0 - return only shifts that did not need to assume zero- values; 1 - return an object that is the same size as op1, 2 - return all possible shifts (any overlap at all is accepted).

Notes

Compute z as follows:

z[k] = sum_n op1[n] * conj(op2[n+k])
PyObject* PyArray_Where( PyObject* condition, PyObject* x, PyObject* y)

If both x and y are NULL, then return PyArray_Nonzero (condition). Otherwise, both x and y must be given and the object returned is shaped like condition and has elements of x and y where condition is respectively True or False.

Other functions

Bool PyArray_CheckStrides(int elsize, int nd, npy_intp numbytes, npy_intp* dims, npy_intp* newstrides)

Determine if newstrides is a strides array consistent with the memory of an nd -dimensional array with shape dims and element-size, elsize. The newstrides array is checked to see if jumping by the provided number of bytes in each direction will ever mean jumping more than numbytes which is the assumed size of the available memory segment. If numbytes is 0, then an equivalent numbytes is computed assuming nd, dims, and elsize refer to a single-segment array. Return NPY_TRUE if newstrides is acceptable, otherwise return NPY_FALSE.

npy_intp PyArray_MultiplyList(npy_intp* seq, int n)
int PyArray_MultiplyIntList(int* seq, int n)

Both of these routines multiply an n -length array, seq, of integers and return the result. No overflow checking is performed.

int PyArray_CompareLists(npy_intp* l1, npy_intp* l2, int n)

Given two n -length arrays of integers, l1, and l2, return 1 if the lists are identical; otherwise, return 0.

Auxiliary Data With Object Semantics

New in version 1.7.0.

NpyAuxData

When working with more complex dtypes which are composed of other dtypes, such as the struct dtype, creating inner loops that manipulate the dtypes requires carrying along additional data. NumPy supports this idea through a struct NpyAuxData, mandating a few conventions so that it is possible to do this.

Defining an NpyAuxData is similar to defining a class in C++, but the object semantics have to be tracked manually since the API is in C. Here’s an example for a function which doubles up an element using an element copier function as a primitive.:

typedef struct {
    NpyAuxData base;
    ElementCopier_Func *func;
    NpyAuxData *funcdata;
} eldoubler_aux_data;

void free_element_doubler_aux_data(NpyAuxData *data)
{
    eldoubler_aux_data *d = (eldoubler_aux_data *)data;
    /* Free the memory owned by this auxadata */
    NPY_AUXDATA_FREE(d->funcdata);
    PyArray_free(d);
}

NpyAuxData *clone_element_doubler_aux_data(NpyAuxData *data)
{
    eldoubler_aux_data *ret = PyArray_malloc(sizeof(eldoubler_aux_data));
    if (ret == NULL) {
        return NULL;
    }

    /* Raw copy of all data */
    memcpy(ret, data, sizeof(eldoubler_aux_data));

    /* Fix up the owned auxdata so we have our own copy */
    ret->funcdata = NPY_AUXDATA_CLONE(ret->funcdata);
    if (ret->funcdata == NULL) {
        PyArray_free(ret);
        return NULL;
    }

    return (NpyAuxData *)ret;
}

NpyAuxData *create_element_doubler_aux_data(
                            ElementCopier_Func *func,
                            NpyAuxData *funcdata)
{
    eldoubler_aux_data *ret = PyArray_malloc(sizeof(eldoubler_aux_data));
    if (ret == NULL) {
        PyErr_NoMemory();
        return NULL;
    }
    memset(&ret, 0, sizeof(eldoubler_aux_data));
    ret->base->free = &free_element_doubler_aux_data;
    ret->base->clone = &clone_element_doubler_aux_data;
    ret->func = func;
    ret->funcdata = funcdata;

    return (NpyAuxData *)ret;
}
NpyAuxData_FreeFunc

The function pointer type for NpyAuxData free functions.

NpyAuxData_CloneFunc

The function pointer type for NpyAuxData clone functions. These functions should never set the Python exception on error, because they may be called from a multi-threaded context.

NPY_AUXDATA_FREE(auxdata)

A macro which calls the auxdata’s free function appropriately, does nothing if auxdata is NULL.

NPY_AUXDATA_CLONE(auxdata)

A macro which calls the auxdata’s clone function appropriately, returning a deep copy of the auxiliary data.

Array Iterators

As of Numpy 1.6, these array iterators are superceded by the new array iterator, NpyIter.

An array iterator is a simple way to access the elements of an N-dimensional array quickly and efficiently. Section 2 provides more description and examples of this useful approach to looping over an array.

PyObject* PyArray_IterNew( PyObject* arr)

Return an array iterator object from the array, arr. This is equivalent to arr. flat. The array iterator object makes it easy to loop over an N-dimensional non-contiguous array in C-style contiguous fashion.

PyObject* PyArray_IterAllButAxis( PyObject* arr, int *axis)

Return an array iterator that will iterate over all axes but the one provided in *axis. The returned iterator cannot be used with PyArray_ITER_GOTO1D. This iterator could be used to write something similar to what ufuncs do wherein the loop over the largest axis is done by a separate sub-routine. If *axis is negative then *axis will be set to the axis having the smallest stride and that axis will be used.

PyObject *PyArray_BroadcastToShape( PyObject* arr, npy_intp *dimensions, int nd)

Return an array iterator that is broadcast to iterate as an array of the shape provided by dimensions and nd.

int PyArrayIter_Check( PyObject* op)

Evaluates true if op is an array iterator (or instance of a subclass of the array iterator type).

void PyArray_ITER_RESET( PyObject* iterator)

Reset an iterator to the beginning of the array.

void PyArray_ITER_NEXT( PyObject* iterator)

Incremement the index and the dataptr members of the iterator to point to the next element of the array. If the array is not (C-style) contiguous, also increment the N-dimensional coordinates array.

void *PyArray_ITER_DATA( PyObject* iterator)

A pointer to the current element of the array.

void PyArray_ITER_GOTO( PyObject* iterator, npy_intp* destination)

Set the iterator index, dataptr, and coordinates members to the location in the array indicated by the N-dimensional c-array, destination, which must have size at least iterator ->nd_m1+1.

PyArray_ITER_GOTO1D( PyObject* iterator, npy_intp index)

Set the iterator index and dataptr to the location in the array indicated by the integer index which points to an element in the C-styled flattened array.

int PyArray_ITER_NOTDONE( PyObject* iterator)

Evaluates TRUE as long as the iterator has not looped through all of the elements, otherwise it evaluates FALSE.

Broadcasting (multi-iterators)

PyObject* PyArray_MultiIterNew(int num, ...)

A simplified interface to broadcasting. This function takes the number of arrays to broadcast and then num extra ( PyObject * ) arguments. These arguments are converted to arrays and iterators are created. PyArray_Broadcast is then called on the resulting multi-iterator object. The resulting, broadcasted mult-iterator object is then returned. A broadcasted operation can then be performed using a single loop and using PyArray_MultiIter_NEXT (..)

void PyArray_MultiIter_RESET( PyObject* multi)

Reset all the iterators to the beginning in a multi-iterator object, multi.

void PyArray_MultiIter_NEXT( PyObject* multi)

Advance each iterator in a multi-iterator object, multi, to its next (broadcasted) element.

void *PyArray_MultiIter_DATA( PyObject* multi, int i)

Return the data-pointer of the i [image] iterator in a multi-iterator object.

void PyArray_MultiIter_NEXTi( PyObject* multi, int i)

Advance the pointer of only the i [image] iterator.

void PyArray_MultiIter_GOTO( PyObject* multi, npy_intp* destination)

Advance each iterator in a multi-iterator object, multi, to the given N -dimensional destination where N is the number of dimensions in the broadcasted array.

void PyArray_MultiIter_GOTO1D( PyObject* multi, npy_intp index)

Advance each iterator in a multi-iterator object, multi, to the corresponding location of the index into the flattened broadcasted array.

int PyArray_MultiIter_NOTDONE( PyObject* multi)

Evaluates TRUE as long as the multi-iterator has not looped through all of the elements (of the broadcasted result), otherwise it evaluates FALSE.

int PyArray_Broadcast( PyArrayMultiIterObject* mit)

This function encapsulates the broadcasting rules. The mit container should already contain iterators for all the arrays that need to be broadcast. On return, these iterators will be adjusted so that iteration over each simultaneously will accomplish the broadcasting. A negative number is returned if an error occurs.

int PyArray_RemoveSmallest( PyArrayMultiIterObject* mit)

This function takes a multi-iterator object that has been previously “broadcasted,” finds the dimension with the smallest “sum of strides” in the broadcasted result and adapts all the iterators so as not to iterate over that dimension (by effectively making them of length-1 in that dimension). The corresponding dimension is returned unless mit ->nd is 0, then -1 is returned. This function is useful for constructing ufunc-like routines that broadcast their inputs correctly and then call a strided 1-d version of the routine as the inner-loop. This 1-d version is usually optimized for speed and for this reason the loop should be performed over the axis that won’t require large stride jumps.

Neighborhood iterator

New in version 1.4.0.

Neighborhood iterators are subclasses of the iterator object, and can be used to iter over a neighborhood of a point. For example, you may want to iterate over every voxel of a 3d image, and for every such voxel, iterate over an hypercube. Neighborhood iterator automatically handle boundaries, thus making this kind of code much easier to write than manual boundaries handling, at the cost of a slight overhead.

PyObject* PyArray_NeighborhoodIterNew( PyArrayIterObject* iter, npy_intp bounds, int mode, PyArrayObject* fill_value)

This function creates a new neighborhood iterator from an existing iterator. The neighborhood will be computed relatively to the position currently pointed by iter, the bounds define the shape of the neighborhood iterator, and the mode argument the boundaries handling mode.

The bounds argument is expected to be a (2 * iter->ao->nd) arrays, such as the range bound[2*i]->bounds[2*i+1] defines the range where to walk for dimension i (both bounds are included in the walked coordinates). The bounds should be ordered for each dimension (bounds[2*i] <= bounds[2*i+1]).

The mode should be one of:

  • NPY_NEIGHBORHOOD_ITER_ZERO_PADDING: zero padding. Outside bounds values will be 0.
  • NPY_NEIGHBORHOOD_ITER_ONE_PADDING: one padding, Outside bounds values will be 1.
  • NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING: constant padding. Outside bounds values will be the same as the first item in fill_value.
  • NPY_NEIGHBORHOOD_ITER_MIRROR_PADDING: mirror padding. Outside bounds values will be as if the array items were mirrored. For example, for the array [1, 2, 3, 4], x[-2] will be 2, x[-2] will be 1, x[4] will be 4, x[5] will be 1, etc...
  • NPY_NEIGHBORHOOD_ITER_CIRCULAR_PADDING: circular padding. Outside bounds values will be as if the array was repeated. For example, for the array [1, 2, 3, 4], x[-2] will be 3, x[-2] will be 4, x[4] will be 1, x[5] will be 2, etc...

If the mode is constant filling (NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING), fill_value should point to an array object which holds the filling value (the first item will be the filling value if the array contains more than one item). For other cases, fill_value may be NULL.

  • The iterator holds a reference to iter
  • Return NULL on failure (in which case the reference count of iter is not changed)
  • iter itself can be a Neighborhood iterator: this can be useful for .e.g automatic boundaries handling
  • the object returned by this function should be safe to use as a normal iterator
  • If the position of iter is changed, any subsequent call to PyArrayNeighborhoodIter_Next is undefined behavior, and PyArrayNeighborhoodIter_Reset must be called.
PyArrayIterObject \*iter;
PyArrayNeighborhoodIterObject \*neigh_iter;
iter = PyArray_IterNew(x);

//For a 3x3 kernel
bounds = {-1, 1, -1, 1};
neigh_iter = (PyArrayNeighborhoodIterObject*)PyArrayNeighborhoodIter_New(
     iter, bounds, NPY_NEIGHBORHOOD_ITER_ZERO_PADDING, NULL);

for(i = 0; i < iter->size; ++i) {
     for (j = 0; j < neigh_iter->size; ++j) {
             // Walk around the item currently pointed by iter->dataptr
             PyArrayNeighborhoodIter_Next(neigh_iter);
     }

     // Move to the next point of iter
     PyArrayIter_Next(iter);
     PyArrayNeighborhoodIter_Reset(neigh_iter);
}
int PyArrayNeighborhoodIter_Reset( PyArrayNeighborhoodIterObject* iter)

Reset the iterator position to the first point of the neighborhood. This should be called whenever the iter argument given at PyArray_NeighborhoodIterObject is changed (see example)

int PyArrayNeighborhoodIter_Next( PyArrayNeighborhoodIterObject* iter)

After this call, iter->dataptr points to the next point of the neighborhood. Calling this function after every point of the neighborhood has been visited is undefined.

Array Scalars

PyObject* PyArray_Return( PyArrayObject* arr)

This function checks to see if arr is a 0-dimensional array and, if so, returns the appropriate array scalar. It should be used whenever 0-dimensional arrays could be returned to Python.

PyObject* PyArray_Scalar(void* data, PyArray_Descr* dtype, PyObject* itemsize)

Return an array scalar object of the given enumerated typenum and itemsize by copying from memory pointed to by data . If swap is nonzero then this function will byteswap the data if appropriate to the data-type because array scalars are always in correct machine-byte order.

PyObject* PyArray_ToScalar(void* data, PyArrayObject* arr)

Return an array scalar object of the type and itemsize indicated by the array object arr copied from the memory pointed to by data and swapping if the data in arr is not in machine byte-order.

PyObject* PyArray_FromScalar( PyObject* scalar, PyArray_Descr* outcode)

Return a 0-dimensional array of type determined by outcode from scalar which should be an array-scalar object. If outcode is NULL, then the type is determined from scalar.

void PyArray_ScalarAsCtype( PyObject* scalar, void* ctypeptr)

Return in ctypeptr a pointer to the actual value in an array scalar. There is no error checking so scalar must be an array-scalar object, and ctypeptr must have enough space to hold the correct type. For flexible-sized types, a pointer to the data is copied into the memory of ctypeptr, for all other types, the actual data is copied into the address pointed to by ctypeptr.

void PyArray_CastScalarToCtype( PyObject* scalar, void* ctypeptr, PyArray_Descr* outcode)

Return the data (cast to the data type indicated by outcode) from the array-scalar, scalar, into the memory pointed to by ctypeptr (which must be large enough to handle the incoming memory).

PyObject* PyArray_TypeObjectFromType(int type)

Returns a scalar type-object from a type-number, type . Equivalent to PyArray_DescrFromType (type)->typeobj except for reference counting and error-checking. Returns a new reference to the typeobject on success or NULL on failure.

NPY_SCALARKIND PyArray_ScalarKind(int typenum, PyArrayObject** arr)

See the function PyArray_MinScalarType for an alternative mechanism introduced in NumPy 1.6.0.

Return the kind of scalar represented by typenum and the array in *arr (if arr is not NULL ). The array is assumed to be rank-0 and only used if typenum represents a signed integer. If arr is not NULL and the first element is negative then NPY_INTNEG_SCALAR is returned, otherwise NPY_INTPOS_SCALAR is returned. The possible return values are NPY_{kind}_SCALAR where {kind} can be INTPOS, INTNEG, FLOAT, COMPLEX, BOOL, or OBJECT. NPY_NOSCALAR is also an enumerated value NPY_SCALARKIND variables can take on.

int PyArray_CanCoerceScalar(char thistype, char neededtype, NPY_SCALARKIND scalar)

See the function PyArray_ResultType for details of NumPy type promotion, updated in NumPy 1.6.0.

Implements the rules for scalar coercion. Scalars are only silently coerced from thistype to neededtype if this function returns nonzero. If scalar is NPY_NOSCALAR, then this function is equivalent to PyArray_CanCastSafely. The rule is that scalars of the same KIND can be coerced into arrays of the same KIND. This rule means that high-precision scalars will never cause low-precision arrays of the same KIND to be upcast.

Data-type descriptors

Warning

Data-type objects must be reference counted so be aware of the action on the data-type reference of different C-API calls. The standard rule is that when a data-type object is returned it is a new reference. Functions that take PyArray_Descr * objects and return arrays steal references to the data-type their inputs unless otherwise noted. Therefore, you must own a reference to any data-type object used as input to such a function.

int PyArray_DescrCheck( PyObject* obj)

Evaluates as true if obj is a data-type object ( PyArray_Descr * ).

PyArray_Descr* PyArray_DescrNew( PyArray_Descr* obj)

Return a new data-type object copied from obj (the fields reference is just updated so that the new object points to the same fields dictionary if any).

PyArray_Descr* PyArray_DescrNewFromType(int typenum)

Create a new data-type object from the built-in (or user-registered) data-type indicated by typenum. All builtin types should not have any of their fields changed. This creates a new copy of the PyArray_Descr structure so that you can fill it in as appropriate. This function is especially needed for flexible data-types which need to have a new elsize member in order to be meaningful in array construction.

PyArray_Descr* PyArray_DescrNewByteorder( PyArray_Descr* obj, char newendian)

Create a new data-type object with the byteorder set according to newendian. All referenced data-type objects (in subdescr and fields members of the data-type object) are also changed (recursively). If a byteorder of NPY_IGNORE is encountered it is left alone. If newendian is NPY_SWAP, then all byte-orders are swapped. Other valid newendian values are NPY_NATIVE, NPY_LITTLE, and NPY_BIG which all cause the returned data-typed descriptor (and all it’s referenced data-type descriptors) to have the corresponding byte- order.

PyArray_Descr* PyArray_DescrFromObject( PyObject* op, PyArray_Descr* mintype)

Determine an appropriate data-type object from the object op (which should be a “nested” sequence object) and the minimum data-type descriptor mintype (which can be NULL ). Similar in behavior to array(op).dtype. Don’t confuse this function with PyArray_DescrConverter. This function essentially looks at all the objects in the (nested) sequence and determines the data-type from the elements it finds.

PyArray_Descr* PyArray_DescrFromScalar( PyObject* scalar)

Return a data-type object from an array-scalar object. No checking is done to be sure that scalar is an array scalar. If no suitable data-type can be determined, then a data-type of NPY_OBJECT is returned by default.

PyArray_Descr* PyArray_DescrFromType(int typenum)

Returns a data-type object corresponding to typenum. The typenum can be one of the enumerated types, a character code for one of the enumerated types, or a user-defined type.

int PyArray_DescrConverter( PyObject* obj, PyArray_Descr** dtype)

Convert any compatible Python object, obj, to a data-type object in dtype. A large number of Python objects can be converted to data-type objects. See Data type objects (dtype) for a complete description. This version of the converter converts None objects to a NPY_DEFAULT_TYPE data-type object. This function can be used with the “O&” character code in PyArg_ParseTuple processing.

int PyArray_DescrConverter2( PyObject* obj, PyArray_Descr** dtype)

Convert any compatible Python object, obj, to a data-type object in dtype. This version of the converter converts None objects so that the returned data-type is NULL. This function can also be used with the “O&” character in PyArg_ParseTuple processing.

int Pyarray_DescrAlignConverter( PyObject* obj, PyArray_Descr** dtype)

Like PyArray_DescrConverter except it aligns C-struct-like objects on word-boundaries as the compiler would.

int Pyarray_DescrAlignConverter2( PyObject* obj, PyArray_Descr** dtype)

Like PyArray_DescrConverter2 except it aligns C-struct-like objects on word-boundaries as the compiler would.

PyObject *PyArray_FieldNames( PyObject* dict)

Take the fields dictionary, dict, such as the one attached to a data-type object and construct an ordered-list of field names such as is stored in the names field of the PyArray_Descr object.

Conversion Utilities

For use with PyArg_ParseTuple

All of these functions can be used in PyArg_ParseTuple (...) with the “O&” format specifier to automatically convert any Python object to the required C-object. All of these functions return NPY_SUCCEED if successful and NPY_FAIL if not. The first argument to all of these function is a Python object. The second argument is the address of the C-type to convert the Python object to.

Warning

Be sure to understand what steps you should take to manage the memory when using these conversion functions. These functions can require freeing memory, and/or altering the reference counts of specific objects based on your use.

int PyArray_Converter( PyObject* obj, PyObject** address)

Convert any Python object to a PyArrayObject. If PyArray_Check (obj) is TRUE then its reference count is incremented and a reference placed in address. If obj is not an array, then convert it to an array using PyArray_FromAny . No matter what is returned, you must DECREF the object returned by this routine in address when you are done with it.

int PyArray_OutputConverter( PyObject* obj, PyArrayObject** address)

This is a default converter for output arrays given to functions. If obj is Py_None or NULL, then *address will be NULL but the call will succeed. If PyArray_Check ( obj) is TRUE then it is returned in *address without incrementing its reference count.

int PyArray_IntpConverter( PyObject* obj, PyArray_Dims* seq)

Convert any Python sequence, obj, smaller than NPY_MAXDIMS to a C-array of npy_intp. The Python object could also be a single number. The seq variable is a pointer to a structure with members ptr and len. On successful return, seq ->ptr contains a pointer to memory that must be freed to avoid a memory leak. The restriction on memory size allows this converter to be conveniently used for sequences intended to be interpreted as array shapes.

int PyArray_BufferConverter( PyObject* obj, PyArray_Chunk* buf)

Convert any Python object, obj, with a (single-segment) buffer interface to a variable with members that detail the object’s use of its chunk of memory. The buf variable is a pointer to a structure with base, ptr, len, and flags members. The PyArray_Chunk structure is binary compatibile with the Python’s buffer object (through its len member on 32-bit platforms and its ptr member on 64-bit platforms or in Python 2.5). On return, the base member is set to obj (or its base if obj is already a buffer object pointing to another object). If you need to hold on to the memory be sure to INCREF the base member. The chunk of memory is pointed to by buf ->ptr member and has length buf ->len. The flags member of buf is NPY_BEHAVED_RO with the NPY_ARRAY_WRITEABLE flag set if obj has a writeable buffer interface.

int PyArray_AxisConverter( PyObject * obj, int* axis)

Convert a Python object, obj, representing an axis argument to the proper value for passing to the functions that take an integer axis. Specifically, if obj is None, axis is set to NPY_MAXDIMS which is interpreted correctly by the C-API functions that take axis arguments.

int PyArray_BoolConverter( PyObject* obj, Bool* value)

Convert any Python object, obj, to NPY_TRUE or NPY_FALSE, and place the result in value.

int PyArray_ByteorderConverter( PyObject* obj, char* endian)

Convert Python strings into the corresponding byte-order character: ‘>’, ‘<’, ‘s’, ‘=’, or ‘|’.

int PyArray_SortkindConverter( PyObject* obj, NPY_SORTKIND* sort)

Convert Python strings into one of NPY_QUICKSORT (starts with ‘q’ or ‘Q’) , NPY_HEAPSORT (starts with ‘h’ or ‘H’), or NPY_MERGESORT (starts with ‘m’ or ‘M’).

int PyArray_SearchsideConverter( PyObject* obj, NPY_SEARCHSIDE* side)

Convert Python strings into one of NPY_SEARCHLEFT (starts with ‘l’ or ‘L’), or NPY_SEARCHRIGHT (starts with ‘r’ or ‘R’).

int PyArray_OrderConverter( PyObject* obj, NPY_ORDER* order)

Convert the Python strings ‘C’, ‘F’, ‘A’, and ‘K’ into the NPY_ORDER enumeration NPY_CORDER, NPY_FORTRANORDER, NPY_ANYORDER, and NPY_KEEPORDER.

int PyArray_CastingConverter( PyObject* obj, NPY_CASTING* casting)

Convert the Python strings ‘no’, ‘equiv’, ‘safe’, ‘same_kind’, and ‘unsafe’ into the NPY_CASTING enumeration NPY_NO_CASTING, NPY_EQUIV_CASTING, NPY_SAFE_CASTING, NPY_SAME_KIND_CASTING, and NPY_UNSAFE_CASTING.

int PyArray_ClipmodeConverter( PyObject* object, NPY_CLIPMODE* val)

Convert the Python strings ‘clip’, ‘wrap’, and ‘raise’ into the NPY_CLIPMODE enumeration NPY_CLIP, NPY_WRAP, and NPY_RAISE.

int PyArray_ConvertClipmodeSequence( PyObject* object, NPY_CLIPMODE* modes, int n)

Converts either a sequence of clipmodes or a single clipmode into a C array of NPY_CLIPMODE values. The number of clipmodes n must be known before calling this function. This function is provided to help functions allow a different clipmode for each dimension.

Other conversions

int PyArray_PyIntAsInt( PyObject* op)

Convert all kinds of Python objects (including arrays and array scalars) to a standard integer. On error, -1 is returned and an exception set. You may find useful the macro:

#define error_converting(x) (((x) == -1) && PyErr_Occurred()
npy_intp PyArray_PyIntAsIntp( PyObject* op)

Convert all kinds of Python objects (including arrays and array scalars) to a (platform-pointer-sized) integer. On error, -1 is returned and an exception set.

int PyArray_IntpFromSequence( PyObject* seq, npy_intp* vals, int maxvals)

Convert any Python sequence (or single Python number) passed in as seq to (up to) maxvals pointer-sized integers and place them in the vals array. The sequence can be smaller then maxvals as the number of converted objects is returned.

int PyArray_TypestrConvert(int itemsize, int gentype)

Convert typestring characters (with itemsize) to basic enumerated data types. The typestring character corresponding to signed and unsigned integers, floating point numbers, and complex-floating point numbers are recognized and converted. Other values of gentype are returned. This function can be used to convert, for example, the string ‘f4’ to NPY_FLOAT32.

Miscellaneous

Importing the API

In order to make use of the C-API from another extension module, the import_array () command must be used. If the extension module is self-contained in a single .c file, then that is all that needs to be done. If, however, the extension module involves multiple files where the C-API is needed then some additional steps must be taken.

void import_array(void)

This function must be called in the initialization section of a module that will make use of the C-API. It imports the module where the function-pointer table is stored and points the correct variable to it.

PY_ARRAY_UNIQUE_SYMBOL
NO_IMPORT_ARRAY

Using these #defines you can use the C-API in multiple files for a single extension module. In each file you must define PY_ARRAY_UNIQUE_SYMBOL to some name that will hold the C-API (e.g. myextension_ARRAY_API). This must be done before including the numpy/arrayobject.h file. In the module intialization routine you call import_array (). In addition, in the files that do not have the module initialization sub_routine define NO_IMPORT_ARRAY prior to including numpy/arrayobject.h.

Suppose I have two files coolmodule.c and coolhelper.c which need to be compiled and linked into a single extension module. Suppose coolmodule.c contains the required initcool module initialization function (with the import_array() function called). Then, coolmodule.c would have at the top:

#define PY_ARRAY_UNIQUE_SYMBOL cool_ARRAY_API
#include numpy/arrayobject.h

On the other hand, coolhelper.c would contain at the top:

#define NO_IMPORT_ARRAY
#define PY_ARRAY_UNIQUE_SYMBOL cool_ARRAY_API
#include numpy/arrayobject.h

You can also put the common two last lines into an extension-local header file as long as you make sure that NO_IMPORT_ARRAY is #defined before #including that file.

Checking the API Version

Because python extensions are not used in the same way as usual libraries on most platforms, some errors cannot be automatically detected at build time or even runtime. For example, if you build an extension using a function available only for numpy >= 1.3.0, and you import the extension later with numpy 1.2, you will not get an import error (but almost certainly a segmentation fault when calling the function). That’s why several functions are provided to check for numpy versions. The macros NPY_VERSION and NPY_FEATURE_VERSION corresponds to the numpy version used to build the extension, whereas the versions returned by the functions PyArray_GetNDArrayCVersion and PyArray_GetNDArrayCFeatureVersion corresponds to the runtime numpy’s version.

The rules for ABI and API compatibilities can be summarized as follows:

  • Whenever NPY_VERSION != PyArray_GetNDArrayCVersion, the extension has to be recompiled (ABI incompatibility).
  • NPY_VERSION == PyArray_GetNDArrayCVersion and NPY_FEATURE_VERSION <= PyArray_GetNDArrayCFeatureVersion means backward compatible changes.

ABI incompatibility is automatically detected in every numpy’s version. API incompatibility detection was added in numpy 1.4.0. If you want to supported many different numpy versions with one extension binary, you have to build your extension with the lowest NPY_FEATURE_VERSION as possible.

unsigned int PyArray_GetNDArrayCVersion(void)

This just returns the value NPY_VERSION. NPY_VERSION changes whenever a backward incompatible change at the ABI level. Because it is in the C-API, however, comparing the output of this function from the value defined in the current header gives a way to test if the C-API has changed thus requiring a re-compilation of extension modules that use the C-API. This is automatically checked in the function import_array.

unsigned int PyArray_GetNDArrayCFeatureVersion(void)

New in version 1.4.0.

This just returns the value NPY_FEATURE_VERSION. NPY_FEATURE_VERSION changes whenever the API changes (e.g. a function is added). A changed value does not always require a recompile.

Internal Flexibility

int PyArray_SetNumericOps( PyObject* dict)

NumPy stores an internal table of Python callable objects that are used to implement arithmetic operations for arrays as well as certain array calculation methods. This function allows the user to replace any or all of these Python objects with their own versions. The keys of the dictionary, dict, are the named functions to replace and the paired value is the Python callable object to use. Care should be taken that the function used to replace an internal array operation does not itself call back to that internal array operation (unless you have designed the function to handle that), or an unchecked infinite recursion can result (possibly causing program crash). The key names that represent operations that can be replaced are:

add, subtract, multiply, divide, remainder, power, square, reciprocal, ones_like, sqrt, negative, absolute, invert, left_shift, right_shift, bitwise_and, bitwise_xor, bitwise_or, less, less_equal, equal, not_equal, greater, greater_equal, floor_divide, true_divide, logical_or, logical_and, floor, ceil, maximum, minimum, rint.

These functions are included here because they are used at least once in the array object’s methods. The function returns -1 (without setting a Python Error) if one of the objects being assigned is not callable.

PyObject* PyArray_GetNumericOps(void)

Return a Python dictionary containing the callable Python objects stored in the the internal arithmetic operation table. The keys of this dictionary are given in the explanation for PyArray_SetNumericOps.

void PyArray_SetStringFunction( PyObject* op, int repr)

This function allows you to alter the tp_str and tp_repr methods of the array object to any Python function. Thus you can alter what happens for all arrays when str(arr) or repr(arr) is called from Python. The function to be called is passed in as op. If repr is non-zero, then this function will be called in response to repr(arr), otherwise the function will be called in response to str(arr). No check on whether or not op is callable is performed. The callable passed in to op should expect an array argument and should return a string to be printed.

Memory management

char* PyDataMem_NEW(size_t nbytes)
PyDataMem_FREE(char* ptr)
char* PyDataMem_RENEW(void * ptr, size_t newbytes)

Macros to allocate, free, and reallocate memory. These macros are used internally to create arrays.

npy_intp* PyDimMem_NEW(nd)
PyDimMem_FREE(npy_intp* ptr)
npy_intp* PyDimMem_RENEW(npy_intp* ptr, npy_intp newnd)

Macros to allocate, free, and reallocate dimension and strides memory.

PyArray_malloc(nbytes)
PyArray_free(ptr)
PyArray_realloc(ptr, nbytes)

These macros use different memory allocators, depending on the constant NPY_USE_PYMEM. The system malloc is used when NPY_USE_PYMEM is 0, if NPY_USE_PYMEM is 1, then the Python memory allocator is used.

Threading support

These macros are only meaningful if NPY_ALLOW_THREADS evaluates True during compilation of the extension module. Otherwise, these macros are equivalent to whitespace. Python uses a single Global Interpreter Lock (GIL) for each Python process so that only a single thread may excecute at a time (even on multi-cpu machines). When calling out to a compiled function that may take time to compute (and does not have side-effects for other threads like updated global variables), the GIL should be released so that other Python threads can run while the time-consuming calculations are performed. This can be accomplished using two groups of macros. Typically, if one macro in a group is used in a code block, all of them must be used in the same code block. Currently, NPY_ALLOW_THREADS is defined to the python-defined WITH_THREADS constant unless the environment variable NPY_NOSMP is set in which case NPY_ALLOW_THREADS is defined to be 0.

Group 1

This group is used to call code that may take some time but does not use any Python C-API calls. Thus, the GIL should be released during its calculation.

NPY_BEGIN_ALLOW_THREADS

Equivalent to Py_BEGIN_ALLOW_THREADS except it uses NPY_ALLOW_THREADS to determine if the macro if replaced with white-space or not.

NPY_END_ALLOW_THREADS

Equivalent to Py_END_ALLOW_THREADS except it uses NPY_ALLOW_THREADS to determine if the macro if replaced with white-space or not.

NPY_BEGIN_THREADS_DEF

Place in the variable declaration area. This macro sets up the variable needed for storing the Python state.

NPY_BEGIN_THREADS

Place right before code that does not need the Python interpreter (no Python C-API calls). This macro saves the Python state and releases the GIL.

NPY_END_THREADS

Place right after code that does not need the Python interpreter. This macro acquires the GIL and restores the Python state from the saved variable.

NPY_BEGIN_THREADS_DESCR( PyArray_Descr *dtype)

Useful to release the GIL only if dtype does not contain arbitrary Python objects which may need the Python interpreter during execution of the loop. Equivalent to

NPY_END_THREADS_DESCR( PyArray_Descr *dtype)

Useful to regain the GIL in situations where it was released using the BEGIN form of this macro.

NPY_BEGIN_THREADS_THRESHOLDED(int loop_size)

Useful to release the GIL only if loop_size exceeds a minimum threshold, currently set to 500. Should be matched with a .. cmacro::NPY_END_THREADS to regain the GIL.

Group 2

This group is used to re-acquire the Python GIL after it has been released. For example, suppose the GIL has been released (using the previous calls), and then some path in the code (perhaps in a different subroutine) requires use of the Python C-API, then these macros are useful to acquire the GIL. These macros accomplish essentially a reverse of the previous three (acquire the LOCK saving what state it had) and then re-release it with the saved state.

NPY_ALLOW_C_API_DEF

Place in the variable declaration area to set up the necessary variable.

NPY_ALLOW_C_API

Place before code that needs to call the Python C-API (when it is known that the GIL has already been released).

NPY_DISABLE_C_API

Place after code that needs to call the Python C-API (to re-release the GIL).

Tip

Never use semicolons after the threading support macros.

Priority

NPY_PRIORITY

Default priority for arrays.

NPY_SUBTYPE_PRIORITY

Default subtype priority.

NPY_SCALAR_PRIORITY

Default scalar priority (very small)

double PyArray_GetPriority( PyObject* obj, double def)

Return the __array_priority__ attribute (converted to a double) of obj or def if no attribute of that name exists. Fast returns that avoid the attribute lookup are provided for objects of type PyArray_Type.

Default buffers

NPY_BUFSIZE

Default size of the user-settable internal buffers.

NPY_MIN_BUFSIZE

Smallest size of user-settable internal buffers.

NPY_MAX_BUFSIZE

Largest size allowed for the user-settable buffers.

Other constants

NPY_NUM_FLOATTYPE

The number of floating-point types

NPY_MAXDIMS

The maximum number of dimensions allowed in arrays.

NPY_VERSION

The current version of the ndarray object (check to see if this variable is defined to guarantee the numpy/arrayobject.h header is being used).

NPY_FALSE

Defined as 0 for use with Bool.

NPY_TRUE

Defined as 1 for use with Bool.

NPY_FAIL

The return value of failed converter functions which are called using the “O&” syntax in PyArg_ParseTuple-like functions.

NPY_SUCCEED

The return value of successful converter functions which are called using the “O&” syntax in PyArg_ParseTuple-like functions.

Miscellaneous Macros

PyArray_SAMESHAPE(a1, a2)

Evaluates as True if arrays a1 and a2 have the same shape.

PyArray_MAX(a, b)

Returns the maximum of a and b. If (a) or (b) are expressions they are evaluated twice.

PyArray_MIN(a, b)

Returns the minimum of a and b. If (a) or (b) are expressions they are evaluated twice.

PyArray_CLT(a, b)
PyArray_CGT(a, b)
PyArray_CLE(a, b)
PyArray_CGE(a, b)
PyArray_CEQ(a, b)
PyArray_CNE(a, b)

Implements the complex comparisons between two complex numbers (structures with a real and imag member) using NumPy’s definition of the ordering which is lexicographic: comparing the real parts first and then the complex parts if the real parts are equal.

PyArray_REFCOUNT( PyObject* op)

Returns the reference count of any Python object.

PyArray_XDECREF_ERR( PyObject *obj)

DECREF’s an array object which may have the NPY_ARRAY_UPDATEIFCOPY flag set without causing the contents to be copied back into the original array. Resets the NPY_ARRAY_WRITEABLE flag on the base object. This is useful for recovering from an error condition when NPY_ARRAY_UPDATEIFCOPY is used.

Enumerated Types

NPY_SORTKIND

A special variable-type which can take on the values NPY_{KIND} where {KIND} is

QUICKSORT, HEAPSORT, MERGESORT
NPY_NSORTS

Defined to be the number of sorts.

NPY_SCALARKIND

A special variable type indicating the number of “kinds” of scalars distinguished in determining scalar-coercion rules. This variable can take on the values NPY_{KIND} where {KIND} can be

NOSCALAR, BOOL_SCALAR, INTPOS_SCALAR, INTNEG_SCALAR, FLOAT_SCALAR, COMPLEX_SCALAR, OBJECT_SCALAR
NPY_NSCALARKINDS

Defined to be the number of scalar kinds (not including NPY_NOSCALAR).

NPY_ORDER

An enumeration type indicating the element order that an array should be interpreted in. When a brand new array is created, generally only NPY_CORDER and NPY_FORTRANORDER are used, whereas when one or more inputs are provided, the order can be based on them.

NPY_ANYORDER

Fortran order if all the inputs are Fortran, C otherwise.

NPY_CORDER

C order.

NPY_FORTRANORDER

Fortran order.

NPY_KEEPORDER

An order as close to the order of the inputs as possible, even if the input is in neither C nor Fortran order.

NPY_CLIPMODE

A variable type indicating the kind of clipping that should be applied in certain functions.

NPY_RAISE

The default for most operations, raises an exception if an index is out of bounds.

NPY_CLIP

Clips an index to the valid range if it is out of bounds.

NPY_WRAP

Wraps an index to the valid range if it is out of bounds.

NPY_CASTING

New in version 1.6.

An enumeration type indicating how permissive data conversions should be. This is used by the iterator added in NumPy 1.6, and is intended to be used more broadly in a future version.

NPY_NO_CASTING

Only allow identical types.

NPY_EQUIV_CASTING

Allow identical and casts involving byte swapping.

NPY_SAFE_CASTING

Only allow casts which will not cause values to be rounded, truncated, or otherwise changed.

NPY_SAME_KIND_CASTING

Allow any safe casts, and casts between types of the same kind. For example, float64 -> float32 is permitted with this rule.

NPY_UNSAFE_CASTING

Allow any cast, no matter what kind of data loss may occur.


Array Iterator API

  • Numpy C-API
  • next
  • previous

Table Of Contents

  • Array Iterator API
    • Array Iterator
    • Converting from Previous NumPy Iterators
    • Simple Iteration Example
    • Simple Multi-Iteration Example
    • Iterator Data Types
    • Construction and Destruction
    • Functions For Iteration

Previous topic

Array API

Next topic

UFunc API

Array Iterator API

New in version 1.6.

Array Iterator

The array iterator encapsulates many of the key features in ufuncs, allowing user code to support features like output parameters, preservation of memory layouts, and buffering of data with the wrong alignment or type, without requiring difficult coding.

This page documents the API for the iterator. The C-API naming convention chosen is based on the one in the numpy-refactor branch, so will integrate naturally into the refactored code base. The iterator is named NpyIter and functions are named NpyIter_*.

There is an introductory guide to array iteration which may be of interest for those using this C API. In many instances, testing out ideas by creating the iterator in Python is a good idea before writing the C iteration code.

Converting from Previous NumPy Iterators

The existing iterator API includes functions like PyArrayIter_Check, PyArray_Iter* and PyArray_ITER_*. The multi-iterator array includes PyArray_MultiIter*, PyArray_Broadcast, and PyArray_RemoveSmallest. The new iterator design replaces all of this functionality with a single object and associated API. One goal of the new API is that all uses of the existing iterator should be replaceable with the new iterator without significant effort. In 1.6, the major exception to this is the neighborhood iterator, which does not have corresponding features in this iterator.

Here is a conversion table for which functions to use with the new iterator:

Iterator Functions |
PyArray_IterNew | NpyIter_New
PyArray_IterAllButAxis | NpyIter_New + axes parameter or Iterator flag NPY_ITER_EXTERNAL_LOOP
PyArray_BroadcastToShape | NOT SUPPORTED (Use the support for multiple operands instead.)
PyArrayIter_Check | Will need to add this in Python exposure
PyArray_ITER_RESET | NpyIter_Reset
PyArray_ITER_NEXT | Function pointer from NpyIter_GetIterNext
PyArray_ITER_DATA | NpyIter_GetDataPtrArray
PyArray_ITER_GOTO | NpyIter_GotoMultiIndex
PyArray_ITER_GOTO1D | NpyIter_GotoIndex or NpyIter_GotoIterIndex
PyArray_ITER_NOTDONE | Return value of iternext function pointer
Multi-iterator Functions |
PyArray_MultiIterNew | NpyIter_MultiNew
PyArray_MultiIter_RESET | NpyIter_Reset
PyArray_MultiIter_NEXT | Function pointer from NpyIter_GetIterNext
PyArray_MultiIter_DATA | NpyIter_GetDataPtrArray
PyArray_MultiIter_NEXTi | NOT SUPPORTED (always lock-step iteration)
PyArray_MultiIter_GOTO | NpyIter_GotoMultiIndex
PyArray_MultiIter_GOTO1D | NpyIter_GotoIndex or NpyIter_GotoIterIndex
PyArray_MultiIter_NOTDONE | Return value of iternext function pointer
PyArray_Broadcast | Handled by NpyIter_MultiNew
PyArray_RemoveSmallest | Iterator flag NPY_ITER_EXTERNAL_LOOP
Other Functions |
PyArray_ConvertToCommonType | Iterator flag NPY_ITER_COMMON_DTYPE

Simple Iteration Example

The best way to become familiar with the iterator is to look at its usage within the NumPy codebase itself. For example, here is a slightly tweaked version of the code for PyArray_CountNonzero, which counts the number of non-zero elements in an array.

npy_intp PyArray_CountNonzero(PyArrayObject* self)
{
    /* Nonzero boolean function */
    PyArray_NonzeroFunc* nonzero = PyArray_DESCR(self)->f->nonzero;

    NpyIter* iter;
    NpyIter_IterNextFunc *iternext;
    char** dataptr;
    npy_intp* strideptr,* innersizeptr;

    /* Handle zero-sized arrays specially */
    if (PyArray_SIZE(self) == 0) {
        return 0;
    }

    /*
     * Create and use an iterator to count the nonzeros.
     *   flag NPY_ITER_READONLY
     *     - The array is never written to.
     *   flag NPY_ITER_EXTERNAL_LOOP
     *     - Inner loop is done outside the iterator for efficiency.
     *   flag NPY_ITER_NPY_ITER_REFS_OK
     *     - Reference types are acceptable.
     *   order NPY_KEEPORDER
     *     - Visit elements in memory order, regardless of strides.
     *       This is good for performance when the specific order
     *       elements are visited is unimportant.
     *   casting NPY_NO_CASTING
     *     - No casting is required for this operation.
     */
    iter = NpyIter_New(self, NPY_ITER_READONLY|
                             NPY_ITER_EXTERNAL_LOOP|
                             NPY_ITER_REFS_OK,
                        NPY_KEEPORDER, NPY_NO_CASTING,
                        NULL);
    if (iter == NULL) {
        return -1;
    }

    /*
     * The iternext function gets stored in a local variable
     * so it can be called repeatedly in an efficient manner.
     */
    iternext = NpyIter_GetIterNext(iter, NULL);
    if (iternext == NULL) {
        NpyIter_Deallocate(iter);
        return -1;
    }
    /* The location of the data pointer which the iterator may update */
    dataptr = NpyIter_GetDataPtrArray(iter);
    /* The location of the stride which the iterator may update */
    strideptr = NpyIter_GetInnerStrideArray(iter);
    /* The location of the inner loop size which the iterator may update */
    innersizeptr = NpyIter_GetInnerLoopSizePtr(iter);

    /* The iteration loop */
    do {
        /* Get the inner loop data/stride/count values */
        char* data = *dataptr;
        npy_intp stride = *strideptr;
        npy_intp count = *innersizeptr;

        /* This is a typical inner loop for NPY_ITER_EXTERNAL_LOOP */
        while (count--) {
            if (nonzero(data, self)) {
                ++nonzero_count;
            }
            data += stride;
        }

        /* Increment the iterator to the next inner loop */
    } while(iternext(iter));

    NpyIter_Deallocate(iter);

    return nonzero_count;
}

Simple Multi-Iteration Example

Here is a simple copy function using the iterator. The order parameter is used to control the memory layout of the allocated result, typically NPY_KEEPORDER is desired.

PyObject *CopyArray(PyObject *arr, NPY_ORDER order)
{
    NpyIter *iter;
    NpyIter_IterNextFunc *iternext;
    PyObject *op[2], *ret;
    npy_uint32 flags;
    npy_uint32 op_flags[2];
    npy_intp itemsize, *innersizeptr, innerstride;
    char **dataptrarray;

    /*
     * No inner iteration - inner loop is handled by CopyArray code
     */
    flags = NPY_ITER_EXTERNAL_LOOP;
    /*
     * Tell the constructor to automatically allocate the output.
     * The data type of the output will match that of the input.
     */
    op[0] = arr;
    op[1] = NULL;
    op_flags[0] = NPY_ITER_READONLY;
    op_flags[1] = NPY_ITER_WRITEONLY | NPY_ITER_ALLOCATE;

    /* Construct the iterator */
    iter = NpyIter_MultiNew(2, op, flags, order, NPY_NO_CASTING,
                            op_flags, NULL);
    if (iter == NULL) {
        return NULL;
    }

    /*
     * Make a copy of the iternext function pointer and
     * a few other variables the inner loop needs.
     */
    iternext = NpyIter_GetIterNext(iter, NULL);
    innerstride = NpyIter_GetInnerStrideArray(iter)[0];
    itemsize = NpyIter_GetDescrArray(iter)[0]->elsize;
    /*
     * The inner loop size and data pointers may change during the
     * loop, so just cache the addresses.
     */
    innersizeptr = NpyIter_GetInnerLoopSizePtr(iter);
    dataptrarray = NpyIter_GetDataPtrArray(iter);

    /*
     * Note that because the iterator allocated the output,
     * it matches the iteration order and is packed tightly,
     * so we don't need to check it like the input.
     */
    if (innerstride == itemsize) {
        do {
            memcpy(dataptrarray[1], dataptrarray[0],
                                    itemsize * (*innersizeptr));
        } while (iternext(iter));
    } else {
        /* For efficiency, should specialize this based on item size... */
        npy_intp i;
        do {
            npy_intp size = *innersizeptr;
            char *src = dataptrarray[0], *dst = dataptrarray[1];
            for(i = 0; i < size; i++, src += innerstride, dst += itemsize) {
                memcpy(dst, src, itemsize);
            }
        } while (iternext(iter));
    }

    /* Get the result from the iterator object array */
    ret = NpyIter_GetOperandArray(iter)[1];
    Py_INCREF(ret);

    if (NpyIter_Deallocate(iter) != NPY_SUCCEED) {
        Py_DECREF(ret);
        return NULL;
    }

    return ret;
}

Iterator Data Types

The iterator layout is an internal detail, and user code only sees an incomplete struct.

NpyIter

This is an opaque pointer type for the iterator. Access to its contents can only be done through the iterator API.

NpyIter_Type

This is the type which exposes the iterator to Python. Currently, no API is exposed which provides access to the values of a Python-created iterator. If an iterator is created in Python, it must be used in Python and vice versa. Such an API will likely be created in a future version.

NpyIter_IterNextFunc

This is a function pointer for the iteration loop, returned by NpyIter_GetIterNext.

NpyIter_GetMultiIndexFunc

This is a function pointer for getting the current iterator multi-index, returned by NpyIter_GetGetMultiIndex.

Construction and Destruction

NpyIter* NpyIter_New( PyArrayObject* op, npy_uint32 flags, NPY_ORDER order, NPY_CASTING casting, PyArray_Descr* dtype)

Creates an iterator for the given numpy array object op.

Flags that may be passed in flags are any combination of the global and per-operand flags documented in NpyIter_MultiNew, except for NPY_ITER_ALLOCATE.

Any of the NPY_ORDER enum values may be passed to order. For efficient iteration, NPY_KEEPORDER is the best option, and the other orders enforce the particular iteration pattern.

Any of the NPY_CASTING enum values may be passed to casting. The values include NPY_NO_CASTING, NPY_EQUIV_CASTING, NPY_SAFE_CASTING, NPY_SAME_KIND_CASTING, and NPY_UNSAFE_CASTING. To allow the casts to occur, copying or buffering must also be enabled.

If dtype isn’t NULL, then it requires that data type. If copying is allowed, it will make a temporary copy if the data is castable. If NPY_ITER_UPDATEIFCOPY is enabled, it will also copy the data back with another cast upon iterator destruction.

Returns NULL if there is an error, otherwise returns the allocated iterator.

To make an iterator similar to the old iterator, this should work.

iter = NpyIter_New(op, NPY_ITER_READWRITE,
                    NPY_CORDER, NPY_NO_CASTING, NULL);

If you want to edit an array with aligned double code, but the order doesn’t matter, you would use this.

dtype = PyArray_DescrFromType(NPY_DOUBLE);
iter = NpyIter_New(op, NPY_ITER_READWRITE|
                    NPY_ITER_BUFFERED|
                    NPY_ITER_NBO|
                    NPY_ITER_ALIGNED,
                    NPY_KEEPORDER,
                    NPY_SAME_KIND_CASTING,
                    dtype);
Py_DECREF(dtype);
NpyIter* NpyIter_MultiNew(npy_intp nop, PyArrayObject** op, npy_uint32 flags, NPY_ORDER order, NPY_CASTING casting, npy_uint32* op_flags, PyArray_Descr** op_dtypes)

Creates an iterator for broadcasting the nop array objects provided in op, using regular NumPy broadcasting rules.

Any of the NPY_ORDER enum values may be passed to order. For efficient iteration, NPY_KEEPORDER is the best option, and the other orders enforce the particular iteration pattern. When using NPY_KEEPORDER, if you also want to ensure that the iteration is not reversed along an axis, you should pass the flag NPY_ITER_DONT_NEGATE_STRIDES.

Any of the NPY_CASTING enum values may be passed to casting. The values include NPY_NO_CASTING, NPY_EQUIV_CASTING, NPY_SAFE_CASTING, NPY_SAME_KIND_CASTING, and NPY_UNSAFE_CASTING. To allow the casts to occur, copying or buffering must also be enabled.

If op_dtypes isn’t NULL, it specifies a data type or NULL for each op[i].

Returns NULL if there is an error, otherwise returns the allocated iterator.

Flags that may be passed in flags, applying to the whole iterator, are:

NPY_ITER_C_INDEX

Causes the iterator to track a raveled flat index matching C order. This option cannot be used with NPY_ITER_F_INDEX.

NPY_ITER_F_INDEX

Causes the iterator to track a raveled flat index matching Fortran order. This option cannot be used with NPY_ITER_C_INDEX.

NPY_ITER_MULTI_INDEX

Causes the iterator to track a multi-index. This prevents the iterator from coalescing axes to produce bigger inner loops. If the loop is also not buffered and no index is being tracked (NpyIter_RemoveAxis can be called), then the iterator size can be -1 to indicate that the iterator is too large. This can happen due to complex broadcasting and will result in errors being created when the setting the iterator range, removing the multi index, or getting the next function. However, it is possible to remove axes again and use the iterator normally if the size is small enough after removal.

NPY_ITER_EXTERNAL_LOOP

Causes the iterator to skip iteration of the innermost loop, requiring the user of the iterator to handle it.

This flag is incompatible with NPY_ITER_C_INDEX, NPY_ITER_F_INDEX, and NPY_ITER_MULTI_INDEX.

NPY_ITER_DONT_NEGATE_STRIDES

This only affects the iterator when NPY_KEEPORDER is specified for the order parameter. By default with NPY_KEEPORDER, the iterator reverses axes which have negative strides, so that memory is traversed in a forward direction. This disables this step. Use this flag if you want to use the underlying memory-ordering of the axes, but don’t want an axis reversed. This is the behavior of numpy.ravel(a, order='K'), for instance.

NPY_ITER_COMMON_DTYPE

Causes the iterator to convert all the operands to a common data type, calculated based on the ufunc type promotion rules. Copying or buffering must be enabled.

If the common data type is known ahead of time, don’t use this flag. Instead, set the requested dtype for all the operands.

NPY_ITER_REFS_OK

Indicates that arrays with reference types (object arrays or structured arrays containing an object type) may be accepted and used in the iterator. If this flag is enabled, the caller must be sure to check whether :cfunc:`NpyIter_IterationNeedsAPI`(iter) is true, in which case it may not release the GIL during iteration.

NPY_ITER_ZEROSIZE_OK

Indicates that arrays with a size of zero should be permitted. Since the typical iteration loop does not naturally work with zero-sized arrays, you must check that the IterSize is larger than zero before entering the iteration loop. Currently only the operands are checked, not a forced shape.

NPY_ITER_REDUCE_OK

Permits writeable operands with a dimension with zero stride and size greater than one. Note that such operands must be read/write.

When buffering is enabled, this also switches to a special buffering mode which reduces the loop length as necessary to not trample on values being reduced.

Note that if you want to do a reduction on an automatically allocated output, you must use NpyIter_GetOperandArray to get its reference, then set every value to the reduction unit before doing the iteration loop. In the case of a buffered reduction, this means you must also specify the flag NPY_ITER_DELAY_BUFALLOC, then reset the iterator after initializing the allocated operand to prepare the buffers.

NPY_ITER_RANGED

Enables support for iteration of sub-ranges of the full iterindex range [0, NpyIter_IterSize(iter)). Use the function NpyIter_ResetToIterIndexRange to specify a range for iteration.

This flag can only be used with NPY_ITER_EXTERNAL_LOOP when NPY_ITER_BUFFERED is enabled. This is because without buffering, the inner loop is always the size of the innermost iteration dimension, and allowing it to get cut up would require special handling, effectively making it more like the buffered version.

NPY_ITER_BUFFERED

Causes the iterator to store buffering data, and use buffering to satisfy data type, alignment, and byte-order requirements. To buffer an operand, do not specify the NPY_ITER_COPY or NPY_ITER_UPDATEIFCOPY flags, because they will override buffering. Buffering is especially useful for Python code using the iterator, allowing for larger chunks of data at once to amortize the Python interpreter overhead.

If used with NPY_ITER_EXTERNAL_LOOP, the inner loop for the caller may get larger chunks than would be possible without buffering, because of how the strides are laid out.

Note that if an operand is given the flag NPY_ITER_COPY or NPY_ITER_UPDATEIFCOPY, a copy will be made in preference to buffering. Buffering will still occur when the array was broadcast so elements need to be duplicated to get a constant stride.

In normal buffering, the size of each inner loop is equal to the buffer size, or possibly larger if NPY_ITER_GROWINNER is specified. If NPY_ITER_REDUCE_OK is enabled and a reduction occurs, the inner loops may become smaller depending on the structure of the reduction.

NPY_ITER_GROWINNER

When buffering is enabled, this allows the size of the inner loop to grow when buffering isn’t necessary. This option is best used if you’re doing a straight pass through all the data, rather than anything with small cache-friendly arrays of temporary values for each inner loop.

NPY_ITER_DELAY_BUFALLOC

When buffering is enabled, this delays allocation of the buffers until NpyIter_Reset or another reset function is called. This flag exists to avoid wasteful copying of buffer data when making multiple copies of a buffered iterator for multi-threaded iteration.

Another use of this flag is for setting up reduction operations. After the iterator is created, and a reduction output is allocated automatically by the iterator (be sure to use READWRITE access), its value may be initialized to the reduction unit. Use NpyIter_GetOperandArray to get the object. Then, call NpyIter_Reset to allocate and fill the buffers with their initial values.

Flags that may be passed in op_flags[i], where 0 <= i < nop:

NPY_ITER_READWRITE
NPY_ITER_READONLY
NPY_ITER_WRITEONLY

Indicate how the user of the iterator will read or write to op[i]. Exactly one of these flags must be specified per operand.

NPY_ITER_COPY

Allow a copy of op[i] to be made if it does not meet the data type or alignment requirements as specified by the constructor flags and parameters.

NPY_ITER_UPDATEIFCOPY

Triggers NPY_ITER_COPY, and when an array operand is flagged for writing and is copied, causes the data in a copy to be copied back to op[i] when the iterator is destroyed.

If the operand is flagged as write-only and a copy is needed, an uninitialized temporary array will be created and then copied to back to op[i] on destruction, instead of doing the unecessary copy operation.

NPY_ITER_NBO
NPY_ITER_ALIGNED
NPY_ITER_CONTIG

Causes the iterator to provide data for op[i] that is in native byte order, aligned according to the dtype requirements, contiguous, or any combination.

By default, the iterator produces pointers into the arrays provided, which may be aligned or unaligned, and with any byte order. If copying or buffering is not enabled and the operand data doesn’t satisfy the constraints, an error will be raised.

The contiguous constraint applies only to the inner loop, successive inner loops may have arbitrary pointer changes.

If the requested data type is in non-native byte order, the NBO flag overrides it and the requested data type is converted to be in native byte order.

NPY_ITER_ALLOCATE

This is for output arrays, and requires that the flag NPY_ITER_WRITEONLY or NPY_ITER_READWRITE be set. If op[i] is NULL, creates a new array with the final broadcast dimensions, and a layout matching the iteration order of the iterator.

When op[i] is NULL, the requested data type op_dtypes[i] may be NULL as well, in which case it is automatically generated from the dtypes of the arrays which are flagged as readable. The rules for generating the dtype are the same is for UFuncs. Of special note is handling of byte order in the selected dtype. If there is exactly one input, the input’s dtype is used as is. Otherwise, if more than one input dtypes are combined together, the output will be in native byte order.

After being allocated with this flag, the caller may retrieve the new array by calling NpyIter_GetOperandArray and getting the i-th object in the returned C array. The caller must call Py_INCREF on it to claim a reference to the array.

NPY_ITER_NO_SUBTYPE

For use with NPY_ITER_ALLOCATE, this flag disables allocating an array subtype for the output, forcing it to be a straight ndarray.

TODO: Maybe it would be better to introduce a function NpyIter_GetWrappedOutput and remove this flag?

NPY_ITER_NO_BROADCAST

Ensures that the input or output matches the iteration dimensions exactly.

NPY_ITER_ARRAYMASK

New in version 1.7.

Indicates that this operand is the mask to use for selecting elements when writing to operands which have the NPY_ITER_WRITEMASKED flag applied to them. Only one operand may have NPY_ITER_ARRAYMASK flag applied to it.

The data type of an operand with this flag should be either NPY_BOOL, NPY_MASK, or a struct dtype whose fields are all valid mask dtypes. In the latter case, it must match up with a struct operand being WRITEMASKED, as it is specifying a mask for each field of that array.

This flag only affects writing from the buffer back to the array. This means that if the operand is also NPY_ITER_READWRITE or NPY_ITER_WRITEONLY, code doing iteration can write to this operand to control which elements will be untouched and which ones will be modified. This is useful when the mask should be a combination of input masks, for example. Mask values can be created with the NpyMask_Create function.

NPY_ITER_WRITEMASKED

New in version 1.7.

Indicates that only elements which the operand with the ARRAYMASK flag indicates are intended to be modified by the iteration. In general, the iterator does not enforce this, it is up to the code doing the iteration to follow that promise. Code can use the NpyMask_IsExposed inline function to test whether the mask at a particular element allows writing.

When this flag is used, and this operand is buffered, this changes how data is copied from the buffer into the array. A masked copying routine is used, which only copies the elements in the buffer for which NpyMask_IsExposed returns true from the corresponding element in the ARRAYMASK operand.

NpyIter* NpyIter_AdvancedNew(npy_intp nop, PyArrayObject** op, npy_uint32 flags, NPY_ORDER order, NPY_CASTING casting, npy_uint32* op_flags, PyArray_Descr** op_dtypes, int oa_ndim, int** op_axes, npy_intp* itershape, npy_intp buffersize)

Extends NpyIter_MultiNew with several advanced options providing more control over broadcasting and buffering.

If -1/NULL values are passed to oa_ndim, op_axes, itershape, and buffersize, it is equivalent to NpyIter_MultiNew.

The parameter oa_ndim, when not zero or -1, specifies the number of dimensions that will be iterated with customized broadcasting. If it is provided, op_axes must and itershape can also be provided. The op_axes parameter let you control in detail how the axes of the operand arrays get matched together and iterated. In op_axes, you must provide an array of nop pointers to oa_ndim-sized arrays of type npy_intp. If an entry in op_axes is NULL, normal broadcasting rules will apply. In op_axes[j][i] is stored either a valid axis of op[j], or -1 which means newaxis. Within each op_axes[j] array, axes may not be repeated. The following example is how normal broadcasting applies to a 3-D array, a 2-D array, a 1-D array and a scalar.

Note: Before NumPy 1.8 oa_ndim == 0` was used for signalling that that ``op_axes and itershape are unused. This is deprecated and should be replaced with -1. Better backward compatibility may be achieved by using NpyIter_MultiNew for this case.

int oa_ndim = 3;               /* # iteration axes */
int op0_axes[] = {0, 1, 2};    /* 3-D operand */
int op1_axes[] = {-1, 0, 1};   /* 2-D operand */
int op2_axes[] = {-1, -1, 0};  /* 1-D operand */
int op3_axes[] = {-1, -1, -1}  /* 0-D (scalar) operand */
int* op_axes[] = {op0_axes, op1_axes, op2_axes, op3_axes};

The itershape parameter allows you to force the iterator to have a specific iteration shape. It is an array of length oa_ndim. When an entry is negative, its value is determined from the operands. This parameter allows automatically allocated outputs to get additional dimensions which don’t match up with any dimension of an input.

If buffersize is zero, a default buffer size is used, otherwise it specifies how big of a buffer to use. Buffers which are powers of 2 such as 4096 or 8192 are recommended.

Returns NULL if there is an error, otherwise returns the allocated iterator.

NpyIter* NpyIter_Copy( NpyIter* iter)

Makes a copy of the given iterator. This function is provided primarily to enable multi-threaded iteration of the data.

TODO: Move this to a section about multithreaded iteration.

The recommended approach to multithreaded iteration is to first create an iterator with the flags NPY_ITER_EXTERNAL_LOOP, NPY_ITER_RANGED, NPY_ITER_BUFFERED, NPY_ITER_DELAY_BUFALLOC, and possibly NPY_ITER_GROWINNER. Create a copy of this iterator for each thread (minus one for the first iterator). Then, take the iteration index range [0, NpyIter_GetIterSize(iter)) and split it up into tasks, for example using a TBB parallel_for loop. When a thread gets a task to execute, it then uses its copy of the iterator by calling NpyIter_ResetToIterIndexRange and iterating over the full range.

When using the iterator in multi-threaded code or in code not holding the Python GIL, care must be taken to only call functions which are safe in that context. NpyIter_Copy cannot be safely called without the Python GIL, because it increments Python references. The Reset* and some other functions may be safely called by passing in the errmsg parameter as non-NULL, so that the functions will pass back errors through it instead of setting a Python exception.

int NpyIter_RemoveAxis(NpyIter* iter, int axis)``

Removes an axis from iteration. This requires that NPY_ITER_MULTI_INDEX was set for iterator creation, and does not work if buffering is enabled or an index is being tracked. This function also resets the iterator to its initial state.

This is useful for setting up an accumulation loop, for example. The iterator can first be created with all the dimensions, including the accumulation axis, so that the output gets created correctly. Then, the accumulation axis can be removed, and the calculation done in a nested fashion.

WARNING: This function may change the internal memory layout of the iterator. Any cached functions or pointers from the iterator must be retrieved again! The iterator range will be reset as well.

Returns NPY_SUCCEED or NPY_FAIL.

int NpyIter_RemoveMultiIndex( NpyIter* iter)

If the iterator is tracking a multi-index, this strips support for them, and does further iterator optimizations that are possible if multi-indices are not needed. This function also resets the iterator to its initial state.

WARNING: This function may change the internal memory layout of the iterator. Any cached functions or pointers from the iterator must be retrieved again!

After calling this function, :cfunc:`NpyIter_HasMultiIndex`(iter) will return false.

Returns NPY_SUCCEED or NPY_FAIL.

int NpyIter_EnableExternalLoop( NpyIter* iter)

If NpyIter_RemoveMultiIndex was called, you may want to enable the flag NPY_ITER_EXTERNAL_LOOP. This flag is not permitted together with NPY_ITER_MULTI_INDEX, so this function is provided to enable the feature after NpyIter_RemoveMultiIndex is called. This function also resets the iterator to its initial state.

WARNING: This function changes the internal logic of the iterator. Any cached functions or pointers from the iterator must be retrieved again!

Returns NPY_SUCCEED or NPY_FAIL.

int NpyIter_Deallocate( NpyIter* iter)

Deallocates the iterator object. This additionally frees any copies made, triggering UPDATEIFCOPY behavior where necessary.

Returns NPY_SUCCEED or NPY_FAIL.

int NpyIter_Reset( NpyIter* iter, char** errmsg)

Resets the iterator back to its initial state, at the beginning of the iteration range.

Returns NPY_SUCCEED or NPY_FAIL. If errmsg is non-NULL, no Python exception is set when NPY_FAIL is returned. Instead, *errmsg is set to an error message. When errmsg is non-NULL, the function may be safely called without holding the Python GIL.

int NpyIter_ResetToIterIndexRange( NpyIter* iter, npy_intp istart, npy_intp iend, char** errmsg)

Resets the iterator and restricts it to the iterindex range [istart, iend). See NpyIter_Copy for an explanation of how to use this for multi-threaded iteration. This requires that the flag NPY_ITER_RANGED was passed to the iterator constructor.

If you want to reset both the iterindex range and the base pointers at the same time, you can do the following to avoid extra buffer copying (be sure to add the return code error checks when you copy this code).

/* Set to a trivial empty range */
NpyIter_ResetToIterIndexRange(iter, 0, 0);
/* Set the base pointers */
NpyIter_ResetBasePointers(iter, baseptrs);
/* Set to the desired range */
NpyIter_ResetToIterIndexRange(iter, istart, iend);

Returns NPY_SUCCEED or NPY_FAIL. If errmsg is non-NULL, no Python exception is set when NPY_FAIL is returned. Instead, *errmsg is set to an error message. When errmsg is non-NULL, the function may be safely called without holding the Python GIL.

int NpyIter_ResetBasePointers( NpyIter *iter, char** baseptrs, char** errmsg)

Resets the iterator back to its initial state, but using the values in baseptrs for the data instead of the pointers from the arrays being iterated. This functions is intended to be used, together with the op_axes parameter, by nested iteration code with two or more iterators.

Returns NPY_SUCCEED or NPY_FAIL. If errmsg is non-NULL, no Python exception is set when NPY_FAIL is returned. Instead, *errmsg is set to an error message. When errmsg is non-NULL, the function may be safely called without holding the Python GIL.

TODO: Move the following into a special section on nested iterators.

Creating iterators for nested iteration requires some care. All the iterator operands must match exactly, or the calls to NpyIter_ResetBasePointers will be invalid. This means that automatic copies and output allocation should not be used haphazardly. It is possible to still use the automatic data conversion and casting features of the iterator by creating one of the iterators with all the conversion parameters enabled, then grabbing the allocated operands with the NpyIter_GetOperandArray function and passing them into the constructors for the rest of the iterators.

WARNING: When creating iterators for nested iteration, the code must not use a dimension more than once in the different iterators. If this is done, nested iteration will produce out-of-bounds pointers during iteration.

WARNING: When creating iterators for nested iteration, buffering can only be applied to the innermost iterator. If a buffered iterator is used as the source for baseptrs, it will point into a small buffer instead of the array and the inner iteration will be invalid.

The pattern for using nested iterators is as follows.

NpyIter *iter1, *iter1;
NpyIter_IterNextFunc *iternext1, *iternext2;
char **dataptrs1;

/*
 * With the exact same operands, no copies allowed, and
 * no axis in op_axes used both in iter1 and iter2.
 * Buffering may be enabled for iter2, but not for iter1.
 */
iter1 = ...; iter2 = ...;

iternext1 = NpyIter_GetIterNext(iter1);
iternext2 = NpyIter_GetIterNext(iter2);
dataptrs1 = NpyIter_GetDataPtrArray(iter1);

do {
    NpyIter_ResetBasePointers(iter2, dataptrs1);
    do {
        /* Use the iter2 values */
    } while (iternext2(iter2));
} while (iternext1(iter1));
int NpyIter_GotoMultiIndex( NpyIter* iter, npy_intp* multi_index)

Adjusts the iterator to point to the ndim indices pointed to by multi_index. Returns an error if a multi-index is not being tracked, the indices are out of bounds, or inner loop iteration is disabled.

Returns NPY_SUCCEED or NPY_FAIL.

int NpyIter_GotoIndex( NpyIter* iter, npy_intp index)

Adjusts the iterator to point to the index specified. If the iterator was constructed with the flag NPY_ITER_C_INDEX, index is the C-order index, and if the iterator was constructed with the flag NPY_ITER_F_INDEX, index is the Fortran-order index. Returns an error if there is no index being tracked, the index is out of bounds, or inner loop iteration is disabled.

Returns NPY_SUCCEED or NPY_FAIL.

npy_intp NpyIter_GetIterSize( NpyIter* iter)

Returns the number of elements being iterated. This is the product of all the dimensions in the shape. When a multi index is being tracked (and NpyIter_RemoveAxis may be called) the size may be -1 to indicate an iterator is too large. Such an iterator is invalid, but may become valid after NpyIter_RemoveAxis is called. It is not necessary to check for this case.

npy_intp NpyIter_GetIterIndex( NpyIter* iter)

Gets the iterindex of the iterator, which is an index matching the iteration order of the iterator.

void NpyIter_GetIterIndexRange( NpyIter* iter, npy_intp* istart, npy_intp* iend)

Gets the iterindex sub-range that is being iterated. If NPY_ITER_RANGED was not specified, this always returns the range [0, NpyIter_IterSize(iter)).

int NpyIter_GotoIterIndex( NpyIter* iter, npy_intp iterindex)

Adjusts the iterator to point to the iterindex specified. The IterIndex is an index matching the iteration order of the iterator. Returns an error if the iterindex is out of bounds, buffering is enabled, or inner loop iteration is disabled.

Returns NPY_SUCCEED or NPY_FAIL.

npy_bool NpyIter_HasDelayedBufAlloc( NpyIter* iter)

Returns 1 if the flag NPY_ITER_DELAY_BUFALLOC was passed to the iterator constructor, and no call to one of the Reset functions has been done yet, 0 otherwise.

npy_bool NpyIter_HasExternalLoop( NpyIter* iter)

Returns 1 if the caller needs to handle the inner-most 1-dimensional loop, or 0 if the iterator handles all looping. This is controlled by the constructor flag NPY_ITER_EXTERNAL_LOOP or NpyIter_EnableExternalLoop.

npy_bool NpyIter_HasMultiIndex( NpyIter* iter)

Returns 1 if the iterator was created with the NPY_ITER_MULTI_INDEX flag, 0 otherwise.

npy_bool NpyIter_HasIndex( NpyIter* iter)

Returns 1 if the iterator was created with the NPY_ITER_C_INDEX or NPY_ITER_F_INDEX flag, 0 otherwise.

npy_bool NpyIter_RequiresBuffering( NpyIter* iter)

Returns 1 if the iterator requires buffering, which occurs when an operand needs conversion or alignment and so cannot be used directly.

npy_bool NpyIter_IsBuffered( NpyIter* iter)

Returns 1 if the iterator was created with the NPY_ITER_BUFFERED flag, 0 otherwise.

npy_bool NpyIter_IsGrowInner( NpyIter* iter)

Returns 1 if the iterator was created with the NPY_ITER_GROWINNER flag, 0 otherwise.

npy_intp NpyIter_GetBufferSize( NpyIter* iter)

If the iterator is buffered, returns the size of the buffer being used, otherwise returns 0.

int NpyIter_GetNDim( NpyIter* iter)

Returns the number of dimensions being iterated. If a multi-index was not requested in the iterator constructor, this value may be smaller than the number of dimensions in the original objects.

int NpyIter_GetNOp( NpyIter* iter)

Returns the number of operands in the iterator.

When NPY_ITER_USE_MASKNA is used on an operand, a new operand is added to the end of the operand list in the iterator to track that operand’s NA mask. Thus, this equals the number of construction operands plus the number of operands for which the flag NPY_ITER_USE_MASKNA was specified.

int NpyIter_GetFirstMaskNAOp( NpyIter* iter)

New in version 1.7.

Returns the index of the first NA mask operand in the array. This value is equal to the number of operands passed into the constructor.

npy_intp* NpyIter_GetAxisStrideArray( NpyIter* iter, int axis)

Gets the array of strides for the specified axis. Requires that the iterator be tracking a multi-index, and that buffering not be enabled.

This may be used when you want to match up operand axes in some fashion, then remove them with NpyIter_RemoveAxis to handle their processing manually. By calling this function before removing the axes, you can get the strides for the manual processing.

Returns NULL on error.

int NpyIter_GetShape( NpyIter* iter, npy_intp* outshape)

Returns the broadcast shape of the iterator in outshape. This can only be called on an iterator which is tracking a multi-index.

Returns NPY_SUCCEED or NPY_FAIL.

PyArray_Descr** NpyIter_GetDescrArray( NpyIter* iter)

This gives back a pointer to the nop data type Descrs for the objects being iterated. The result points into iter, so the caller does not gain any references to the Descrs.

This pointer may be cached before the iteration loop, calling iternext will not change it.

PyObject** NpyIter_GetOperandArray( NpyIter* iter)

This gives back a pointer to the nop operand PyObjects that are being iterated. The result points into iter, so the caller does not gain any references to the PyObjects.

npy_int8* NpyIter_GetMaskNAIndexArray( NpyIter* iter)

New in version 1.7.

This gives back a pointer to the nop indices which map construction operands with NPY_ITER_USE_MASKNA flagged to their corresponding NA mask operands and vice versa. For operands which were not flagged with NPY_ITER_USE_MASKNA, this array contains negative values.

PyObject* NpyIter_GetIterView( NpyIter* iter, npy_intp i)

This gives back a reference to a new ndarray view, which is a view into the i-th object in the array :cfunc:`NpyIter_GetOperandArray`(), whose dimensions and strides match the internal optimized iteration pattern. A C-order iteration of this view is equivalent to the iterator’s iteration order.

For example, if an iterator was created with a single array as its input, and it was possible to rearrange all its axes and then collapse it into a single strided iteration, this would return a view that is a one-dimensional array.

void NpyIter_GetReadFlags( NpyIter* iter, char* outreadflags)

Fills nop flags. Sets outreadflags[i] to 1 if op[i] can be read from, and to 0 if not.

void NpyIter_GetWriteFlags( NpyIter* iter, char* outwriteflags)

Fills nop flags. Sets outwriteflags[i] to 1 if op[i] can be written to, and to 0 if not.

int NpyIter_CreateCompatibleStrides( NpyIter* iter, npy_intp itemsize, npy_intp* outstrides)

Builds a set of strides which are the same as the strides of an output array created using the NPY_ITER_ALLOCATE flag, where NULL was passed for op_axes. This is for data packed contiguously, but not necessarily in C or Fortran order. This should be used together with NpyIter_GetShape and NpyIter_GetNDim with the flag NPY_ITER_MULTI_INDEX passed into the constructor.

A use case for this function is to match the shape and layout of the iterator and tack on one or more dimensions. For example, in order to generate a vector per input value for a numerical gradient, you pass in ndim*itemsize for itemsize, then add another dimension to the end with size ndim and stride itemsize. To do the Hessian matrix, you do the same thing but add two dimensions, or take advantage of the symmetry and pack it into 1 dimension with a particular encoding.

This function may only be called if the iterator is tracking a multi-index and if NPY_ITER_DONT_NEGATE_STRIDES was used to prevent an axis from being iterated in reverse order.

If an array is created with this method, simply adding ‘itemsize’ for each iteration will traverse the new array matching the iterator.

Returns NPY_SUCCEED or NPY_FAIL.

npy_bool NpyIter_IsFirstVisit( NpyIter* iter, int iop)

New in version 1.7.

Checks to see whether this is the first time the elements of the specified reduction operand which the iterator points at are being seen for the first time. The function returns a reasonable answer for reduction operands and when buffering is disabled. The answer may be incorrect for buffered non-reduction operands.

This function is intended to be used in EXTERNAL_LOOP mode only, and will produce some wrong answers when that mode is not enabled.

If this function returns true, the caller should also check the inner loop stride of the operand, because if that stride is 0, then only the first element of the innermost external loop is being visited for the first time.

WARNING: For performance reasons, ‘iop’ is not bounds-checked, it is not confirmed that ‘iop’ is actually a reduction operand, and it is not confirmed that EXTERNAL_LOOP mode is enabled. These checks are the responsibility of the caller, and should be done outside of any inner loops.

Functions For Iteration

NpyIter_IterNextFunc* NpyIter_GetIterNext( NpyIter* iter, char** errmsg)

Returns a function pointer for iteration. A specialized version of the function pointer may be calculated by this function instead of being stored in the iterator structure. Thus, to get good performance, it is required that the function pointer be saved in a variable rather than retrieved for each loop iteration.

Returns NULL if there is an error. If errmsg is non-NULL, no Python exception is set when NPY_FAIL is returned. Instead, *errmsg is set to an error message. When errmsg is non-NULL, the function may be safely called without holding the Python GIL.

The typical looping construct is as follows.

NpyIter_IterNextFunc *iternext = NpyIter_GetIterNext(iter, NULL);
char** dataptr = NpyIter_GetDataPtrArray(iter);

do {
    /* use the addresses dataptr[0], ... dataptr[nop-1] */
} while(iternext(iter));

When NPY_ITER_EXTERNAL_LOOP is specified, the typical inner loop construct is as follows.

NpyIter_IterNextFunc *iternext = NpyIter_GetIterNext(iter, NULL);
char** dataptr = NpyIter_GetDataPtrArray(iter);
npy_intp* stride = NpyIter_GetInnerStrideArray(iter);
npy_intp* size_ptr = NpyIter_GetInnerLoopSizePtr(iter), size;
npy_intp iop, nop = NpyIter_GetNOp(iter);

do {
    size = *size_ptr;
    while (size--) {
        /* use the addresses dataptr[0], ... dataptr[nop-1] */
        for (iop = 0; iop < nop; ++iop) {
            dataptr[iop] += stride[iop];
        }
    }
} while (iternext());

Observe that we are using the dataptr array inside the iterator, not copying the values to a local temporary. This is possible because when iternext() is called, these pointers will be overwritten with fresh values, not incrementally updated.

If a compile-time fixed buffer is being used (both flags NPY_ITER_BUFFERED and NPY_ITER_EXTERNAL_LOOP), the inner size may be used as a signal as well. The size is guaranteed to become zero when iternext() returns false, enabling the following loop construct. Note that if you use this construct, you should not pass NPY_ITER_GROWINNER as a flag, because it will cause larger sizes under some circumstances.

/* The constructor should have buffersize passed as this value */
#define FIXED_BUFFER_SIZE 1024

NpyIter_IterNextFunc *iternext = NpyIter_GetIterNext(iter, NULL);
char **dataptr = NpyIter_GetDataPtrArray(iter);
npy_intp *stride = NpyIter_GetInnerStrideArray(iter);
npy_intp *size_ptr = NpyIter_GetInnerLoopSizePtr(iter), size;
npy_intp i, iop, nop = NpyIter_GetNOp(iter);

/* One loop with a fixed inner size */
size = *size_ptr;
while (size == FIXED_BUFFER_SIZE) {
    /*
     * This loop could be manually unrolled by a factor
     * which divides into FIXED_BUFFER_SIZE
     */
    for (i = 0; i < FIXED_BUFFER_SIZE; ++i) {
        /* use the addresses dataptr[0], ... dataptr[nop-1] */
        for (iop = 0; iop < nop; ++iop) {
            dataptr[iop] += stride[iop];
        }
    }
    iternext();
    size = *size_ptr;
}

/* Finish-up loop with variable inner size */
if (size > 0) do {
    size = *size_ptr;
    while (size--) {
        /* use the addresses dataptr[0], ... dataptr[nop-1] */
        for (iop = 0; iop < nop; ++iop) {
            dataptr[iop] += stride[iop];
        }
    }
} while (iternext());
NpyIter_GetMultiIndexFunc *NpyIter_GetGetMultiIndex( NpyIter* iter, char** errmsg)

Returns a function pointer for getting the current multi-index of the iterator. Returns NULL if the iterator is not tracking a multi-index. It is recommended that this function pointer be cached in a local variable before the iteration loop.

Returns NULL if there is an error. If errmsg is non-NULL, no Python exception is set when NPY_FAIL is returned. Instead, *errmsg is set to an error message. When errmsg is non-NULL, the function may be safely called without holding the Python GIL.

char** NpyIter_GetDataPtrArray( NpyIter* iter)

This gives back a pointer to the nop data pointers. If NPY_ITER_EXTERNAL_LOOP was not specified, each data pointer points to the current data item of the iterator. If no inner iteration was specified, it points to the first data item of the inner loop.

This pointer may be cached before the iteration loop, calling iternext will not change it. This function may be safely called without holding the Python GIL.

char** NpyIter_GetInitialDataPtrArray( NpyIter* iter)

Gets the array of data pointers directly into the arrays (never into the buffers), corresponding to iteration index 0.

These pointers are different from the pointers accepted by NpyIter_ResetBasePointers, because the direction along some axes may have been reversed.

This function may be safely called without holding the Python GIL.

npy_intp* NpyIter_GetIndexPtr( NpyIter* iter)

This gives back a pointer to the index being tracked, or NULL if no index is being tracked. It is only useable if one of the flags NPY_ITER_C_INDEX or NPY_ITER_F_INDEX were specified during construction.

When the flag NPY_ITER_EXTERNAL_LOOP is used, the code needs to know the parameters for doing the inner loop. These functions provide that information.

npy_intp* NpyIter_GetInnerStrideArray( NpyIter* iter)

Returns a pointer to an array of the nop strides, one for each iterated object, to be used by the inner loop.

This pointer may be cached before the iteration loop, calling iternext will not change it. This function may be safely called without holding the Python GIL.

npy_intp* NpyIter_GetInnerLoopSizePtr( NpyIter* iter)

Returns a pointer to the number of iterations the inner loop should execute.

This address may be cached before the iteration loop, calling iternext will not change it. The value itself may change during iteration, in particular if buffering is enabled. This function may be safely called without holding the Python GIL.

void NpyIter_GetInnerFixedStrideArray( NpyIter* iter, npy_intp* out_strides)

Gets an array of strides which are fixed, or will not change during the entire iteration. For strides that may change, the value NPY_MAX_INTP is placed in the stride.

Once the iterator is prepared for iteration (after a reset if NPY_DELAY_BUFALLOC was used), call this to get the strides which may be used to select a fast inner loop function. For example, if the stride is 0, that means the inner loop can always load its value into a variable once, then use the variable throughout the loop, or if the stride equals the itemsize, a contiguous version for that operand may be used.

This function may be safely called without holding the Python GIL.


UFunc API

  • Numpy C-API
  • next
  • previous

Table Of Contents

  • UFunc API
    • Constants
    • Macros
    • Functions
    • Generic functions
    • Importing the API

Previous topic

Array Iterator API

Next topic

Generalized Universal Function API

UFunc API

Constants

UFUNC_ERR_{HANDLER}

{HANDLER} can be IGNORE, WARN, RAISE, or CALL

UFUNC_{THING}_{ERR}

{THING} can be MASK, SHIFT, or FPE, and {ERR} can be DIVIDEBYZERO, OVERFLOW, UNDERFLOW, and INVALID.

PyUFunc_{VALUE}

{VALUE} can be One (1), Zero (0), or None (-1)

Macros

NPY_LOOP_BEGIN_THREADS

Used in universal function code to only release the Python GIL if loop->obj is not true (i.e. this is not an OBJECT array loop). Requires use of NPY_BEGIN_THREADS_DEF in variable declaration area.

NPY_LOOP_END_THREADS

Used in universal function code to re-acquire the Python GIL if it was released (because loop->obj was not true).

UFUNC_CHECK_ERROR(loop)

A macro used internally to check for errors and goto fail if found. This macro requires a fail label in the current code block. The loop variable must have at least members (obj, errormask, and errorobj). If loop ->obj is nonzero, then PyErr_Occurred () is called (meaning the GIL must be held). If loop ->obj is zero, then if loop ->errormask is nonzero, PyUFunc_checkfperr is called with arguments loop ->errormask and loop ->errobj. If the result of this check of the IEEE floating point registers is true then the code redirects to the fail label which must be defined.

UFUNC_CHECK_STATUS(ret)

Deprecated: use npy_clear_floatstatus from npy_math.h instead.

A macro that expands to platform-dependent code. The ret variable can can be any integer. The UFUNC_FPE_{ERR} bits are set in ret according to the status of the corresponding error flags of the floating point processor.

Functions

PyObject* PyUFunc_FromFuncAndData(PyUFuncGenericFunction* func,
void** data, char* types, int ntypes, int nin, int nout, int identity,
char* name, char* doc, int check_return)

Create a new broadcasting universal function from required variables. Each ufunc builds around the notion of an element-by-element operation. Each ufunc object contains pointers to 1-d loops implementing the basic functionality for each supported type.

Note

The func, data, types, name, and doc arguments are not copied by PyUFunc_FromFuncAndData. The caller must ensure that the memory used by these arrays is not freed as long as the ufunc object is alive.

Parameters:
  • func – Must to an array of length ntypes containing PyUFuncGenericFunction items. These items are pointers to functions that actually implement the underlying (element-by-element) function N times.
  • data – Should be NULL or a pointer to an array of size ntypes . This array may contain arbitrary extra-data to be passed to the corresponding 1-d loop function in the func array.
  • types – Must be of length (nin + nout) * ntypes, and it contains the data-types (built-in only) that the corresponding function in the func array can deal with.
  • ntypes – How many different data-type “signatures” the ufunc has implemented.
  • nin – The number of inputs to this operation.
  • nout – The number of outputs
  • name – The name for the ufunc. Specifying a name of ‘add’ or ‘multiply’ enables a special behavior for integer-typed reductions when no dtype is given. If the input type is an integer (or boolean) data type smaller than the size of the int_ data type, it will be internally upcast to the int_ (or uint) data type.
  • doc – Allows passing in a documentation string to be stored with the ufunc. The documentation string should not contain the name of the function or the calling signature as that will be dynamically determined from the object and available when accessing the __doc__ attribute of the ufunc.
  • check_return – Unused and present for backwards compatibility of the C-API. A corresponding check_return integer does exist in the ufunc structure and it does get set with this value when the ufunc object is created.
PyObject* PyUFunc_FromFuncAndDataAndSignature(PyUFuncGenericFunction* func,
void** data, char* types, int ntypes, int nin, int nout, int identity,
char* name, char* doc, int check_return, char *signature)

This function is very similar to PyUFunc_FromFuncAndData above, but has an extra signature argument, to define generalized universal functions. Similarly to how ufuncs are built around an element-by-element operation, gufuncs are around subarray-by-subarray operations, the signature defining the subarrays to operate on.

Parameters:
  • signature – The signature for the new gufunc. Setting it to NULL is equivalent to calling PyUFunc_FromFuncAndData. A copy of the string is made, so the passed in buffer can be freed.
int PyUFunc_RegisterLoopForType(PyUFuncObject* ufunc,
int usertype, PyUFuncGenericFunction function, int* arg_types, void* data)

This function allows the user to register a 1-d loop with an already- created ufunc to be used whenever the ufunc is called with any of its input arguments as the user-defined data-type. This is needed in order to make ufuncs work with built-in data-types. The data-type must have been previously registered with the numpy system. The loop is passed in as function. This loop can take arbitrary data which should be passed in as data. The data-types the loop requires are passed in as arg_types which must be a pointer to memory at least as large as ufunc->nargs.

int PyUFunc_RegisterLoopForDescr(PyUFuncObject* ufunc,
PyArray_Descr* userdtype, PyUFuncGenericFunction function,
PyArray_Descr** arg_dtypes, void* data)

This function behaves like PyUFunc_RegisterLoopForType above, except that it allows the user to register a 1-d loop using PyArray_Descr objects instead of dtype type num values. This allows a 1-d loop to be registered for structured array data-dtypes and custom data-types instead of scalar data-types.

int PyUFunc_ReplaceLoopBySignature(PyUFuncObject* ufunc,
PyUFuncGenericFunction newfunc, int* signature,
PyUFuncGenericFunction* oldfunc)

Replace a 1-d loop matching the given signature in the already-created ufunc with the new 1-d loop newfunc. Return the old 1-d loop function in oldfunc. Return 0 on success and -1 on failure. This function works only with built-in types (use PyUFunc_RegisterLoopForType for user-defined types). A signature is an array of data-type numbers indicating the inputs followed by the outputs assumed by the 1-d loop.

int PyUFunc_GenericFunction(PyUFuncObject* self,
PyObject* args, PyObject* kwds, PyArrayObject** mps)

A generic ufunc call. The ufunc is passed in as self, the arguments to the ufunc as args and kwds. The mps argument is an array of PyArrayObject pointers whose values are discarded and which receive the converted input arguments as well as the ufunc outputs when success is returned. The user is responsible for managing this array and receives a new reference for each array in mps. The total number of arrays in mps is given by self ->nin + self ->nout.

Returns 0 on success, -1 on error.

int PyUFunc_checkfperr(int errmask, PyObject* errobj)

A simple interface to the IEEE error-flag checking support. The errmask argument is a mask of UFUNC_MASK_{ERR} bitmasks indicating which errors to check for (and how to check for them). The errobj must be a Python tuple with two elements: a string containing the name which will be used in any communication of error and either a callable Python object (call-back function) or Py_None. The callable object will only be used if UFUNC_ERR_CALL is set as the desired error checking method. This routine manages the GIL and is safe to call even after releasing the GIL. If an error in the IEEE-compatibile hardware is determined a -1 is returned, otherwise a 0 is returned.

void PyUFunc_clearfperr()

Clear the IEEE error flags.

void PyUFunc_GetPyValues(char* name, int* bufsize,
int* errmask, PyObject** errobj)

Get the Python values used for ufunc processing from the thread-local storage area unless the defaults have been set in which case the name lookup is bypassed. The name is placed as a string in the first element of *errobj. The second element is the looked-up function to call on error callback. The value of the looked-up buffer-size to use is passed into bufsize, and the value of the error mask is placed into errmask.

Generic functions

At the core of every ufunc is a collection of type-specific functions that defines the basic functionality for each of the supported types. These functions must evaluate the underlying function [image] times. Extra-data may be passed in that may be used during the calculation. This feature allows some general functions to be used as these basic looping functions. The general function has all the code needed to point variables to the right place and set up a function call. The general function assumes that the actual function to call is passed in as the extra data and calls it with the correct values. All of these functions are suitable for placing directly in the array of functions stored in the functions member of the PyUFuncObject structure.

void PyUFunc_f_f_As_d_d(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_d_d(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_f_f(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_g_g(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_F_F_As_D_D(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_F_F(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_D_D(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_G_G(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_e_e(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_e_e_As_f_f(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_e_e_As_d_d(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)

Type specific, core 1-d functions for ufuncs where each calculation is obtained by calling a function taking one input argument and returning one output. This function is passed in func. The letters correspond to dtypechar’s of the supported data types ( e - half, f - float, d - double, g - long double, F - cfloat, D - cdouble, G - clongdouble). The argument func must support the same signature. The _As_X_X variants assume ndarray’s of one data type but cast the values to use an underlying function that takes a different data type. Thus, PyUFunc_f_f_As_d_d uses ndarrays of data type NPY_FLOAT but calls out to a C-function that takes double and returns double.

void PyUFunc_ff_f_As_dd_d(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_ff_f(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_dd_d(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_gg_g(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_FF_F_As_DD_D(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_DD_D(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_FF_F(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_GG_G(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_ee_e(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_ee_e_As_ff_f(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_ee_e_As_dd_d(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)

Type specific, core 1-d functions for ufuncs where each calculation is obtained by calling a function taking two input arguments and returning one output. The underlying function to call is passed in as func. The letters correspond to dtypechar’s of the specific data type supported by the general-purpose function. The argument func must support the corresponding signature. The _As_XX_X variants assume ndarrays of one data type but cast the values at each iteration of the loop to use the underlying function that takes a different data type.

void PyUFunc_O_O(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)
void PyUFunc_OO_O(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)

One-input, one-output, and two-input, one-output core 1-d functions for the NPY_OBJECT data type. These functions handle reference count issues and return early on error. The actual function to call is func and it must accept calls with the signature (PyObject*) (PyObject*) for PyUFunc_O_O or (PyObject*)(PyObject *, PyObject *) for PyUFunc_OO_O.

void PyUFunc_O_O_method(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)

This general purpose 1-d core function assumes that func is a string representing a method of the input object. For each iteration of the loop, the Python obejct is extracted from the array and its func method is called returning the result to the output array.

void PyUFunc_OO_O_method(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)

This general purpose 1-d core function assumes that func is a string representing a method of the input object that takes one argument. The first argument in args is the method whose function is called, the second argument in args is the argument passed to the function. The output of the function is stored in the third entry of args.

void PyUFunc_On_Om(char** args, npy_intp* dimensions,
npy_intp* steps, void* func)

This is the 1-d core function used by the dynamic ufuncs created by umath.frompyfunc(function, nin, nout). In this case func is a pointer to a PyUFunc_PyFuncData structure which has definition

PyUFunc_PyFuncData
typedef struct {
    int nin;
    int nout;
    PyObject *callable;
} PyUFunc_PyFuncData;

At each iteration of the loop, the nin input objects are exctracted from their object arrays and placed into an argument tuple, the Python callable is called with the input arguments, and the nout outputs are placed into their object arrays.

Importing the API

PY_UFUNC_UNIQUE_SYMBOL
NO_IMPORT_UFUNC
void import_ufunc(void)

These are the constants and functions for accessing the ufunc C-API from extension modules in precisely the same way as the array C-API can be accessed. The import_ufunc () function must always be called (in the initialization subroutine of the extension module). If your extension module is in one file then that is all that is required. The other two constants are useful if your extension module makes use of multiple files. In that case, define PY_UFUNC_UNIQUE_SYMBOL to something unique to your code and then in source files that do not contain the module initialization function but still need access to the UFUNC API, define PY_UFUNC_UNIQUE_SYMBOL to the same name used previously and also define NO_IMPORT_UFUNC.

The C-API is actually an array of function pointers. This array is created (and pointed to by a global variable) by import_ufunc. The global variable is either statically defined or allowed to be seen by other files depending on the state of Py_UFUNC_UNIQUE_SYMBOL and NO_IMPORT_UFUNC.


Generalized Universal Function API

  • Numpy C-API
  • next
  • previous

Table Of Contents

  • Generalized Universal Function API
    • Definitions
    • Details of Signature
    • C-API for implementing Elementary Functions

Previous topic

UFunc API

Next topic

Numpy core libraries

Generalized Universal Function API

There is a general need for looping over not only functions on scalars but also over functions on vectors (or arrays). This concept is realized in Numpy by generalizing the universal functions (ufuncs). In regular ufuncs, the elementary function is limited to element-by-element operations, whereas the generalized version (gufuncs) supports “sub-array” by “sub-array” operations. The Perl vector library PDL provides a similar functionality and its terms are re-used in the following.

Each generalized ufunc has information associated with it that states what the “core” dimensionality of the inputs is, as well as the corresponding dimensionality of the outputs (the element-wise ufuncs have zero core dimensions). The list of the core dimensions for all arguments is called the “signature” of a ufunc. For example, the ufunc numpy.add has signature (),()->() defining two scalar inputs and one scalar output.

Another example is the function inner1d(a, b) with a signature of (i),(i)->(). This applies the inner product along the last axis of each input, but keeps the remaining indices intact. For example, where a is of shape (3, 5, N) and b is of shape (5, N), this will return an output of shape (3,5). The underlying elementary function is called 3 * 5 times. In the signature, we specify one core dimension (i) for each input and zero core dimensions () for the output, since it takes two 1-d arrays and returns a scalar. By using the same name i, we specify that the two corresponding dimensions should be of the same size.

The dimensions beyond the core dimensions are called “loop” dimensions. In the above example, this corresponds to (3, 5).

The signature determines how the dimensions of each input/output array are split into core and loop dimensions:

  1. Each dimension in the signature is matched to a dimension of the corresponding passed-in array, starting from the end of the shape tuple. These are the core dimensions, and they must be present in the arrays, or an error will be raised.
  2. Core dimensions assigned to the same label in the signature (e.g. the i in inner1d‘s (i),(i)->()) must have exactly matching sizes, no broadcasting is performed.
  3. The core dimensions are removed from all inputs and the remaining dimensions are broadcast together, defining the loop dimensions.
  4. The shape of each output is determined from the loop dimensions plus the output’s core dimensions

Typically, the size of all core dimensions in an output will be determined by the size of a core dimension with the same label in an input array. This is not a requirement, and it is possible to define a signature where a label comes up for the first time in an output, although some precautions must be taken when calling such a function. An example would be the function euclidean_pdist(a), with signature (n,d)->(p), that given an array of n d-dimensional vectors, computes all unique pairwise Euclidean distances among them. The output dimension p must therefore be equal to n * (n - 1) / 2, but it is the caller’s responsibility to pass in an output array of the right size. If the size of a core dimension of an output cannot be determined from a passed in input or output array, an error will be raised.

Note: Prior to Numpy 1.10.0, less strict checks were in place: missing core dimensions were created by prepending 1’s to the shape as necessary, core dimensions with the same label were broadcast together, and undetermined dimensions were created with size 1.

Definitions

Elementary Function
Each ufunc consists of an elementary function that performs the most basic operation on the smallest portion of array arguments (e.g. adding two numbers is the most basic operation in adding two arrays). The ufunc applies the elementary function multiple times on different parts of the arrays. The input/output of elementary functions can be vectors; e.g., the elementary function of inner1d takes two vectors as input.
Signature
A signature is a string describing the input/output dimensions of the elementary function of a ufunc. See section below for more details.
Core Dimension
The dimensionality of each input/output of an elementary function is defined by its core dimensions (zero core dimensions correspond to a scalar input/output). The core dimensions are mapped to the last dimensions of the input/output arrays.
Dimension Name
A dimension name represents a core dimension in the signature. Different dimensions may share a name, indicating that they are of the same size.
Dimension Index
A dimension index is an integer representing a dimension name. It enumerates the dimension names according to the order of the first occurrence of each name in the signature.

Details of Signature

The signature defines “core” dimensionality of input and output variables, and thereby also defines the contraction of the dimensions. The signature is represented by a string of the following format:

  • Core dimensions of each input or output array are represented by a list of dimension names in parentheses, (i_1,...,i_N); a scalar input/output is denoted by (). Instead of i_1, i_2, etc, one can use any valid Python variable name.
  • Dimension lists for different arguments are separated by ",". Input/output arguments are separated by "->".
  • If one uses the same dimension name in multiple locations, this enforces the same size of the corresponding dimensions.

The formal syntax of signatures is as follows:

<Signature>            ::= <Input arguments> "->" <Output arguments>
<Input arguments>      ::= <Argument list>
<Output arguments>     ::= <Argument list>
<Argument list>        ::= nil | <Argument> | <Argument> "," <Argument list>
<Argument>             ::= "(" <Core dimension list> ")"
<Core dimension list>  ::= nil | <Dimension name> |
                           <Dimension name> "," <Core dimension list>
<Dimension name>       ::= valid Python variable name

Notes:

  1. All quotes are for clarity.
  2. Core dimensions that share the same name must have the exact same size. Each dimension name typically corresponds to one level of looping in the elementary function’s implementation.
  3. White spaces are ignored.

Here are some examples of signatures:

add | (),()->() |
inner1d | (i),(i)->() |
sum1d | (i)->() |
dot2d | (m,n),(n,p)->(m,p) | matrix multiplication
outer_inner | (i,t),(j,t)->(i,j) | inner over the last dimension, outer over the second to last, and loop/broadcast over the rest.

C-API for implementing Elementary Functions

The current interface remains unchanged, and PyUFunc_FromFuncAndData can still be used to implement (specialized) ufuncs, consisting of scalar elementary functions.

One can use PyUFunc_FromFuncAndDataAndSignature to declare a more general ufunc. The argument list is the same as PyUFunc_FromFuncAndData, with an additional argument specifying the signature as C string.

Furthermore, the callback function is of the same type as before, void (*foo)(char **args, intp *dimensions, intp *steps, void *func). When invoked, args is a list of length nargs containing the data of all input/output arguments. For a scalar elementary function, steps is also of length nargs, denoting the strides used for the arguments. dimensions is a pointer to a single integer defining the size of the axis to be looped over.

For a non-trivial signature, dimensions will also contain the sizes of the core dimensions as well, starting at the second entry. Only one size is provided for each unique dimension name and the sizes are given according to the first occurrence of a dimension name in the signature.

The first nargs elements of steps remain the same as for scalar ufuncs. The following elements contain the strides of all core dimensions for all arguments in order.

For example, consider a ufunc with signature (i,j),(i)->(). In this case, args will contain three pointers to the data of the input/output arrays a, b, c. Furthermore, dimensions will be [N, I, J] to define the size of N of the loop and the sizes I and J for the core dimensions i and j. Finally, steps will be [a_N, b_N, c_N, a_i, a_j, b_i], containing all necessary strides.


Numpy core libraries

  • Numpy C-API
  • next
  • previous

Table Of Contents

  • Numpy core libraries
    • Numpy core math library
      • Floating point classification
      • Useful math constants
      • Low-level floating point manipulation
      • Complex functions
      • Linking against the core math library in an extension
      • Half-precision functions

Previous topic

Generalized Universal Function API

Next topic

C API Deprecations

Numpy core libraries

New in version 1.3.0.

Starting from numpy 1.3.0, we are working on separating the pure C, “computational” code from the python dependent code. The goal is twofolds: making the code cleaner, and enabling code reuse by other extensions outside numpy (scipy, etc...).

Numpy core math library

The numpy core math library (‘npymath’) is a first step in this direction. This library contains most math-related C99 functionality, which can be used on platforms where C99 is not well supported. The core math functions have the same API as the C99 ones, except for the npy_* prefix.

The available functions are defined in <numpy/npy_math.h> - please refer to this header when in doubt.

Floating point classification

NPY_NAN

This macro is defined to a NaN (Not a Number), and is guaranteed to have the signbit unset (‘positive’ NaN). The corresponding single and extension precision macro are available with the suffix F and L.

NPY_INFINITY

This macro is defined to a positive inf. The corresponding single and extension precision macro are available with the suffix F and L.

NPY_PZERO

This macro is defined to positive zero. The corresponding single and extension precision macro are available with the suffix F and L.

NPY_NZERO

This macro is defined to negative zero (that is with the sign bit set). The corresponding single and extension precision macro are available with the suffix F and L.

int npy_isnan(x)

This is a macro, and is equivalent to C99 isnan: works for single, double and extended precision, and return a non 0 value is x is a NaN.

int npy_isfinite(x)

This is a macro, and is equivalent to C99 isfinite: works for single, double and extended precision, and return a non 0 value is x is neither a NaN nor an infinity.

int npy_isinf(x)

This is a macro, and is equivalent to C99 isinf: works for single, double and extended precision, and return a non 0 value is x is infinite (positive and negative).

int npy_signbit(x)

This is a macro, and is equivalent to C99 signbit: works for single, double and extended precision, and return a non 0 value is x has the signbit set (that is the number is negative).

double npy_copysign(double x, double y)

This is a function equivalent to C99 copysign: return x with the same sign as y. Works for any value, including inf and nan. Single and extended precisions are available with suffix f and l.

New in version 1.4.0.

Useful math constants

The following math constants are available in npy_math.h. Single and extended precision are also available by adding the F and L suffixes respectively.

NPY_E

Base of natural logarithm ( e)

NPY_LOG2E

Logarithm to base 2 of the Euler constant ( [image])

NPY_LOG10E

Logarithm to base 10 of the Euler constant ( [image])

NPY_LOGE2

Natural logarithm of 2 ( [image])

NPY_LOGE10

Natural logarithm of 10 ( [image])

NPY_PI

Pi ( [image])

NPY_PI_2

Pi divided by 2 ( [image])

NPY_PI_4

Pi divided by 4 ( [image])

NPY_1_PI

Reciprocal of pi ( [image])

NPY_2_PI

Two times the reciprocal of pi ( [image])

NPY_EULER
The Euler constant

Low-level floating point manipulation

Those can be useful for precise floating point comparison.

double npy_nextafter(double x, double y)

This is a function equivalent to C99 nextafter: return next representable floating point value from x in the direction of y. Single and extended precisions are available with suffix f and l.

New in version 1.4.0.

double npy_spacing(double x)

This is a function equivalent to Fortran intrinsic. Return distance between x and next representable floating point value from x, e.g. spacing(1) == eps. spacing of nan and +/- inf return nan. Single and extended precisions are available with suffix f and l.

New in version 1.4.0.

void npy_set_floatstatus_divbyzero()

Set the divide by zero floating point exception

New in version 1.6.0.

void npy_set_floatstatus_overflow()

Set the overflow floating point exception

New in version 1.6.0.

void npy_set_floatstatus_underflow()

Set the underflow floating point exception

New in version 1.6.0.

void npy_set_floatstatus_invalid()

Set the invalid floating point exception

New in version 1.6.0.

int npy_get_floatstatus()

Get floating point status. Returns a bitmask with following possible flags:

  • NPY_FPE_DIVIDEBYZERO
  • NPY_FPE_OVERFLOW
  • NPY_FPE_UNDERFLOW
  • NPY_FPE_INVALID

New in version 1.9.0.

int npy_clear_floatstatus()

Clears the floating point status. Returns the previous status mask.

New in version 1.9.0.

Complex functions

New in version 1.4.0.

C99-like complex functions have been added. Those can be used if you wish to implement portable C extensions. Since we still support platforms without C99 complex type, you need to restrict to C90-compatible syntax, e.g.:

/* a = 1 + 2i \*/
npy_complex a = npy_cpack(1, 2);
npy_complex b;

b = npy_log(a);

Linking against the core math library in an extension

New in version 1.4.0.

To use the core math library in your own extension, you need to add the npymath compile and link options to your extension in your setup.py:

>>> from numpy.distutils.misc_util import get_info
>>> info = get_info('npymath')
>>> config.add_extension('foo', sources=['foo.c'], extra_info=info)

In other words, the usage of info is exactly the same as when using blas_info and co.

Half-precision functions

New in version 2.0.0.

The header file <numpy/halffloat.h> provides functions to work with IEEE 754-2008 16-bit floating point values. While this format is not typically used for numerical computations, it is useful for storing values which require floating point but do not need much precision. It can also be used as an educational tool to understand the nature of floating point round-off error.

Like for other types, NumPy includes a typedef npy_half for the 16 bit float. Unlike for most of the other types, you cannot use this as a normal type in C, since is is a typedef for npy_uint16. For example, 1.0 looks like 0x3c00 to C, and if you do an equality comparison between the different signed zeros, you will get -0.0 != 0.0 (0x8000 != 0x0000), which is incorrect.

For these reasons, NumPy provides an API to work with npy_half values accessible by including <numpy/halffloat.h> and linking to ‘npymath’. For functions that are not provided directly, such as the arithmetic operations, the preferred method is to convert to float or double and back again, as in the following example.

npy_half sum(int n, npy_half *array) {
    float ret = 0;
    while(n--) {
        ret += npy_half_to_float(*array++);
    }
    return npy_float_to_half(ret);
}

External Links:

  • 754-2008 IEEE Standard for Floating-Point Arithmetic
  • Half-precision Float Wikipedia Article.
  • OpenGL Half Float Pixel Support
  • The OpenEXR image format.
NPY_HALF_ZERO

This macro is defined to positive zero.

NPY_HALF_PZERO

This macro is defined to positive zero.

NPY_HALF_NZERO

This macro is defined to negative zero.

NPY_HALF_ONE

This macro is defined to 1.0.

NPY_HALF_NEGONE

This macro is defined to -1.0.

NPY_HALF_PINF

This macro is defined to +inf.

NPY_HALF_NINF

This macro is defined to -inf.

NPY_HALF_NAN

This macro is defined to a NaN value, guaranteed to have its sign bit unset.

float npy_half_to_float(npy_half h)

Converts a half-precision float to a single-precision float.

double npy_half_to_double(npy_half h)

Converts a half-precision float to a double-precision float.

npy_half npy_float_to_half(float f)

Converts a single-precision float to a half-precision float. The value is rounded to the nearest representable half, with ties going to the nearest even. If the value is too small or too big, the system’s floating point underflow or overflow bit will be set.

npy_half npy_double_to_half(double d)

Converts a double-precision float to a half-precision float. The value is rounded to the nearest representable half, with ties going to the nearest even. If the value is too small or too big, the system’s floating point underflow or overflow bit will be set.

int npy_half_eq(npy_half h1, npy_half h2)

Compares two half-precision floats (h1 == h2).

int npy_half_ne(npy_half h1, npy_half h2)

Compares two half-precision floats (h1 != h2).

int npy_half_le(npy_half h1, npy_half h2)

Compares two half-precision floats (h1 <= h2).

int npy_half_lt(npy_half h1, npy_half h2)

Compares two half-precision floats (h1 < h2).

int npy_half_ge(npy_half h1, npy_half h2)

Compares two half-precision floats (h1 >= h2).

int npy_half_gt(npy_half h1, npy_half h2)

Compares two half-precision floats (h1 > h2).

int npy_half_eq_nonan(npy_half h1, npy_half h2)

Compares two half-precision floats that are known to not be NaN (h1 == h2). If a value is NaN, the result is undefined.

int npy_half_lt_nonan(npy_half h1, npy_half h2)

Compares two half-precision floats that are known to not be NaN (h1 < h2). If a value is NaN, the result is undefined.

int npy_half_le_nonan(npy_half h1, npy_half h2)

Compares two half-precision floats that are known to not be NaN (h1 <= h2). If a value is NaN, the result is undefined.

int npy_half_iszero(npy_half h)

Tests whether the half-precision float has a value equal to zero. This may be slightly faster than calling npy_half_eq(h, NPY_ZERO).

int npy_half_isnan(npy_half h)

Tests whether the half-precision float is a NaN.

int npy_half_isinf(npy_half h)

Tests whether the half-precision float is plus or minus Inf.

int npy_half_isfinite(npy_half h)

Tests whether the half-precision float is finite (not NaN or Inf).

int npy_half_signbit(npy_half h)

Returns 1 is h is negative, 0 otherwise.

npy_half npy_half_copysign(npy_half x, npy_half y)

Returns the value of x with the sign bit copied from y. Works for any value, including Inf and NaN.

npy_half npy_half_spacing(npy_half h)

This is the same for half-precision float as npy_spacing and npy_spacingf described in the low-level floating point section.

npy_half npy_half_nextafter(npy_half x, npy_half y)

This is the same for half-precision float as npy_nextafter and npy_nextafterf described in the low-level floating point section.

npy_uint16 npy_floatbits_to_halfbits(npy_uint32 f)

Low-level function which converts a 32-bit single-precision float, stored as a uint32, into a 16-bit half-precision float.

npy_uint16 npy_doublebits_to_halfbits(npy_uint64 d)

Low-level function which converts a 64-bit double-precision float, stored as a uint64, into a 16-bit half-precision float.

npy_uint32 npy_halfbits_to_floatbits(npy_uint16 h)

Low-level function which converts a 16-bit half-precision float into a 32-bit single-precision float, stored as a uint32.

npy_uint64 npy_halfbits_to_doublebits(npy_uint16 h)

Low-level function which converts a 16-bit half-precision float into a 64-bit double-precision float, stored as a uint64.


C API Deprecations

  • Numpy C-API
  • next
  • previous

Table Of Contents

  • C API Deprecations
    • Background
    • Deprecation Mechanism NPY_NO_DEPRECATED_API

Previous topic

Numpy core libraries

Next topic

Numpy internals

C API Deprecations

Background

The API exposed by NumPy for third-party extensions has grown over years of releases, and has allowed programmers to directly access NumPy functionality from C. This API can be best described as “organic”. It has emerged from multiple competing desires and from multiple points of view over the years, strongly influenced by the desire to make it easy for users to move to NumPy from Numeric and Numarray. The core API originated with Numeric in 1995 and there are patterns such as the heavy use of macros written to mimic Python’s C-API as well as account for compiler technology of the late 90’s. There is also only a small group of volunteers who have had very little time to spend on improving this API.

There is an ongoing effort to improve the API. It is important in this effort to ensure that code that compiles for NumPy 1.X continues to compile for NumPy 1.X. At the same time, certain API’s will be marked as deprecated so that future-looking code can avoid these API’s and follow better practices.

Another important role played by deprecation markings in the C API is to move towards hiding internal details of the NumPy implementation. For those needing direct, easy, access to the data of ndarrays, this will not remove this ability. Rather, there are many potential performance optimizations which require changing the implementation details, and NumPy developers have been unable to try them because of the high value of preserving ABI compatibility. By deprecating this direct access, we will in the future be able to improve NumPy’s performance in ways we cannot presently.

Deprecation Mechanism NPY_NO_DEPRECATED_API

In C, there is no equivalent to the deprecation warnings that Python supports. One way to do deprecations is to flag them in the documentation and release notes, then remove or change the deprecated features in a future major version (NumPy 2.0 and beyond). Minor versions of NumPy should not have major C-API changes, however, that prevent code that worked on a previous minor release. For example, we will do our best to ensure that code that compiled and worked on NumPy 1.4 should continue to work on NumPy 1.7 (but perhaps with compiler warnings).

To use the NPY_NO_DEPRECATED_API mechanism, you need to #define it to the target API version of NumPy before #including any NumPy headers. If you want to confirm that your code is clean against 1.7, use:

#define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION

On compilers which support a #warning mechanism, NumPy issues a compiler warning if you do not define the symbol NPY_NO_DEPRECATED_API. This way, the fact that there are deprecations will be flagged for third-party developers who may not have read the release notes closely.


Numpy internals

  • next
  • previous

Table Of Contents

  • Numpy internals
    • Internal organization of numpy arrays
    • Multidimensional Array Indexing Order Issues

Previous topic

C API Deprecations

Next topic

Numpy C Code Explanations

Numpy internals

  • Numpy C Code Explanations
    • Memory model
    • Data-type encapsulation
    • N-D Iterators
    • Broadcasting
    • Array Scalars
    • Advanced (“Fancy”) Indexing
      • Fancy-indexing check
      • Fancy-indexing implementation
        • Creating the mapping object
        • Binding the mapping object
        • Getting (or Setting)
    • Universal Functions
      • Setup
      • Function call
        • One Loop
        • Strided Loop
        • Buffered Loop
      • Final output manipulation
      • Methods
        • Setup
        • Reduce
        • Accumulate
        • Reduceat

Internal organization of numpy arrays

It helps to understand a bit about how numpy arrays are handled under the covers to help understand numpy better. This section will not go into great detail. Those wishing to understand the full details are referred to Travis Oliphant’s book “Guide to Numpy”.

Numpy arrays consist of two major components, the raw array data (from now on, referred to as the data buffer), and the information about the raw array data. The data buffer is typically what people think of as arrays in C or Fortran, a contiguous (and fixed) block of memory containing fixed sized data items. Numpy also contains a significant set of data that describes how to interpret the data in the data buffer. This extra information contains (among other things):

  1. The basic data element’s size in bytes
  2. The start of the data within the data buffer (an offset relative to the beginning of the data buffer).
  3. The number of dimensions and the size of each dimension
  4. The separation between elements for each dimension (the ‘stride’). This does not have to be a multiple of the element size
  5. The byte order of the data (which may not be the native byte order)
  6. Whether the buffer is read-only
  7. Information (via the dtype object) about the interpretation of the basic data element. The basic data element may be as simple as a int or a float, or it may be a compound object (e.g., struct-like), a fixed character field, or Python object pointers.
  8. Whether the array is to interpreted as C-order or Fortran-order.

This arrangement allow for very flexible use of arrays. One thing that it allows is simple changes of the metadata to change the interpretation of the array buffer. Changing the byteorder of the array is a simple change involving no rearrangement of the data. The shape of the array can be changed very easily without changing anything in the data buffer or any data copying at all

Among other things that are made possible is one can create a new array metadata object that uses the same data buffer to create a new view of that data buffer that has a different interpretation of the buffer (e.g., different shape, offset, byte order, strides, etc) but shares the same data bytes. Many operations in numpy do just this such as slices. Other operations, such as transpose, don’t move data elements around in the array, but rather change the information about the shape and strides so that the indexing of the array changes, but the data in the doesn’t move.

Typically these new versions of the array metadata but the same data buffer are new ‘views’ into the data buffer. There is a different ndarray object, but it uses the same data buffer. This is why it is necessary to force copies through use of the .copy() method if one really wants to make a new and independent copy of the data buffer.

New views into arrays mean the the object reference counts for the data buffer increase. Simply doing away with the original array object will not remove the data buffer if other views of it still exist.

Multidimensional Array Indexing Order Issues

What is the right way to index multi-dimensional arrays? Before you jump to conclusions about the one and true way to index multi-dimensional arrays, it pays to understand why this is a confusing issue. This section will try to explain in detail how numpy indexing works and why we adopt the convention we do for images, and when it may be appropriate to adopt other conventions.

The first thing to understand is that there are two conflicting conventions for indexing 2-dimensional arrays. Matrix notation uses the first index to indicate which row is being selected and the second index to indicate which column is selected. This is opposite the geometrically oriented-convention for images where people generally think the first index represents x position (i.e., column) and the second represents y position (i.e., row). This alone is the source of much confusion; matrix-oriented users and image-oriented users expect two different things with regard to indexing.

The second issue to understand is how indices correspond to the order the array is stored in memory. In Fortran the first index is the most rapidly varying index when moving through the elements of a two dimensional array as it is stored in memory. If you adopt the matrix convention for indexing, then this means the matrix is stored one column at a time (since the first index moves to the next row as it changes). Thus Fortran is considered a Column-major language. C has just the opposite convention. In C, the last index changes most rapidly as one moves through the array as stored in memory. Thus C is a Row-major language. The matrix is stored by rows. Note that in both cases it presumes that the matrix convention for indexing is being used, i.e., for both Fortran and C, the first index is the row. Note this convention implies that the indexing convention is invariant and that the data order changes to keep that so.

But that’s not the only way to look at it. Suppose one has large two-dimensional arrays (images or matrices) stored in data files. Suppose the data are stored by rows rather than by columns. If we are to preserve our index convention (whether matrix or image) that means that depending on the language we use, we may be forced to reorder the data if it is read into memory to preserve our indexing convention. For example if we read row-ordered data into memory without reordering, it will match the matrix indexing convention for C, but not for Fortran. Conversely, it will match the image indexing convention for Fortran, but not for C. For C, if one is using data stored in row order, and one wants to preserve the image index convention, the data must be reordered when reading into memory.

In the end, which you do for Fortran or C depends on which is more important, not reordering data or preserving the indexing convention. For large images, reordering data is potentially expensive, and often the indexing convention is inverted to avoid that.

The situation with numpy makes this issue yet more complicated. The internal machinery of numpy arrays is flexible enough to accept any ordering of indices. One can simply reorder indices by manipulating the internal stride information for arrays without reordering the data at all. Numpy will know how to map the new index order to the data without moving the data.

So if this is true, why not choose the index order that matches what you most expect? In particular, why not define row-ordered images to use the image convention? (This is sometimes referred to as the Fortran convention vs the C convention, thus the ‘C’ and ‘FORTRAN’ order options for array ordering in numpy.) The drawback of doing this is potential performance penalties. It’s common to access the data sequentially, either implicitly in array operations or explicitly by looping over rows of an image. When that is done, then the data will be accessed in non-optimal order. As the first index is incremented, what is actually happening is that elements spaced far apart in memory are being sequentially accessed, with usually poor memory access speeds. For example, for a two dimensional image ‘im’ defined so that im[0, 10] represents the value at x=0, y=10. To be consistent with usual Python behavior then im[0] would represent a column at x=0. Yet that data would be spread over the whole array since the data are stored in row order. Despite the flexibility of numpy’s indexing, it can’t really paper over the fact basic operations are rendered inefficient because of data order or that getting contiguous subarrays is still awkward (e.g., im[:,0] for the first row, vs im[0]), thus one can’t use an idiom such as for row in im; for col in im does work, but doesn’t yield contiguous column data.

As it turns out, numpy is smart enough when dealing with ufuncs to determine which index is the most rapidly varying one in memory and uses that for the innermost loop. Thus for ufuncs there is no large intrinsic advantage to either approach in most cases. On the other hand, use of .flat with an FORTRAN ordered array will lead to non-optimal memory access as adjacent elements in the flattened array (iterator, actually) are not contiguous in memory.

Indeed, the fact is that Python indexing on lists and other sequences naturally leads to an outside-to inside ordering (the first index gets the largest grouping, the next the next largest, and the last gets the smallest element). Since image data are normally stored by rows, this corresponds to position within rows being the last item indexed.

If you do want to use Fortran ordering realize that there are two approaches to consider: 1) accept that the first index is just not the most rapidly changing in memory and have all your I/O routines reorder your data when going from memory to disk or visa versa, or use numpy’s mechanism for mapping the first index to the most rapidly varying data. We recommend the former if possible. The disadvantage of the latter is that many of numpy’s functions will yield arrays without Fortran ordering unless you are careful to use the ‘order’ keyword. Doing this would be highly inconvenient.

Otherwise we recommend simply learning to reverse the usual order of indices when accessing elements of an array. Granted, it goes against the grain, but it is more in line with Python semantics and the natural order of the data.


Numpy C Code Explanations

  • Numpy internals
  • next
  • previous

Table Of Contents

  • Numpy C Code Explanations
    • Memory model
    • Data-type encapsulation
    • N-D Iterators
    • Broadcasting
    • Array Scalars
    • Advanced (“Fancy”) Indexing
      • Fancy-indexing check
      • Fancy-indexing implementation
        • Creating the mapping object
        • Binding the mapping object
        • Getting (or Setting)
    • Universal Functions
      • Setup
      • Function call
        • One Loop
        • Strided Loop
        • Buffered Loop
      • Final output manipulation
      • Methods
        • Setup
        • Reduce
        • Accumulate
        • Reduceat

Previous topic

Numpy internals

Next topic

Numpy and SWIG

Numpy C Code Explanations

Fanaticism consists of redoubling your efforts when you have forgotten your aim. — George Santayana

An authority is a person who can tell you more about something than you really care to know. — Unknown

This Chapter attempts to explain the logic behind some of the new pieces of code. The purpose behind these explanations is to enable somebody to be able to understand the ideas behind the implementation somewhat more easily than just staring at the code. Perhaps in this way, the algorithms can be improved on, borrowed from, and/or optimized.

Memory model

One fundamental aspect of the ndarray is that an array is seen as a “chunk” of memory starting at some location. The interpretation of this memory depends on the stride information. For each dimension in an N -dimensional array, an integer (stride) dictates how many bytes must be skipped to get to the next element in that dimension. Unless you have a single-segment array, this stride information must be consulted when traversing through an array. It is not difficult to write code that accepts strides, you just have to use (char *) pointers because strides are in units of bytes. Keep in mind also that strides do not have to be unit-multiples of the element size. Also, remember that if the number of dimensions of the array is 0 (sometimes called a rank-0 array), then the strides and dimensions variables are NULL.

Besides the structural information contained in the strides and dimensions members of the PyArrayObject, the flags contain important information about how the data may be accessed. In particular, the NPY_ARRAY_ALIGNED flag is set when the memory is on a suitable boundary according to the data-type array. Even if you have a contiguous chunk of memory, you cannot just assume it is safe to dereference a data- type-specific pointer to an element. Only if the NPY_ARRAY_ALIGNED flag is set is this a safe operation (on some platforms it will work but on others, like Solaris, it will cause a bus error). The NPY_ARRAY_WRITEABLE should also be ensured if you plan on writing to the memory area of the array. It is also possible to obtain a pointer to an unwriteable memory area. Sometimes, writing to the memory area when the NPY_ARRAY_WRITEABLE flag is not set will just be rude. Other times it can cause program crashes ( e.g. a data-area that is a read-only memory-mapped file).

Data-type encapsulation

The data-type is an important abstraction of the ndarray. Operations will look to the data-type to provide the key functionality that is needed to operate on the array. This functionality is provided in the list of function pointers pointed to by the ‘f’ member of the PyArray_Descr structure. In this way, the number of data-types can be extended simply by providing a PyArray_Descr structure with suitable function pointers in the ‘f’ member. For built-in types there are some optimizations that by-pass this mechanism, but the point of the data- type abstraction is to allow new data-types to be added.

One of the built-in data-types, the void data-type allows for arbitrary records containing 1 or more fields as elements of the array. A field is simply another data-type object along with an offset into the current record. In order to support arbitrarily nested fields, several recursive implementations of data-type access are implemented for the void type. A common idiom is to cycle through the elements of the dictionary and perform a specific operation based on the data-type object stored at the given offset. These offsets can be arbitrary numbers. Therefore, the possibility of encountering mis- aligned data must be recognized and taken into account if necessary.

N-D Iterators

A very common operation in much of NumPy code is the need to iterate over all the elements of a general, strided, N-dimensional array. This operation of a general-purpose N-dimensional loop is abstracted in the notion of an iterator object. To write an N-dimensional loop, you only have to create an iterator object from an ndarray, work with the dataptr member of the iterator object structure and call the macro PyArray_ITER_NEXT (it) on the iterator object to move to the next element. The “next” element is always in C-contiguous order. The macro works by first special casing the C-contiguous, 1-D, and 2-D cases which work very simply.

For the general case, the iteration works by keeping track of a list of coordinate counters in the iterator object. At each iteration, the last coordinate counter is increased (starting from 0). If this counter is smaller then one less than the size of the array in that dimension (a pre-computed and stored value), then the counter is increased and the dataptr member is increased by the strides in that dimension and the macro ends. If the end of a dimension is reached, the counter for the last dimension is reset to zero and the dataptr is moved back to the beginning of that dimension by subtracting the strides value times one less than the number of elements in that dimension (this is also pre-computed and stored in the backstrides member of the iterator object). In this case, the macro does not end, but a local dimension counter is decremented so that the next-to-last dimension replaces the role that the last dimension played and the previously-described tests are executed again on the next-to-last dimension. In this way, the dataptr is adjusted appropriately for arbitrary striding.

The coordinates member of the PyArrayIterObject structure maintains the current N-d counter unless the underlying array is C-contiguous in which case the coordinate counting is by-passed. The index member of the PyArrayIterObject keeps track of the current flat index of the iterator. It is updated by the PyArray_ITER_NEXT macro.

Broadcasting

In Numeric, broadcasting was implemented in several lines of code buried deep in ufuncobject.c. In NumPy, the notion of broadcasting has been abstracted so that it can be performed in multiple places. Broadcasting is handled by the function PyArray_Broadcast. This function requires a PyArrayMultiIterObject (or something that is a binary equivalent) to be passed in. The PyArrayMultiIterObject keeps track of the broadcasted number of dimensions and size in each dimension along with the total size of the broadcasted result. It also keeps track of the number of arrays being broadcast and a pointer to an iterator for each of the arrays being broadcasted.

The PyArray_Broadcast function takes the iterators that have already been defined and uses them to determine the broadcast shape in each dimension (to create the iterators at the same time that broadcasting occurs then use the PyMultiIter_New function). Then, the iterators are adjusted so that each iterator thinks it is iterating over an array with the broadcasted size. This is done by adjusting the iterators number of dimensions, and the shape in each dimension. This works because the iterator strides are also adjusted. Broadcasting only adjusts (or adds) length-1 dimensions. For these dimensions, the strides variable is simply set to 0 so that the data-pointer for the iterator over that array doesn’t move as the broadcasting operation operates over the extended dimension.

Broadcasting was always implemented in Numeric using 0-valued strides for the extended dimensions. It is done in exactly the same way in NumPy. The big difference is that now the array of strides is kept track of in a PyArrayIterObject, the iterators involved in a broadcasted result are kept track of in a PyArrayMultiIterObject, and the PyArray_BroadCast call implements the broad-casting rules.

Array Scalars

The array scalars offer a hierarchy of Python types that allow a one- to-one correspondence between the data-type stored in an array and the Python-type that is returned when an element is extracted from the array. An exception to this rule was made with object arrays. Object arrays are heterogeneous collections of arbitrary Python objects. When you select an item from an object array, you get back the original Python object (and not an object array scalar which does exist but is rarely used for practical purposes).

The array scalars also offer the same methods and attributes as arrays with the intent that the same code can be used to support arbitrary dimensions (including 0-dimensions). The array scalars are read-only (immutable) with the exception of the void scalar which can also be written to so that record-array field setting works more naturally (a[0][‘f1’] = value ).

Advanced (“Fancy”) Indexing

The implementation of advanced indexing represents some of the most difficult code to write and explain. In fact, there are two implementations of advanced indexing. The first works only with 1-D arrays and is implemented to handle expressions involving a.flat[obj]. The second is general-purpose that works for arrays of “arbitrary dimension” (up to a fixed maximum). The one-dimensional indexing approaches were implemented in a rather straightforward fashion, and so it is the general-purpose indexing code that will be the focus of this section.

There is a multi-layer approach to indexing because the indexing code can at times return an array scalar and at other times return an array. The functions with “_nice” appended to their name do this special handling while the function without the _nice appendage always return an array (perhaps a 0-dimensional array). Some special-case optimizations (the index being an integer scalar, and the index being a tuple with as many dimensions as the array) are handled in array_subscript_nice function which is what Python calls when presented with the code “a[obj].” These optimizations allow fast single-integer indexing, and also ensure that a 0-dimensional array is not created only to be discarded as the array scalar is returned instead. This provides significant speed-up for code that is selecting many scalars out of an array (such as in a loop). However, it is still not faster than simply using a list to store standard Python scalars, because that is optimized by the Python interpreter itself.

After these optimizations, the array_subscript function itself is called. This function first checks for field selection which occurs when a string is passed as the indexing object. Then, 0-D arrays are given special-case consideration. Finally, the code determines whether or not advanced, or fancy, indexing needs to be performed. If fancy indexing is not needed, then standard view-based indexing is performed using code borrowed from Numeric which parses the indexing object and returns the offset into the data-buffer and the dimensions necessary to create a new view of the array. The strides are also changed by multiplying each stride by the step-size requested along the corresponding dimension.

Fancy-indexing check

The fancy_indexing_check routine determines whether or not to use standard view-based indexing or new copy-based indexing. If the indexing object is a tuple, then view-based indexing is assumed by default. Only if the tuple contains an array object or a sequence object is fancy-indexing assumed. If the indexing object is an array, then fancy indexing is automatically assumed. If the indexing object is any other kind of sequence, then fancy-indexing is assumed by default. This is over-ridden to simple indexing if the sequence contains any slice, newaxis, or Ellipsis objects, and no arrays or additional sequences are also contained in the sequence. The purpose of this is to allow the construction of “slicing” sequences which is a common technique for building up code that works in arbitrary numbers of dimensions.

Fancy-indexing implementation

The concept of indexing was also abstracted using the idea of an iterator. If fancy indexing is performed, then a PyArrayMapIterObject is created. This internal object is not exposed to Python. It is created in order to handle the fancy-indexing at a high-level. Both get and set fancy-indexing operations are implemented using this object. Fancy indexing is abstracted into three separate operations: (1) creating the PyArrayMapIterObject from the indexing object, (2) binding the PyArrayMapIterObject to the array being indexed, and (3) getting (or setting) the items determined by the indexing object. There is an optimization implemented so that the PyArrayIterObject (which has it’s own less complicated fancy-indexing) is used for indexing when possible.

Creating the mapping object

The first step is to convert the indexing objects into a standard form where iterators are created for all of the index array inputs and all Boolean arrays are converted to equivalent integer index arrays (as if nonzero(arr) had been called). Finally, all integer arrays are replaced with the integer 0 in the indexing object and all of the index-array iterators are “broadcast” to the same shape.

Binding the mapping object

When the mapping object is created it does not know which array it will be used with so once the index iterators are constructed during mapping-object creation, the next step is to associate these iterators with a particular ndarray. This process interprets any ellipsis and slice objects so that the index arrays are associated with the appropriate axis (the axis indicated by the iteraxis entry corresponding to the iterator for the integer index array). This information is then used to check the indices to be sure they are within range of the shape of the array being indexed. The presence of ellipsis and/or slice objects implies a sub-space iteration that is accomplished by extracting a sub-space view of the array (using the index object resulting from replacing all the integer index arrays with 0) and storing the information about where this sub-space starts in the mapping object. This is used later during mapping-object iteration to select the correct elements from the underlying array.

Getting (or Setting)

After the mapping object is successfully bound to a particular array, the mapping object contains the shape of the resulting item as well as iterator objects that will walk through the currently-bound array and either get or set its elements as needed. The walk is implemented using the PyArray_MapIterNext function. This function sets the coordinates of an iterator object into the current array to be the next coordinate location indicated by all of the indexing-object iterators while adjusting, if necessary, for the presence of a sub- space. The result of this function is that the dataptr member of the mapping object structure is pointed to the next position in the array that needs to be copied out or set to some value.

When advanced indexing is used to extract an array, an iterator for the new array is constructed and advanced in phase with the mapping object iterator. When advanced indexing is used to place values in an array, a special “broadcasted” iterator is constructed from the object being placed into the array so that it will only work if the values used for setting have a shape that is “broadcastable” to the shape implied by the indexing object.

Universal Functions

Universal functions are callable objects that take N inputs and produce M outputs by wrapping basic 1-D loops that work element-by-element into full easy-to use functions that seamlessly implement broadcasting, type-checking and buffered coercion, and output-argument handling. New universal functions are normally created in C, although there is a mechanism for creating ufuncs from Python functions (frompyfunc). The user must supply a 1-D loop that implements the basic function taking the input scalar values and placing the resulting scalars into the appropriate output slots as explaine n implementation.

Setup

Every ufunc calculation involves some overhead related to setting up the calculation. The practical significance of this overhead is that even though the actual calculation of the ufunc is very fast, you will be able to write array and type-specific code that will work faster for small arrays than the ufunc. In particular, using ufuncs to perform many calculations on 0-D arrays will be slower than other Python-based solutions (the silently-imported scalarmath module exists precisely to give array scalars the look-and-feel of ufunc-based calculations with significantly reduced overhead).

When a ufunc is called, many things must be done. The information collected from these setup operations is stored in a loop-object. This loop object is a C-structure (that could become a Python object but is not initialized as such because it is only used internally). This loop object has the layout needed to be used with PyArray_Broadcast so that the broadcasting can be handled in the same way as it is handled in other sections of code.

The first thing done is to look-up in the thread-specific global dictionary the current values for the buffer-size, the error mask, and the associated error object. The state of the error mask controls what happens when an error-condiction is found. It should be noted that checking of the hardware error flags is only performed after each 1-D loop is executed. This means that if the input and output arrays are contiguous and of the correct type so that a single 1-D loop is performed, then the flags may not be checked until all elements of the array have been calcluated. Looking up these values in a thread- specific dictionary takes time which is easily ignored for all but very small arrays.

After checking, the thread-specific global variables, the inputs are evaluated to determine how the ufunc should proceed and the input and output arrays are constructed if necessary. Any inputs which are not arrays are converted to arrays (using context if necessary). Which of the inputs are scalars (and therefore converted to 0-D arrays) is noted.

Next, an appropriate 1-D loop is selected from the 1-D loops available to the ufunc based on the input array types. This 1-D loop is selected by trying to match the signature of the data-types of the inputs against the available signatures. The signatures corresponding to built-in types are stored in the types member of the ufunc structure. The signatures corresponding to user-defined types are stored in a linked-list of function-information with the head element stored as a CObject in the userloops dictionary keyed by the data-type number (the first user-defined type in the argument list is used as the key). The signatures are searched until a signature is found to which the input arrays can all be cast safely (ignoring any scalar arguments which are not allowed to determine the type of the result). The implication of this search procedure is that “lesser types” should be placed below “larger types” when the signatures are stored. If no 1-D loop is found, then an error is reported. Otherwise, the argument_list is updated with the stored signature — in case casting is necessary and to fix the output types assumed by the 1-D loop.

If the ufunc has 2 inputs and 1 output and the second input is an Object array then a special-case check is performed so that NotImplemented is returned if the second input is not an ndarray, has the __array_priority__ attribute, and has an __r{op}__ special method. In this way, Python is signaled to give the other object a chance to complete the operation instead of using generic object-array calculations. This allows (for example) sparse matrices to override the multiplication operator 1-D loop.

For input arrays that are smaller than the specified buffer size, copies are made of all non-contiguous, mis-aligned, or out-of- byteorder arrays to ensure that for small arrays, a single-loop is used. Then, array iterators are created for all the input arrays and the resulting collection of iterators is broadcast to a single shape.

The output arguments (if any) are then processed and any missing return arrays are constructed. If any provided output array doesn’t have the correct type (or is mis-aligned) and is smaller than the buffer size, then a new output array is constructed with the special UPDATEIFCOPY flag set so that when it is DECREF’d on completion of the function, it’s contents will be copied back into the output array. Iterators for the output arguments are then processed.

Finally, the decision is made about how to execute the looping mechanism to ensure that all elements of the input arrays are combined to produce the output arrays of the correct type. The options for loop execution are one-loop (for contiguous, aligned, and correct data- type), strided-loop (for non-contiguous but still aligned and correct data-type), and a buffered loop (for mis-aligned or incorrect data- type situations). Depending on which execution method is called for, the loop is then setup and computed.

Function call

This section describes how the basic universal function computation loop is setup and executed for each of the three different kinds of execution possibilities. If NPY_ALLOW_THREADS is defined during compilation, then the Python Global Interpreter Lock (GIL) is released prior to calling all of these loops (as long as they don’t involve object arrays). It is re-acquired if necessary to handle error conditions. The hardware error flags are checked only after the 1-D loop is calcluated.

One Loop

This is the simplest case of all. The ufunc is executed by calling the underlying 1-D loop exactly once. This is possible only when we have aligned data of the correct type (including byte-order) for both input and output and all arrays have uniform strides (either contiguous, 0-D, or 1-D). In this case, the 1-D computational loop is called once to compute the calculation for the entire array. Note that the hardware error flags are only checked after the entire calculation is complete.

Strided Loop

When the input and output arrays are aligned and of the correct type, but the striding is not uniform (non-contiguous and 2-D or larger), then a second looping structure is employed for the calculation. This approach converts all of the iterators for the input and output arguments to iterate over all but the largest dimension. The inner loop is then handled by the underlying 1-D computational loop. The outer loop is a standard iterator loop on the converted iterators. The hardware error flags are checked after each 1-D loop is completed.

Buffered Loop

This is the code that handles the situation whenever the input and/or output arrays are either misaligned or of the wrong data-type (including being byte-swapped) from what the underlying 1-D loop expects. The arrays are also assumed to be non-contiguous. The code works very much like the strided loop except for the inner 1-D loop is modified so that pre-processing is performed on the inputs and post- processing is performed on the outputs in bufsize chunks (where bufsize is a user-settable parameter). The underlying 1-D computational loop is called on data that is copied over (if it needs to be). The setup code and the loop code is considerably more complicated in this case because it has to handle:

  • memory allocation of the temporary buffers
  • deciding whether or not to use buffers on the input and output data (mis-aligned and/or wrong data-type)
  • copying and possibly casting data for any inputs or outputs for which buffers are necessary.
  • special-casing Object arrays so that reference counts are properly handled when copies and/or casts are necessary.
  • breaking up the inner 1-D loop into bufsize chunks (with a possible remainder).

Again, the hardware error flags are checked at the end of each 1-D loop.

Final output manipulation

Ufuncs allow other array-like classes to be passed seamlessly through the interface in that inputs of a particular class will induce the outputs to be of that same class. The mechanism by which this works is the following. If any of the inputs are not ndarrays and define the __array_wrap__ method, then the class with the largest __array_priority__ attribute determines the type of all the outputs (with the exception of any output arrays passed in). The __array_wrap__ method of the input array will be called with the ndarray being returned from the ufunc as it’s input. There are two calling styles of the __array_wrap__ function supported. The first takes the ndarray as the first argument and a tuple of “context” as the second argument. The context is (ufunc, arguments, output argument number). This is the first call tried. If a TypeError occurs, then the function is called with just the ndarray as the first argument.

Methods

Their are three methods of ufuncs that require calculation similar to the general-purpose ufuncs. These are reduce, accumulate, and reduceat. Each of these methods requires a setup command followed by a loop. There are four loop styles possible for the methods corresponding to no-elements, one-element, strided-loop, and buffered- loop. These are the same basic loop styles as implemented for the general purpose function call except for the no-element and one- element cases which are special-cases occurring when the input array objects have 0 and 1 elements respectively.

Setup

The setup function for all three methods is construct_reduce. This function creates a reducing loop object and fills it with parameters needed to complete the loop. All of the methods only work on ufuncs that take 2-inputs and return 1 output. Therefore, the underlying 1-D loop is selected assuming a signature of [ otype, otype, otype ] where otype is the requested reduction data-type. The buffer size and error handling is then retrieved from (per-thread) global storage. For small arrays that are mis-aligned or have incorrect data-type, a copy is made so that the un-buffered section of code is used. Then, the looping strategy is selected. If there is 1 element or 0 elements in the array, then a simple looping method is selected. If the array is not mis-aligned and has the correct data-type, then strided looping is selected. Otherwise, buffered looping must be performed. Looping parameters are then established, and the return array is constructed. The output array is of a different shape depending on whether the method is reduce, accumulate, or reduceat. If an output array is already provided, then it’s shape is checked. If the output array is not C-contiguous, aligned, and of the correct data type, then a temporary copy is made with the UPDATEIFCOPY flag set. In this way, the methods will be able to work with a well-behaved output array but the result will be copied back into the true output array when the method computation is complete. Finally, iterators are set up to loop over the correct axis (depending on the value of axis provided to the method) and the setup routine returns to the actual computation routine.

Reduce

All of the ufunc methods use the same underlying 1-D computational loops with input and output arguments adjusted so that the appropriate reduction takes place. For example, the key to the functioning of reduce is that the 1-D loop is called with the output and the second input pointing to the same position in memory and both having a step- size of 0. The first input is pointing to the input array with a step- size given by the appropriate stride for the selected axis. In this way, the operation performed is

where N+1 is the number of elements in the input, i, o is the output, and i[k] is the [image] element of i along the selected axis. This basic operations is repeated for arrays with greater than 1 dimension so that the reduction takes place for every 1-D sub-array along the selected axis. An iterator with the selected dimension removed handles this looping.

For buffered loops, care must be taken to copy and cast data before the loop function is called because the underlying loop expects aligned data of the correct data-type (including byte-order). The buffered loop must handle this copying and casting prior to calling the loop function on chunks no greater than the user-specified bufsize.

Accumulate

The accumulate function is very similar to the reduce function in that the output and the second input both point to the output. The difference is that the second input points to memory one stride behind the current output pointer. Thus, the operation performed is

The output has the same shape as the input and each 1-D loop operates over N elements when the shape in the selected axis is N+1. Again, buffered loops take care to copy and cast the data before calling the underlying 1-D computational loop.

Reduceat

The reduceat function is a generalization of both the reduce and accumulate functions. It implements a reduce over ranges of the input array specified by indices. The extra indices argument is checked to be sure that every input is not too large for the input array along the selected dimension before the loop calculations take place. The loop implementation is handled using code that is very similar to the reduce code repeated as many times as there are elements in the indices input. In particular: the first input pointer passed to the underlying 1-D computational loop points to the input array at the correct location indicated by the index array. In addition, the output pointer and the second input pointer passed to the underlying 1-D loop point to the same position in memory. The size of the 1-D computational loop is fixed to be the difference between the current index and the next index (when the current index is the last index, then the next index is assumed to be the length of the array along the selected dimension). In this way, the 1-D loop will implement a reduce over the specified indices.

Mis-aligned or a loop data-type that does not match the input and/or output data-type is handled using buffered code where-in data is copied to a temporary buffer and cast to the correct data-type if necessary prior to calling the underlying 1-D function. The temporary buffers are created in (element) sizes no bigger than the user settable buffer-size value. Thus, the loop must be flexible enough to call the underlying 1-D computational loop enough times to complete the total calculation in chunks no bigger than the buffer-size.


Numpy and SWIG

  • next
  • previous

Previous topic

Numpy C Code Explanations

Next topic

Numpy.i: a SWIG Interface File for NumPy

Numpy and SWIG

  • Numpy.i: a SWIG Interface File for NumPy
    • Introduction
    • Using numpy.i
    • Available Typemaps
    • NumPy Array Scalars and SWIG
    • Helper Functions
    • Beyond the Provided Typemaps
    • Summary
  • Testing the numpy.i Typemaps
    • Introduction
    • Testing Organization
    • Testing Header Files
    • Testing Source Files
    • Testing SWIG Interface Files
    • Testing Python Scripts


Numpy.i: a SWIG Interface File for NumPy

  • Numpy and SWIG
  • next
  • previous

Table Of Contents

  • Numpy.i: a SWIG Interface File for NumPy
    • Introduction
    • Using numpy.i
    • Available Typemaps
      • Input Arrays
      • In-Place Arrays
      • Argout Arrays
      • Argout View Arrays
      • Memory Managed Argout View Arrays
      • Output Arrays
      • Other Common Types: bool
      • Other Common Types: complex
    • NumPy Array Scalars and SWIG
      • Why is There a Second File?
    • Helper Functions
      • Macros
      • Routines
    • Beyond the Provided Typemaps
      • A Common Example
      • Other Situations
      • A Final Note
    • Summary

Previous topic

Numpy and SWIG

Next topic

Testing the numpy.i Typemaps

Numpy.i: a SWIG Interface File for NumPy

Introduction

The Simple Wrapper and Interface Generator (or SWIG) is a powerful tool for generating wrapper code for interfacing to a wide variety of scripting languages. SWIG can parse header files, and using only the code prototypes, create an interface to the target language. But SWIG is not omnipotent. For example, it cannot know from the prototype:

double rms(double* seq, int n);

what exactly seq is. Is it a single value to be altered in-place? Is it an array, and if so what is its length? Is it input-only? Output-only? Input-output? SWIG cannot determine these details, and does not attempt to do so.

If we designed rms, we probably made it a routine that takes an input-only array of length n of double values called seq and returns the root mean square. The default behavior of SWIG, however, will be to create a wrapper function that compiles, but is nearly impossible to use from the scripting language in the way the C routine was intended.

For Python, the preferred way of handling contiguous (or technically, strided) blocks of homogeneous data is with NumPy, which provides full object-oriented access to multidimensial arrays of data. Therefore, the most logical Python interface for the rms function would be (including doc string):

def rms(seq):
    """
    rms: return the root mean square of a sequence
    rms(numpy.ndarray) -> double
    rms(list) -> double
    rms(tuple) -> double
    """

where seq would be a NumPy array of double values, and its length n would be extracted from seq internally before being passed to the C routine. Even better, since NumPy supports construction of arrays from arbitrary Python sequences, seq itself could be a nearly arbitrary sequence (so long as each element can be converted to a double) and the wrapper code would internally convert it to a NumPy array before extracting its data and length.

SWIG allows these types of conversions to be defined via a mechanism called typemaps. This document provides information on how to use numpy.i, a SWIG interface file that defines a series of typemaps intended to make the type of array-related conversions described above relatively simple to implement. For example, suppose that the rms function prototype defined above was in a header file named rms.h. To obtain the Python interface discussed above, your SWIG interface file would need the following:

%{
#define SWIG_FILE_WITH_INIT
#include "rms.h"
%}

%include "numpy.i"

%init %{
import_array();
%}

%apply (double* IN_ARRAY1, int DIM1) {(double* seq, int n)};
%include "rms.h"

Typemaps are keyed off a list of one or more function arguments, either by type or by type and name. We will refer to such lists as signatures. One of the many typemaps defined by numpy.i is used above and has the signature (double* IN_ARRAY1, int DIM1). The argument names are intended to suggest that the double* argument is an input array of one dimension and that the int represents the size of that dimension. This is precisely the pattern in the rms prototype.

Most likely, no actual prototypes to be wrapped will have the argument names IN_ARRAY1 and DIM1. We use the SWIG %apply directive to apply the typemap for one-dimensional input arrays of type double to the actual prototype used by rms. Using numpy.i effectively, therefore, requires knowing what typemaps are available and what they do.

A SWIG interface file that includes the SWIG directives given above will produce wrapper code that looks something like:

 1 PyObject *_wrap_rms(PyObject *args) {
 2   PyObject *resultobj = 0;
 3   double *arg1 = (double *) 0 ;
 4   int arg2 ;
 5   double result;
 6   PyArrayObject *array1 = NULL ;
 7   int is_new_object1 = 0 ;
 8   PyObject * obj0 = 0 ;
 9
10   if (!PyArg_ParseTuple(args,(char *)"O:rms",&obj0)) SWIG_fail;
11   {
12     array1 = obj_to_array_contiguous_allow_conversion(
13                  obj0, NPY_DOUBLE, &is_new_object1);
14     npy_intp size[1] = {
15       -1
16     };
17     if (!array1 || !require_dimensions(array1, 1) ||
18         !require_size(array1, size, 1)) SWIG_fail;
19     arg1 = (double*) array1->data;
20     arg2 = (int) array1->dimensions[0];
21   }
22   result = (double)rms(arg1,arg2);
23   resultobj = SWIG_From_double((double)(result));
24   {
25     if (is_new_object1 && array1) Py_DECREF(array1);
26   }
27   return resultobj;
28 fail:
29   {
30     if (is_new_object1 && array1) Py_DECREF(array1);
31   }
32   return NULL;
33 }

The typemaps from numpy.i are responsible for the following lines of code: 12–20, 25 and 30. Line 10 parses the input to the rms function. From the format string "O:rms", we can see that the argument list is expected to be a single Python object (specified by the O before the colon) and whose pointer is stored in obj0. A number of functions, supplied by numpy.i, are called to make and check the (possible) conversion from a generic Python object to a NumPy array. These functions are explained in the section Helper Functions, but hopefully their names are self-explanatory. At line 12 we use obj0 to construct a NumPy array. At line 17, we check the validity of the result: that it is non-null and that it has a single dimension of arbitrary length. Once these states are verified, we extract the data buffer and length in lines 19 and 20 so that we can call the underlying C function at line 22. Line 25 performs memory management for the case where we have created a new array that is no longer needed.

This code has a significant amount of error handling. Note the SWIG_fail is a macro for goto fail, refering to the label at line 28. If the user provides the wrong number of arguments, this will be caught at line 10. If construction of the NumPy array fails or produces an array with the wrong number of dimensions, these errors are caught at line 17. And finally, if an error is detected, memory is still managed correctly at line 30.

Note that if the C function signature was in a different order:

double rms(int n, double* seq);

that SWIG would not match the typemap signature given above with the argument list for rms. Fortunately, numpy.i has a set of typemaps with the data pointer given last:

%apply (int DIM1, double* IN_ARRAY1) {(int n, double* seq)};

This simply has the effect of switching the definitions of arg1 and arg2 in lines 3 and 4 of the generated code above, and their assignments in lines 19 and 20.

Using numpy.i

The numpy.i file is currently located in the tools/swig sub-directory under the numpy installation directory. Typically, you will want to copy it to the directory where you are developing your wrappers.

A simple module that only uses a single SWIG interface file should include the following:

%{
#define SWIG_FILE_WITH_INIT
%}
%include "numpy.i"
%init %{
import_array();
%}

Within a compiled Python module, import_array() should only get called once. This could be in a C/C++ file that you have written and is linked to the module. If this is the case, then none of your interface files should #define SWIG_FILE_WITH_INIT or call import_array(). Or, this initialization call could be in a wrapper file generated by SWIG from an interface file that has the %init block as above. If this is the case, and you have more than one SWIG interface file, then only one interface file should #define SWIG_FILE_WITH_INIT and call import_array().

Available Typemaps

The typemap directives provided by numpy.i for arrays of different data types, say double and int, and dimensions of different types, say int or long, are identical to one another except for the C and NumPy type specifications. The typemaps are therefore implemented (typically behind the scenes) via a macro:

%numpy_typemaps(DATA_TYPE, DATA_TYPECODE, DIM_TYPE)

that can be invoked for appropriate (DATA_TYPE, DATA_TYPECODE, DIM_TYPE) triplets. For example:

%numpy_typemaps(double, NPY_DOUBLE, int)
%numpy_typemaps(int,    NPY_INT   , int)

The numpy.i interface file uses the %numpy_typemaps macro to implement typemaps for the following C data types and int dimension types:

  • signed char
  • unsigned char
  • short
  • unsigned short
  • int
  • unsigned int
  • long
  • unsigned long
  • long long
  • unsigned long long
  • float
  • double

In the following descriptions, we reference a generic DATA_TYPE, which could be any of the C data types listed above, and DIM_TYPE which should be one of the many types of integers.

The typemap signatures are largely differentiated on the name given to the buffer pointer. Names with FARRAY are for Fortran-ordered arrays, and names with ARRAY are for C-ordered (or 1D arrays).

Input Arrays

Input arrays are defined as arrays of data that are passed into a routine but are not altered in-place or returned to the user. The Python input array is therefore allowed to be almost any Python sequence (such as a list) that can be converted to the requested type of array. The input array signatures are

1D:

  • ( DATA_TYPE IN_ARRAY1[ANY] )
  • ( DATA_TYPE* IN_ARRAY1, int DIM1 )
  • ( int DIM1, DATA_TYPE* IN_ARRAY1 )

2D:

  • ( DATA_TYPE IN_ARRAY2[ANY][ANY] )
  • ( DATA_TYPE* IN_ARRAY2, int DIM1, int DIM2 )
  • ( int DIM1, int DIM2, DATA_TYPE* IN_ARRAY2 )
  • ( DATA_TYPE* IN_FARRAY2, int DIM1, int DIM2 )
  • ( int DIM1, int DIM2, DATA_TYPE* IN_FARRAY2 )

3D:

  • ( DATA_TYPE IN_ARRAY3[ANY][ANY][ANY] )
  • ( DATA_TYPE* IN_ARRAY3, int DIM1, int DIM2, int DIM3 )
  • ( int DIM1, int DIM2, int DIM3, DATA_TYPE* IN_ARRAY3 )
  • ( DATA_TYPE* IN_FARRAY3, int DIM1, int DIM2, int DIM3 )
  • ( int DIM1, int DIM2, int DIM3, DATA_TYPE* IN_FARRAY3 )

4D:

  • (DATA_TYPE IN_ARRAY4[ANY][ANY][ANY][ANY])
  • (DATA_TYPE* IN_ARRAY4, DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, DIM_TYPE DIM4)
  • (DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, , DIM_TYPE DIM4, DATA_TYPE* IN_ARRAY4)
  • (DATA_TYPE* IN_FARRAY4, DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, DIM_TYPE DIM4)
  • (DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, DIM_TYPE DIM4, DATA_TYPE* IN_FARRAY4)

The first signature listed, ( DATA_TYPE IN_ARRAY[ANY] ) is for one-dimensional arrays with hard-coded dimensions. Likewise, ( DATA_TYPE IN_ARRAY2[ANY][ANY] ) is for two-dimensional arrays with hard-coded dimensions, and similarly for three-dimensional.

In-Place Arrays

In-place arrays are defined as arrays that are modified in-place. The input values may or may not be used, but the values at the time the function returns are significant. The provided Python argument must therefore be a NumPy array of the required type. The in-place signatures are

1D:

  • ( DATA_TYPE INPLACE_ARRAY1[ANY] )
  • ( DATA_TYPE* INPLACE_ARRAY1, int DIM1 )
  • ( int DIM1, DATA_TYPE* INPLACE_ARRAY1 )

2D:

  • ( DATA_TYPE INPLACE_ARRAY2[ANY][ANY] )
  • ( DATA_TYPE* INPLACE_ARRAY2, int DIM1, int DIM2 )
  • ( int DIM1, int DIM2, DATA_TYPE* INPLACE_ARRAY2 )
  • ( DATA_TYPE* INPLACE_FARRAY2, int DIM1, int DIM2 )
  • ( int DIM1, int DIM2, DATA_TYPE* INPLACE_FARRAY2 )

3D:

  • ( DATA_TYPE INPLACE_ARRAY3[ANY][ANY][ANY] )
  • ( DATA_TYPE* INPLACE_ARRAY3, int DIM1, int DIM2, int DIM3 )
  • ( int DIM1, int DIM2, int DIM3, DATA_TYPE* INPLACE_ARRAY3 )
  • ( DATA_TYPE* INPLACE_FARRAY3, int DIM1, int DIM2, int DIM3 )
  • ( int DIM1, int DIM2, int DIM3, DATA_TYPE* INPLACE_FARRAY3 )

4D:

  • (DATA_TYPE INPLACE_ARRAY4[ANY][ANY][ANY][ANY])
  • (DATA_TYPE* INPLACE_ARRAY4, DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, DIM_TYPE DIM4)
  • (DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, , DIM_TYPE DIM4, DATA_TYPE* INPLACE_ARRAY4)
  • (DATA_TYPE* INPLACE_FARRAY4, DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, DIM_TYPE DIM4)
  • (DIM_TYPE DIM1, DIM_TYPE DIM2, DIM_TYPE DIM3, DIM_TYPE DIM4, DATA_TYPE* INPLACE_FARRAY4)

These typemaps now check to make sure that the INPLACE_ARRAY arguments use native byte ordering. If not, an exception is raised.

Argout Arrays

Argout arrays are arrays that appear in the input arguments in C, but are in fact output arrays. This pattern occurs often when there is more than one output variable and the single return argument is therefore not sufficient. In Python, the convential way to return multiple arguments is to pack them into a sequence (tuple, list, etc.) and return the sequence. This is what the argout typemaps do. If a wrapped function that uses these argout typemaps has more than one return argument, they are packed into a tuple or list, depending on the version of Python. The Python user does not pass these arrays in, they simply get returned. For the case where a dimension is specified, the python user must provide that dimension as an argument. The argout signatures are

1D:

  • ( DATA_TYPE ARGOUT_ARRAY1[ANY] )
  • ( DATA_TYPE* ARGOUT_ARRAY1, int DIM1 )
  • ( int DIM1, DATA_TYPE* ARGOUT_ARRAY1 )

2D:

  • ( DATA_TYPE ARGOUT_ARRAY2[ANY][ANY] )

3D:

  • ( DATA_TYPE ARGOUT_ARRAY3[ANY][ANY][ANY] )

4D:

  • ( DATA_TYPE ARGOUT_ARRAY4[ANY][ANY][ANY][ANY] )

These are typically used in situations where in C/C++, you would allocate a(n) array(s) on the heap, and call the function to fill the array(s) values. In Python, the arrays are allocated for you and returned as new array objects.

Note that we support DATA_TYPE* argout typemaps in 1D, but not 2D or 3D. This is because of a quirk with the SWIG typemap syntax and cannot be avoided. Note that for these types of 1D typemaps, the Python function will take a single argument representing DIM1.

Argout View Arrays

Argoutview arrays are for when your C code provides you with a view of its internal data and does not require any memory to be allocated by the user. This can be dangerous. There is almost no way to guarantee that the internal data from the C code will remain in existence for the entire lifetime of the NumPy array that encapsulates it. If the user destroys the object that provides the view of the data before destroying the NumPy array, then using that array may result in bad memory references or segmentation faults. Nevertheless, there are situations, working with large data sets, where you simply have no other choice.

The C code to be wrapped for argoutview arrays are characterized by pointers: pointers to the dimensions and double pointers to the data, so that these values can be passed back to the user. The argoutview typemap signatures are therefore

1D:

  • ( DATA_TYPE** ARGOUTVIEW_ARRAY1, DIM_TYPE* DIM1 )
  • ( DIM_TYPE* DIM1, DATA_TYPE** ARGOUTVIEW_ARRAY1 )

2D:

  • ( DATA_TYPE** ARGOUTVIEW_ARRAY2, DIM_TYPE* DIM1, DIM_TYPE* DIM2 )
  • ( DIM_TYPE* DIM1, DIM_TYPE* DIM2, DATA_TYPE** ARGOUTVIEW_ARRAY2 )
  • ( DATA_TYPE** ARGOUTVIEW_FARRAY2, DIM_TYPE* DIM1, DIM_TYPE* DIM2 )
  • ( DIM_TYPE* DIM1, DIM_TYPE* DIM2, DATA_TYPE** ARGOUTVIEW_FARRAY2 )

3D:

  • ( DATA_TYPE** ARGOUTVIEW_ARRAY3, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3)
  • ( DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DATA_TYPE** ARGOUTVIEW_ARRAY3)
  • ( DATA_TYPE** ARGOUTVIEW_FARRAY3, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3)
  • ( DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DATA_TYPE** ARGOUTVIEW_FARRAY3)

4D:

  • (DATA_TYPE** ARGOUTVIEW_ARRAY4, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4)
  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4, DATA_TYPE** ARGOUTVIEW_ARRAY4)
  • (DATA_TYPE** ARGOUTVIEW_FARRAY4, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4)
  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4, DATA_TYPE** ARGOUTVIEW_FARRAY4)

Note that arrays with hard-coded dimensions are not supported. These cannot follow the double pointer signatures of these typemaps.

Memory Managed Argout View Arrays

A recent addition to numpy.i are typemaps that permit argout arrays with views into memory that is managed. See the discussion here.

1D:

  • (DATA_TYPE** ARGOUTVIEWM_ARRAY1, DIM_TYPE* DIM1)
  • (DIM_TYPE* DIM1, DATA_TYPE** ARGOUTVIEWM_ARRAY1)

2D:

  • (DATA_TYPE** ARGOUTVIEWM_ARRAY2, DIM_TYPE* DIM1, DIM_TYPE* DIM2)
  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DATA_TYPE** ARGOUTVIEWM_ARRAY2)
  • (DATA_TYPE** ARGOUTVIEWM_FARRAY2, DIM_TYPE* DIM1, DIM_TYPE* DIM2)
  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DATA_TYPE** ARGOUTVIEWM_FARRAY2)

3D:

  • (DATA_TYPE** ARGOUTVIEWM_ARRAY3, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3)
  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DATA_TYPE** ARGOUTVIEWM_ARRAY3)
  • (DATA_TYPE** ARGOUTVIEWM_FARRAY3, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3)
  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DATA_TYPE** ARGOUTVIEWM_FARRAY3)

4D:

  • (DATA_TYPE** ARGOUTVIEWM_ARRAY4, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4)
  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4, DATA_TYPE** ARGOUTVIEWM_ARRAY4)
  • (DATA_TYPE** ARGOUTVIEWM_FARRAY4, DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4)
  • (DIM_TYPE* DIM1, DIM_TYPE* DIM2, DIM_TYPE* DIM3, DIM_TYPE* DIM4, DATA_TYPE** ARGOUTVIEWM_FARRAY4)

Output Arrays

The numpy.i interface file does not support typemaps for output arrays, for several reasons. First, C/C++ return arguments are limited to a single value. This prevents obtaining dimension information in a general way. Second, arrays with hard-coded lengths are not permitted as return arguments. In other words:

double[3] newVector(double x, double y, double z);

is not legal C/C++ syntax. Therefore, we cannot provide typemaps of the form:

%typemap(out) (TYPE[ANY]);

If you run into a situation where a function or method is returning a pointer to an array, your best bet is to write your own version of the function to be wrapped, either with %extend for the case of class methods or %ignore and %rename for the case of functions.

Other Common Types: bool

Note that C++ type bool is not supported in the list in the Available Typemaps section. NumPy bools are a single byte, while the C++ bool is four bytes (at least on my system). Therefore:

%numpy_typemaps(bool, NPY_BOOL, int)

will result in typemaps that will produce code that reference improper data lengths. You can implement the following macro expansion:

%numpy_typemaps(bool, NPY_UINT, int)

to fix the data length problem, and Input Arrays will work fine, but In-Place Arrays might fail type-checking.

Other Common Types: complex

Typemap conversions for complex floating-point types is also not supported automatically. This is because Python and NumPy are written in C, which does not have native complex types. Both Python and NumPy implement their own (essentially equivalent) struct definitions for complex variables:

/* Python */
typedef struct {double real; double imag;} Py_complex;

/* NumPy */
typedef struct {float  real, imag;} npy_cfloat;
typedef struct {double real, imag;} npy_cdouble;

We could have implemented:

%numpy_typemaps(Py_complex , NPY_CDOUBLE, int)
%numpy_typemaps(npy_cfloat , NPY_CFLOAT , int)
%numpy_typemaps(npy_cdouble, NPY_CDOUBLE, int)

which would have provided automatic type conversions for arrays of type Py_complex, npy_cfloat and npy_cdouble. However, it seemed unlikely that there would be any independent (non-Python, non-NumPy) application code that people would be using SWIG to generate a Python interface to, that also used these definitions for complex types. More likely, these application codes will define their own complex types, or in the case of C++, use std::complex. Assuming these data structures are compatible with Python and NumPy complex types, %numpy_typemap expansions as above (with the user’s complex type substituted for the first argument) should work.

NumPy Array Scalars and SWIG

SWIG has sophisticated type checking for numerical types. For example, if your C/C++ routine expects an integer as input, the code generated by SWIG will check for both Python integers and Python long integers, and raise an overflow error if the provided Python integer is too big to cast down to a C integer. With the introduction of NumPy scalar arrays into your Python code, you might conceivably extract an integer from a NumPy array and attempt to pass this to a SWIG-wrapped C/C++ function that expects an int, but the SWIG type checking will not recognize the NumPy array scalar as an integer. (Often, this does in fact work – it depends on whether NumPy recognizes the integer type you are using as inheriting from the Python integer type on the platform you are using. Sometimes, this means that code that works on a 32-bit machine will fail on a 64-bit machine.)

If you get a Python error that looks like the following:

TypeError: in method 'MyClass_MyMethod', argument 2 of type 'int'

and the argument you are passing is an integer extracted from a NumPy array, then you have stumbled upon this problem. The solution is to modify the SWIG type conversion system to accept Numpy array scalars in addition to the standard integer types. Fortunately, this capabilitiy has been provided for you. Simply copy the file:

pyfragments.swg

to the working build directory for you project, and this problem will be fixed. It is suggested that you do this anyway, as it only increases the capabilities of your Python interface.

Why is There a Second File?

The SWIG type checking and conversion system is a complicated combination of C macros, SWIG macros, SWIG typemaps and SWIG fragments. Fragments are a way to conditionally insert code into your wrapper file if it is needed, and not insert it if not needed. If multiple typemaps require the same fragment, the fragment only gets inserted into your wrapper code once.

There is a fragment for converting a Python integer to a C long. There is a different fragment that converts a Python integer to a C int, that calls the rountine defined in the long fragment. We can make the changes we want here by changing the definition for the long fragment. SWIG determines the active definition for a fragment using a “first come, first served” system. That is, we need to define the fragment for long conversions prior to SWIG doing it internally. SWIG allows us to do this by putting our fragment definitions in the file pyfragments.swg. If we were to put the new fragment definitions in numpy.i, they would be ignored.

Helper Functions

The numpy.i file containes several macros and routines that it uses internally to build its typemaps. However, these functions may be useful elsewhere in your interface file. These macros and routines are implemented as fragments, which are described briefly in the previous section. If you try to use one or more of the following macros or functions, but your compiler complains that it does not recognize the symbol, then you need to force these fragments to appear in your code using:

%fragment("NumPy_Fragments");

in your SWIG interface file.

Macros

is_array(a)
Evaluates as true if a is non-NULL and can be cast to a PyArrayObject*.
array_type(a)
Evaluates to the integer data type code of a, assuming a can be cast to a PyArrayObject*.
array_numdims(a)
Evaluates to the integer number of dimensions of a, assuming a can be cast to a PyArrayObject*.
array_dimensions(a)
Evaluates to an array of type npy_intp and length array_numdims(a), giving the lengths of all of the dimensions of a, assuming a can be cast to a PyArrayObject*.
array_size(a,i)
Evaluates to the i-th dimension size of a, assuming a can be cast to a PyArrayObject*.
array_strides(a)
Evaluates to an array of type npy_intp and length array_numdims(a), giving the stridess of all of the dimensions of a, assuming a can be cast to a PyArrayObject*. A stride is the distance in bytes between an element and its immediate neighbor along the same axis.
array_stride(a,i)
Evaluates to the i-th stride of a, assuming a can be cast to a PyArrayObject*.
array_data(a)
Evaluates to a pointer of type void* that points to the data buffer of a, assuming a can be cast to a PyArrayObject*.
array_descr(a)
Returns a borrowed reference to the dtype property (PyArray_Descr*) of a, assuming a can be cast to a PyArrayObject*.
array_flags(a)
Returns an integer representing the flags of a, assuming a can be cast to a PyArrayObject*.
array_enableflags(a,f)
Sets the flag represented by f of a, assuming a can be cast to a PyArrayObject*.
array_is_contiguous(a)
Evaluates as true if a is a contiguous array. Equivalent to (PyArray_ISCONTIGUOUS(a)).
array_is_native(a)
Evaluates as true if the data buffer of a uses native byte order. Equivalent to (PyArray_ISNOTSWAPPED(a)).
array_is_fortran(a)
Evaluates as true if a is FORTRAN ordered.

Routines

pytype_string()

Return type: const char*

Arguments:

  • PyObject* py_obj, a general Python object.

Return a string describing the type of py_obj.

typecode_string()

Return type: const char*

Arguments:

  • int typecode, a NumPy integer typecode.

Return a string describing the type corresponding to the NumPy typecode.

type_match()

Return type: int

Arguments:

  • int actual_type, the NumPy typecode of a NumPy array.
  • int desired_type, the desired NumPy typecode.

Make sure that actual_type is compatible with desired_type. For example, this allows character and byte types, or int and long types, to match. This is now equivalent to PyArray_EquivTypenums().

obj_to_array_no_conversion()

Return type: PyArrayObject*

Arguments:

  • PyObject* input, a general Python object.
  • int typecode, the desired NumPy typecode.

Cast input to a PyArrayObject* if legal, and ensure that it is of type typecode. If input cannot be cast, or the typecode is wrong, set a Python error and return NULL.

obj_to_array_allow_conversion()

Return type: PyArrayObject*

Arguments:

  • PyObject* input, a general Python object.
  • int typecode, the desired NumPy typecode of the resulting array.
  • int* is_new_object, returns a value of 0 if no conversion performed, else 1.

Convert input to a NumPy array with the given typecode. On success, return a valid PyArrayObject* with the correct type. On failure, the Python error string will be set and the routine returns NULL.

make_contiguous()

Return type: PyArrayObject*

Arguments:

  • PyArrayObject* ary, a NumPy array.
  • int* is_new_object, returns a value of 0 if no conversion performed, else 1.
  • int min_dims, minimum allowable dimensions.
  • int max_dims, maximum allowable dimensions.

Check to see if ary is contiguous. If so, return the input pointer and flag it as not a new object. If it is not contiguous, create a new PyArrayObject* using the original data, flag it as a new object and return the pointer.

make_fortran()

Return type: PyArrayObject*

Arguments

  • PyArrayObject* ary, a NumPy array.
  • int* is_new_object, returns a value of 0 if no conversion performed, else 1.

Check to see if ary is Fortran contiguous. If so, return the input pointer and flag it as not a new object. If it is not Fortran contiguous, create a new PyArrayObject* using the original data, flag it as a new object and return the pointer.

obj_to_array_contiguous_allow_conversion()

Return type: PyArrayObject*

Arguments:

  • PyObject* input, a general Python object.
  • int typecode, the desired NumPy typecode of the resulting array.
  • int* is_new_object, returns a value of 0 if no conversion performed, else 1.

Convert input to a contiguous PyArrayObject* of the specified type. If the input object is not a contiguous PyArrayObject*, a new one will be created and the new object flag will be set.

obj_to_array_fortran_allow_conversion()

Return type: PyArrayObject*

Arguments:

  • PyObject* input, a general Python object.
  • int typecode, the desired NumPy typecode of the resulting array.
  • int* is_new_object, returns a value of 0 if no conversion performed, else 1.

Convert input to a Fortran contiguous PyArrayObject* of the specified type. If the input object is not a Fortran contiguous PyArrayObject*, a new one will be created and the new object flag will be set.

require_contiguous()

Return type: int

Arguments:

  • PyArrayObject* ary, a NumPy array.

Test whether ary is contiguous. If so, return 1. Otherwise, set a Python error and return 0.

require_native()

Return type: int

Arguments:

  • PyArray_Object* ary, a NumPy array.

Require that ary is not byte-swapped. If the array is not byte-swapped, return 1. Otherwise, set a Python error and return 0.

require_dimensions()

Return type: int

Arguments:

  • PyArrayObject* ary, a NumPy array.
  • int exact_dimensions, the desired number of dimensions.

Require ary to have a specified number of dimensions. If the array has the specified number of dimensions, return 1. Otherwise, set a Python error and return 0.

require_dimensions_n()

Return type: int

Arguments:

  • PyArrayObject* ary, a NumPy array.
  • int* exact_dimensions, an array of integers representing acceptable numbers of dimensions.
  • int n, the length of exact_dimensions.

Require ary to have one of a list of specified number of dimensions. If the array has one of the specified number of dimensions, return 1. Otherwise, set the Python error string and return 0.

require_size()

Return type: int

Arguments:

  • PyArrayObject* ary, a NumPy array.
  • npy_int* size, an array representing the desired lengths of each dimension.
  • int n, the length of size.

Require ary to have a specified shape. If the array has the specified shape, return 1. Otherwise, set the Python error string and return 0.

require_fortran()

Return type: int

Arguments:

  • PyArrayObject* ary, a NumPy array.

Require the given PyArrayObject to to be Fortran ordered. If the the PyArrayObject is already Fortran ordered, do nothing. Else, set the Fortran ordering flag and recompute the strides.

Beyond the Provided Typemaps

There are many C or C++ array/NumPy array situations not covered by a simple %include "numpy.i" and subsequent %apply directives.

A Common Example

Consider a reasonable prototype for a dot product function:

double dot(int len, double* vec1, double* vec2);

The Python interface that we want is:

def dot(vec1, vec2):
    """
    dot(PyObject,PyObject) -> double
    """

The problem here is that there is one dimension argument and two array arguments, and our typemaps are set up for dimensions that apply to a single array (in fact, SWIG does not provide a mechanism for associating len with vec2 that takes two Python input arguments). The recommended solution is the following:

%apply (int DIM1, double* IN_ARRAY1) {(int len1, double* vec1),
                                      (int len2, double* vec2)}
%rename (dot) my_dot;
%exception my_dot {
    $action
    if (PyErr_Occurred()) SWIG_fail;
}
%inline %{
double my_dot(int len1, double* vec1, int len2, double* vec2) {
    if (len1 != len2) {
        PyErr_Format(PyExc_ValueError,
                     "Arrays of lengths (%d,%d) given",
                     len1, len2);
        return 0.0;
    }
    return dot(len1, vec1, vec2);
}
%}

If the header file that contains the prototype for double dot() also contains other prototypes that you want to wrap, so that you need to %include this header file, then you will also need a %ignore dot; directive, placed after the %rename and before the %include directives. Or, if the function in question is a class method, you will want to use %extend rather than %inline in addition to %ignore.

A note on error handling: Note that my_dot returns a double but that it can also raise a Python error. The resulting wrapper function will return a Python float representation of 0.0 when the vector lengths do not match. Since this is not NULL, the Python interpreter will not know to check for an error. For this reason, we add the %exception directive above for my_dot to get the behavior we want (note that $action is a macro that gets expanded to a valid call to my_dot). In general, you will probably want to write a SWIG macro to perform this task.

Other Situations

There are other wrapping situations in which numpy.i may be helpful when you encounter them.

  • In some situations, it is possible that you could use the %numpy_typemaps macro to implement typemaps for your own types. See the Other Common Types: bool or Other Common Types: complex sections for examples. Another situation is if your dimensions are of a type other than int (say long for example):

    %numpy_typemaps(double, NPY_DOUBLE, long)

  • You can use the code in numpy.i to write your own typemaps. For example, if you had a five-dimensional array as a function argument, you could cut-and-paste the appropriate four-dimensional typemaps into your interface file. The modifications for the fourth dimension would be trivial.

  • Sometimes, the best approach is to use the %extend directive to define new methods for your classes (or overload existing ones) that take a PyObject* (that either is or can be converted to a PyArrayObject*) instead of a pointer to a buffer. In this case, the helper routines in numpy.i can be very useful.

  • Writing typemaps can be a bit nonintuitive. If you have specific questions about writing SWIG typemaps for NumPy, the developers of numpy.i do monitor the Numpy-discussion and Swig-user mail lists.

A Final Note

When you use the %apply directive, as is usually necessary to use numpy.i, it will remain in effect until you tell SWIG that it shouldn’t be. If the arguments to the functions or methods that you are wrapping have common names, such as length or vector, these typemaps may get applied in situations you do not expect or want. Therefore, it is always a good idea to add a %clear directive after you are done with a specific typemap:

%apply (double* IN_ARRAY1, int DIM1) {(double* vector, int length)}
%include "my_header.h"
%clear (double* vector, int length);

In general, you should target these typemap signatures specifically where you want them, and then clear them after you are done.

Summary

Out of the box, numpy.i provides typemaps that support conversion between NumPy arrays and C arrays:

  • That can be one of 12 different scalar types: signed char, unsigned char, short, unsigned short, int, unsigned int, long, unsigned long, long long, unsigned long long, float and double.
  • That support 74 different argument signatures for each data type, including:
    • One-dimensional, two-dimensional, three-dimensional and four-dimensional arrays.
    • Input-only, in-place, argout, argoutview, and memory managed argoutview behavior.
    • Hard-coded dimensions, data-buffer-then-dimensions specification, and dimensions-then-data-buffer specification.
    • Both C-ordering (“last dimension fastest”) or Fortran-ordering (“first dimension fastest”) support for 2D, 3D and 4D arrays.

The numpy.i interface file also provides additional tools for wrapper developers, including:

  • A SWIG macro (%numpy_typemaps) with three arguments for implementing the 74 argument signatures for the user’s choice of (1) C data type, (2) NumPy data type (assuming they match), and (3) dimension type.
  • Fourteen C macros and fifteen C functions that can be used to write specialized typemaps, extensions, or inlined functions that handle cases not covered by the provided typemaps. Note that the macros and functions are coded specifically to work with the NumPy C/API regardless of NumPy version number, both before and after the deprecation of some aspects of the API after version 1.6.


Testing the numpy.i Typemaps

  • Numpy and SWIG
  • next
  • previous

Table Of Contents

  • Testing the numpy.i Typemaps
    • Introduction
    • Testing Organization
    • Testing Header Files
    • Testing Source Files
    • Testing SWIG Interface Files
    • Testing Python Scripts

Previous topic

Numpy.i: a SWIG Interface File for NumPy

Next topic

F2PY Users Guide and Reference Manual

Testing the numpy.i Typemaps

Introduction

Writing tests for the numpy.i SWIG interface file is a combinatorial headache. At present, 12 different data types are supported, each with 74 different argument signatures, for a total of 888 typemaps supported “out of the box”. Each of these typemaps, in turn, might require several unit tests in order to verify expected behavior for both proper and improper inputs. Currently, this results in 1,427 individual unit tests that are performed when make test is run in the numpy/docs/swig subdirectory.

To facilitate this many similar unit tests, some high-level programming techniques are employed, including C and SWIG macros, as well as Python inheritance. The purpose of this document is to describe the testing infrastructure employed to verify that the numpy.i typemaps are working as expected.

Testing Organization

There are three indepedent testing frameworks supported, for one-, two-, and three-dimensional arrays respectively. For one-dimensional arrays, there are two C++ files, a header and a source, named:

Vector.h
Vector.cxx

that contain prototypes and code for a variety of functions that have one-dimensional arrays as function arguments. The file:

Vector.i

is a SWIG interface file that defines a python module Vector that wraps the functions in Vector.h while utilizing the typemaps in numpy.i to correctly handle the C arrays.

The Makefile calls swig to generate Vector.py and Vector_wrap.cxx, and also executes the setup.py script that compiles Vector_wrap.cxx and links together the extension module _Vector.so or _Vector.dylib, depending on the platform. This extension module and the proxy file Vector.py are both placed in a subdirectory under the build directory.

The actual testing takes place with a Python script named:

testVector.py

that uses the standard Python library module unittest, which performs several tests of each function defined in Vector.h for each data type supported.

Two-dimensional arrays are tested in exactly the same manner. The above description applies, but with Matrix substituted for Vector. For three-dimensional tests, substitute Tensor for Vector. For four-dimensional tests, substitute SuperTensor for Vector. For the descriptions that follow, we will reference the Vector tests, but the same information applies to Matrix, Tensor and SuperTensor tests.

The command make test will ensure that all of the test software is built and then run all three test scripts.

Testing Header Files

Vector.h is a C++ header file that defines a C macro called TEST_FUNC_PROTOS that takes two arguments: TYPE, which is a data type name such as unsigned int; and SNAME, which is a short name for the same data type with no spaces, e.g. uint. This macro defines several function prototypes that have the prefix SNAME and have at least one argument that is an array of type TYPE. Those functions that have return arguments return a TYPE value.

TEST_FUNC_PROTOS is then implemented for all of the data types supported by numpy.i:

  • signed char
  • unsigned char
  • short
  • unsigned short
  • int
  • unsigned int
  • long
  • unsigned long
  • long long
  • unsigned long long
  • float
  • double

Testing Source Files

Vector.cxx is a C++ source file that implements compilable code for each of the function prototypes specified in Vector.h. It defines a C macro TEST_FUNCS that has the same arguments and works in the same way as TEST_FUNC_PROTOS does in Vector.h. TEST_FUNCS is implemented for each of the 12 data types as above.

Testing SWIG Interface Files

Vector.i is a SWIG interface file that defines python module Vector. It follows the conventions for using numpy.i as described in this chapter. It defines a SWIG macro %apply_numpy_typemaps that has a single argument TYPE. It uses the SWIG directive %apply to apply the provided typemaps to the argument signatures found in Vector.h. This macro is then implemented for all of the data types supported by numpy.i. It then does a %include "Vector.h" to wrap all of the function prototypes in Vector.h using the typemaps in numpy.i.

Testing Python Scripts

After make is used to build the testing extension modules, testVector.py can be run to execute the tests. As with other scripts that use unittest to facilitate unit testing, testVector.py defines a class that inherits from unittest.TestCase:

class VectorTestCase(unittest.TestCase):

However, this class is not run directly. Rather, it serves as a base class to several other python classes, each one specific to a particular data type. The VectorTestCase class stores two strings for typing information:

self.typeStr
A string that matches one of the SNAME prefixes used in Vector.h and Vector.cxx. For example, "double".
self.typeCode
A short (typically single-character) string that represents a data type in numpy and corresponds to self.typeStr. For example, if self.typeStr is "double", then self.typeCode should be "d".

Each test defined by the VectorTestCase class extracts the python function it is trying to test by accessing the Vector module’s dictionary:

length = Vector.__dict__[self.typeStr + "Length"]

In the case of double precision tests, this will return the python function Vector.doubleLength.

We then define a new test case class for each supported data type with a short definition such as:

class doubleTestCase(VectorTestCase):
    def __init__(self, methodName="runTest"):
        VectorTestCase.__init__(self, methodName)
        self.typeStr  = "double"
        self.typeCode = "d"

Each of these 12 classes is collected into a unittest.TestSuite, which is then executed. Errors and failures are summed together and returned as the exit argument. Any non-zero result indicates that at least one test did not pass.


F2PY Users Guide and Reference Manual

  • next
  • previous

Table Of Contents

  • F2PY Users Guide and Reference Manual
    • Introduction

Previous topic

Testing the numpy.i Typemaps

Next topic

Three ways to wrap - getting started

F2PY Users Guide and Reference Manual

Author: | Pearu Peterson
Contact: | pearu@cens.ioc.ee
Web site: | http://cens.ioc.ee/projects/f2py2e/
Date: | 2005/04/02 10:03:26

Introduction

The purpose of the F2PY –Fortran to Python interface generator– project is to provide a connection between Python and Fortran languages. F2PY is a Python package (with a command line tool f2py and a module f2py2e) that facilitates creating/building Python C/API extension modules that make it possible

  • to call Fortran 77/90/95 external subroutines and Fortran 90/95 module subroutines as well as C functions;
  • to access Fortran 77 COMMON blocks and Fortran 90/95 module data, including allocatable arrays

from Python. See F2PY web site for more information and installation instructions.

  • Three ways to wrap - getting started
    • The quick way
    • The smart way
    • The quick and smart way
  • Signature file
    • Python module block
    • Fortran/C routine signatures
    • Extensions
  • Using F2PY bindings in Python
    • Scalar arguments
    • String arguments
    • Array arguments
    • Call-back arguments
    • Common blocks
    • Fortran 90 module data
  • Using F2PY
    • Command f2py
    • Python module f2py2e
  • Using via numpy.distutils
  • Advanced F2PY usages
    • Adding self-written functions to F2PY generated modules
    • Modifying the dictionary of a F2PY generated module


Three ways to wrap - getting started

  • F2PY Users Guide and Reference Manual
  • next
  • previous

Table Of Contents

  • Three ways to wrap - getting started
    • The quick way
    • The smart way
    • The quick and smart way

Previous topic

F2PY Users Guide and Reference Manual

Next topic

Signature file

Three ways to wrap - getting started

Wrapping Fortran or C functions to Python using F2PY consists of the following steps:

  • Creating the so-called signature file that contains descriptions of wrappers to Fortran or C functions, also called as signatures of the functions. In the case of Fortran routines, F2PY can create initial signature file by scanning Fortran source codes and catching all relevant information needed to create wrapper functions.
  • Optionally, F2PY created signature files can be edited to optimize wrappers functions, make them “smarter” and more “Pythonic”.
  • F2PY reads a signature file and writes a Python C/API module containing Fortran/C/Python bindings.
  • F2PY compiles all sources and builds an extension module containing the wrappers. In building extension modules, F2PY uses numpy_distutils that supports a number of Fortran 77/90/95 compilers, including Gnu, Intel, Sun Fortre, SGI MIPSpro, Absoft, NAG, Compaq etc. compilers.

Depending on a particular situation, these steps can be carried out either by just in one command or step-by-step, some steps can be omitted or combined with others.

Below I’ll describe three typical approaches of using F2PY. The following example Fortran 77 code will be used for illustration:

C FILE: FIB1.F
      SUBROUTINE FIB(A,N)
C
C     CALCULATE FIRST N FIBONACCI NUMBERS
C
      INTEGER N
      REAL*8 A(N)
      DO I=1,N
         IF (I.EQ.1) THEN
            A(I) = 0.0D0
         ELSEIF (I.EQ.2) THEN
            A(I) = 1.0D0
         ELSE
            A(I) = A(I-1) + A(I-2)
         ENDIF
      ENDDO
      END
C END FILE FIB1.F

The quick way

The quickest way to wrap the Fortran subroutine FIB to Python is to run

f2py -c fib1.f -m fib1

This command builds (see -c flag, execute f2py without arguments to see the explanation of command line options) an extension module fib1.so (see -m flag) to the current directory. Now, in Python the Fortran subroutine FIB is accessible via fib1.fib:

>>> import numpy
>>> import fib1
>>> print fib1.fib.__doc__
fib - Function signature:
  fib(a,[n])
Required arguments:
  a : input rank-1 array('d') with bounds (n)
Optional arguments:
  n := len(a) input int

>>> a = numpy.zeros(8,'d')
>>> fib1.fib(a)
>>> print a
[  0.   1.   1.   2.   3.   5.   8.  13.]

Note

  • Note that F2PY found that the second argument n is the dimension of the first array argument a. Since by default all arguments are input-only arguments, F2PY concludes that n can be optional with the default value len(a).

  • One can use different values for optional n:

    >>> a1 = numpy.zeros(8,'d')
>>> fib1.fib(a1,6)
>>> print a1
[ 0.  1.  1.  2.  3.  5.  0.  0.]

    but an exception is raised when it is incompatible with the input array a:

    >>> fib1.fib(a,10)
fib:n=10
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
fib.error: (len(a)>=n) failed for 1st keyword n
>>>

    This demonstrates one of the useful features in F2PY, that it, F2PY implements basic compatibility checks between related arguments in order to avoid any unexpected crashes.

  • When a Numpy array, that is Fortran contiguous and has a dtype corresponding to presumed Fortran type, is used as an input array argument, then its C pointer is directly passed to Fortran.

    Otherwise F2PY makes a contiguous copy (with a proper dtype) of the input array and passes C pointer of the copy to Fortran subroutine. As a result, any possible changes to the (copy of) input array have no effect to the original argument, as demonstrated below:

    >>> a = numpy.ones(8,'i')
>>> fib1.fib(a)
>>> print a
[1 1 1 1 1 1 1 1]

    Clearly, this is not an expected behaviour. The fact that the above example worked with dtype=float is considered accidental.

    F2PY provides intent(inplace) attribute that would modify the attributes of an input array so that any changes made by Fortran routine will be effective also in input argument. For example, if one specifies intent(inplace) a (see below, how), then the example above would read:

    >>> a = numpy.ones(8,'i')
>>> fib1.fib(a)
>>> print a
[  0.   1.   1.   2.   3.   5.   8.  13.]

    However, the recommended way to get changes made by Fortran subroutine back to python is to use intent(out) attribute. It is more efficient and a cleaner solution.

  • The usage of fib1.fib in Python is very similar to using FIB in Fortran. However, using in situ output arguments in Python indicates a poor style as there is no safety mechanism in Python with respect to wrong argument types. When using Fortran or C, compilers naturally discover any type mismatches during compile time but in Python the types must be checked in runtime. So, using in situ output arguments in Python may cause difficult to find bugs, not to mention that the codes will be less readable when all required type checks are implemented.

Though the demonstrated way of wrapping Fortran routines to Python is very straightforward, it has several drawbacks (see the comments above). These drawbacks are due to the fact that there is no way that F2PY can determine what is the actual intention of one or the other argument, is it input or output argument, or both, or something else. So, F2PY conservatively assumes that all arguments are input arguments by default.

However, there are ways (see below) how to “teach” F2PY about the true intentions (among other things) of function arguments; and then F2PY is able to generate more Pythonic (more explicit, easier to use, and less error prone) wrappers to Fortran functions.

The smart way

Let’s apply the steps of wrapping Fortran functions to Python one by one.

  • First, we create a signature file from fib1.f by running

    f2py fib1.f -m fib2 -h fib1.pyf

    The signature file is saved to fib1.pyf (see -h flag) and its contents is shown below.

    !    -*- f90 -*-
python module fib2 ! in
    interface  ! in :fib2
        subroutine fib(a,n) ! in :fib2:fib1.f
            real*8 dimension(n) :: a
            integer optional,check(len(a)>=n),depend(a) :: n=len(a)
        end subroutine fib
    end interface
end python module fib2

! This file was auto-generated with f2py (version:2.28.198-1366).
! See http://cens.ioc.ee/projects/f2py2e/

  • Next, we’ll teach F2PY that the argument n is a input argument (use intent(in) attribute) and that the result, i.e. the contents of a after calling Fortran function FIB, should be returned to Python (use intent(out) attribute). In addition, an array a should be created dynamically using the size given by the input argument n (use depend(n) attribute to indicate dependence relation).

    The content of a modified version of fib1.pyf (saved as fib2.pyf) is as follows:

    !    -*- f90 -*-
python module fib2
    interface
        subroutine fib(a,n)
            real*8 dimension(n),intent(out),depend(n) :: a
            integer intent(in) :: n
        end subroutine fib
    end interface
end python module fib2

  • And finally, we build the extension module by running

    f2py -c fib2.pyf fib1.f

In Python:

>>> import fib2
>>> print fib2.fib.__doc__
fib - Function signature:
  a = fib(n)
Required arguments:
  n : input int
Return objects:
  a : rank-1 array('d') with bounds (n)

>>> print fib2.fib(8)
[  0.   1.   1.   2.   3.   5.   8.  13.]

Note

  • Clearly, the signature of fib2.fib now corresponds to the intention of Fortran subroutine FIB more closely: given the number n, fib2.fib returns the first n Fibonacci numbers as a Numpy array. Also, the new Python signature fib2.fib rules out any surprises that we experienced with fib1.fib.
  • Note that by default using single intent(out) also implies intent(hide). Argument that has intent(hide) attribute specified, will not be listed in the argument list of a wrapper function.

The quick and smart way

The “smart way” of wrapping Fortran functions, as explained above, is suitable for wrapping (e.g. third party) Fortran codes for which modifications to their source codes are not desirable nor even possible.

However, if editing Fortran codes is acceptable, then the generation of an intermediate signature file can be skipped in most cases. Namely, F2PY specific attributes can be inserted directly to Fortran source codes using the so-called F2PY directive. A F2PY directive defines special comment lines (starting with Cf2py, for example) which are ignored by Fortran compilers but F2PY interprets them as normal lines.

Here is shown a modified version of the example Fortran code, saved as fib3.f:

C FILE: FIB3.F
      SUBROUTINE FIB(A,N)
C
C     CALCULATE FIRST N FIBONACCI NUMBERS
C
      INTEGER N
      REAL*8 A(N)
Cf2py intent(in) n
Cf2py intent(out) a
Cf2py depend(n) a
      DO I=1,N
         IF (I.EQ.1) THEN
            A(I) = 0.0D0
         ELSEIF (I.EQ.2) THEN
            A(I) = 1.0D0
         ELSE
            A(I) = A(I-1) + A(I-2)
         ENDIF
      ENDDO
      END
C END FILE FIB3.F

Building the extension module can be now carried out in one command:

f2py -c -m fib3 fib3.f

Notice that the resulting wrapper to FIB is as “smart” as in previous case:

>>> import fib3
>>> print fib3.fib.__doc__
fib - Function signature:
  a = fib(n)
Required arguments:
  n : input int
Return objects:
  a : rank-1 array('d') with bounds (n)

>>> print fib3.fib(8)
[  0.   1.   1.   2.   3.   5.   8.  13.]


Signature file

  • F2PY Users Guide and Reference Manual
  • next
  • previous

Table Of Contents

  • Signature file
    • Python module block
    • Fortran/C routine signatures
      • Type declarations
      • Statements
      • Attributes
    • Extensions
      • F2PY directives
      • C expressions
      • Multiline blocks

Previous topic

Three ways to wrap - getting started

Next topic

Using F2PY bindings in Python

Signature file

The syntax specification for signature files (.pyf files) is borrowed from the Fortran 90/95 language specification. Almost all Fortran 90/95 standard constructs are understood, both in free and fixed format (recall that Fortran 77 is a subset of Fortran 90/95). F2PY introduces also some extensions to Fortran 90/95 language specification that help designing Fortran to Python interface, make it more “Pythonic”.

Signature files may contain arbitrary Fortran code (so that Fortran codes can be considered as signature files). F2PY silently ignores Fortran constructs that are irrelevant for creating the interface. However, this includes also syntax errors. So, be careful not making ones;-).

In general, the contents of signature files is case-sensitive. When scanning Fortran codes and writing a signature file, F2PY lowers all cases automatically except in multiline blocks or when --no-lower option is used.

The syntax of signature files is overvied below.

Python module block

A signature file may contain one (recommended) or more python module blocks. python module block describes the contents of a Python/C extension module <modulename>module.c that F2PY generates.

Exception: if <modulename> contains a substring __user__, then the corresponding python module block describes the signatures of so-called call-back functions (see Call-back arguments).

A python module block has the following structure:

python module <modulename>
  [<usercode statement>]...
  [
  interface
    <usercode statement>
    <Fortran block data signatures>
    <Fortran/C routine signatures>
  end [interface]
  ]...
  [
  interface
    module <F90 modulename>
      [<F90 module data type declarations>]
      [<F90 module routine signatures>]
    end [module [<F90 modulename>]]
  end [interface]
  ]...
end [python module [<modulename>]]

Here brackets [] indicate a optional part, dots ... indicate one or more of a previous part. So, []... reads zero or more of a previous part.

Fortran/C routine signatures

The signature of a Fortran routine has the following structure:

[<typespec>] function | subroutine <routine name> \
              [ ( [<arguments>] ) ] [ result ( <entityname> ) ]
  [<argument/variable type declarations>]
  [<argument/variable attribute statements>]
  [<use statements>]
  [<common block statements>]
  [<other statements>]
end [ function | subroutine [<routine name>] ]

From a Fortran routine signature F2PY generates a Python/C extension function that has the following signature:

def <routine name>(<required arguments>[,<optional arguments>]):
     ...
     return <return variables>

The signature of a Fortran block data has the following structure:

block data [ <block data name> ]
  [<variable type declarations>]
  [<variable attribute statements>]
  [<use statements>]
  [<common block statements>]
  [<include statements>]
end [ block data [<block data name>] ]

Type declarations

The definition of the <argument/variable type declaration> part is

<typespec> [ [<attrspec>] :: ] <entitydecl>

where

<typespec> := byte | character [<charselector>]
           | complex [<kindselector>] | real [<kindselector>]
           | double complex | double precision
           | integer [<kindselector>] | logical [<kindselector>]

<charselector> := * <charlen>
               | ( [len=] <len> [ , [kind=] <kind>] )
               | ( kind= <kind> [ , len= <len> ] )
<kindselector> := * <intlen> | ( [kind=] <kind> )

<entitydecl> := <name> [ [ * <charlen> ] [ ( <arrayspec> ) ]
                      | [ ( <arrayspec> ) ] * <charlen> ]
                     | [ / <init_expr> / | = <init_expr> ] \
                       [ , <entitydecl> ]

and

  • <attrspec> is a comma separated list of attributes;
  • <arrayspec> is a comma separated list of dimension bounds;
  • <init_expr> is a C expression.
  • <intlen> may be negative integer for integer type specifications. In such cases integer*<negintlen> represents unsigned C integers.

If an argument has no <argument type declaration>, its type is determined by applying implicit rules to its name.

Statements

Attribute statements:
The <argument/variable attribute statement> is <argument/variable type declaration> without <typespec>. In addition, in an attribute statement one cannot use other attributes, also <entitydecl> can be only a list of names.
Use statements:

The definition of the <use statement> part is

use <modulename> [ , <rename_list> | , ONLY : <only_list> ]

where

<rename_list> := <local_name> => <use_name> [ , <rename_list> ]

Currently F2PY uses use statement only for linking call-back modules and external arguments (call-back functions), see Call-back arguments.

Common block statements:

The definition of the <common block statement> part is

common / <common name> / <shortentitydecl>

where

<shortentitydecl> := <name> [ ( <arrayspec> ) ] [ , <shortentitydecl> ]

One python module block should not contain two or more common blocks with the same name. Otherwise, the latter ones are ignored. The types of variables in <shortentitydecl> are defined using <argument type declarations>. Note that the corresponding <argument type declarations> may contain array specifications; then you don’t need to specify these in <shortentitydecl>.

Other statements:

The <other statement> part refers to any other Fortran language constructs that are not described above. F2PY ignores most of them except

  • call statements and function calls of external arguments (more details?);

  • include statements
    include '<filename>'
include "<filename>"

    If a file <filename> does not exist, the include statement is ignored. Otherwise, the file <filename> is included to a signature file. include statements can be used in any part of a signature file, also outside the Fortran/C routine signature blocks.

  • implicit statements
    implicit none
implicit <list of implicit maps>

    where

    <implicit map> := <typespec> ( <list of letters or range of letters> )

    Implicit rules are used to determine the type specification of a variable (from the first-letter of its name) if the variable is not defined using <variable type declaration>. Default implicit rule is given by

    implicit real (a-h,o-z,$_), integer (i-m)
  • entry statements
    entry <entry name> [([<arguments>])]

    F2PY generates wrappers to all entry names using the signature of the routine block.

    Tip: entry statement can be used to describe the signature of an arbitrary routine allowing F2PY to generate a number of wrappers from only one routine block signature. There are few restrictions while doing this: fortranname cannot be used, callstatement and callprotoargument can be used only if they are valid for all entry routines, etc.

In addition, F2PY introduces the following statements:

  • threadsafe

    Use Py_BEGIN_ALLOW_THREADS .. Py_END_ALLOW_THREADS block around the call to Fortran/C function.

  • callstatement <C-expr|multi-line block>

    Replace F2PY generated call statement to Fortran/C function with <C-expr|multi-line block>. The wrapped Fortran/C function is available as (*f2py_func). To raise an exception, set f2py_success = 0 in <C-expr|multi-line block>.

  • callprotoargument <C-typespecs>

    When callstatement statement is used then F2PY may not generate proper prototypes for Fortran/C functions (because <C-expr> may contain any function calls and F2PY has no way to determine what should be the proper prototype). With this statement you can explicitly specify the arguments of the corresponding prototype:

    extern <return type> FUNC_F(<routine name>,<ROUTINE NAME>)(<callprotoargument>);
  • fortranname [<actual Fortran/C routine name>]

    You can use arbitrary <routine name> for a given Fortran/C function. Then you have to specify <actual Fortran/C routine name> with this statement.

    If fortranname statement is used without <actual Fortran/C routine name> then a dummy wrapper is generated.

  • usercode <multi-line block>

    When used inside python module block, then given C code will be inserted to generated C/API source just before wrapper function definitions. Here you can define arbitrary C functions to be used in initialization of optional arguments, for example. If usercode is used twice inside python module block then the second multiline block is inserted after the definition of external routines.

    When used inside <routine singature>, then given C code will be inserted to the corresponding wrapper function just after declaring variables but before any C statements. So, usercode follow-up can contain both declarations and C statements.

    When used inside the first interface block, then given C code will be inserted at the end of the initialization function of the extension module. Here you can modify extension modules dictionary. For example, for defining additional variables etc.

  • pymethoddef <multiline block>

    Multiline block will be inserted to the definition of module methods PyMethodDef-array. It must be a comma-separated list of C arrays (see Extending and Embedding Python documentation for details). pymethoddef statement can be used only inside python module block.

Attributes

The following attributes are used by F2PY:

optional

The corresponding argument is moved to the end of <optional arguments> list. A default value for an optional argument can be specified <init_expr>, see entitydecl definition. Note that the default value must be given as a valid C expression.

Note that whenever <init_expr> is used, optional attribute is set automatically by F2PY.

For an optional array argument, all its dimensions must be bounded.

required

The corresponding argument is considered as a required one. This is default. You need to specify required only if there is a need to disable automatic optional setting when <init_expr> is used.

If Python None object is used as an required argument, the argument is treated as optional. That is, in the case of array argument, the memory is allocated. And if <init_expr> is given, the corresponding initialization is carried out.

dimension(<arrayspec>)
The corresponding variable is considered as an array with given dimensions in <arrayspec>.
intent(<intentspec>)

This specifies the “intention” of the corresponding argument. <intentspec> is a comma separated list of the following keys:

  • in

    The argument is considered as an input-only argument. It means that the value of the argument is passed to Fortran/C function and that function is expected not to change the value of an argument.

  • inout

    The argument is considered as an input/output or in situ output argument. intent(inout) arguments can be only “contiguous” Numpy arrays with proper type and size. Here “contiguous” can be either in Fortran or C sense. The latter one coincides with the contiguous concept used in Numpy and is effective only if intent(c) is used. Fortran contiguity is assumed by default.

    Using intent(inout) is generally not recommended, use intent(in,out) instead. See also intent(inplace) attribute.

  • inplace

    The argument is considered as an input/output or in situ output argument. intent(inplace) arguments must be Numpy arrays with proper size. If the type of an array is not “proper” or the array is non-contiguous then the array will be changed in-place to fix the type and make it contiguous.

    Using intent(inplace) is generally not recommended either. For example, when slices have been taken from an intent(inplace) argument then after in-place changes, slices data pointers may point to unallocated memory area.

  • out

    The argument is considered as an return variable. It is appended to the <returned variables> list. Using intent(out) sets intent(hide) automatically, unless also intent(in) or intent(inout) were used.

    By default, returned multidimensional arrays are Fortran-contiguous. If intent(c) is used, then returned multidimensional arrays are C-contiguous.

  • hide

    The argument is removed from the list of required or optional arguments. Typically intent(hide) is used with intent(out) or when <init_expr> completely determines the value of the argument like in the following example:

    integer intent(hide),depend(a) :: n = len(a)
real intent(in),dimension(n) :: a
  • c

    The argument is treated as a C scalar or C array argument. In the case of a scalar argument, its value is passed to C function as a C scalar argument (recall that Fortran scalar arguments are actually C pointer arguments). In the case of an array argument, the wrapper function is assumed to treat multidimensional arrays as C-contiguous arrays.

    There is no need to use intent(c) for one-dimensional arrays, no matter if the wrapped function is either a Fortran or a C function. This is because the concepts of Fortran- and C contiguity overlap in one-dimensional cases.

    If intent(c) is used as an statement but without entity declaration list, then F2PY adds intent(c) attibute to all arguments.

    Also, when wrapping C functions, one must use intent(c) attribute for <routine name> in order to disable Fortran specific F_FUNC(..,..) macros.

  • cache

    The argument is treated as a junk of memory. No Fortran nor C contiguity checks are carried out. Using intent(cache) makes sense only for array arguments, also in connection with intent(hide) or optional attributes.

  • copy

    Ensure that the original contents of intent(in) argument is preserved. Typically used in connection with intent(in,out) attribute. F2PY creates an optional argument overwrite_<argument name> with the default value 0.

  • overwrite

    The original contents of the intent(in) argument may be altered by the Fortran/C function. F2PY creates an optional argument overwrite_<argument name> with the default value 1.

  • out=<new name>

    Replace the return name with <new name> in the __doc__ string of a wrapper function.

  • callback

    Construct an external function suitable for calling Python function from Fortran. intent(callback) must be specified before the corresponding external statement. If ‘argument’ is not in argument list then it will be added to Python wrapper but only initializing external function.

    Use intent(callback) in situations where a Fortran/C code assumes that a user implements a function with given prototype and links it to an executable. Don’t use intent(callback) if function appears in the argument list of a Fortran routine.

    With intent(hide) or optional attributes specified and using a wrapper function without specifying the callback argument in argument list then call-back function is looked in the namespace of F2PY generated extension module where it can be set as a module attribute by a user.

  • aux

    Define auxiliary C variable in F2PY generated wrapper function. Useful to save parameter values so that they can be accessed in initialization expression of other variables. Note that intent(aux) silently implies intent(c).

The following rules apply:

  • If no intent(in | inout | out | hide) is specified, intent(in) is assumed.
  • intent(in,inout) is intent(in).
  • intent(in,hide) or intent(inout,hide) is intent(hide).
  • intent(out) is intent(out,hide) unless intent(in) or intent(inout) is specified.
  • If intent(copy) or intent(overwrite) is used, then an additional optional argument is introduced with a name overwrite_<argument name> and a default value 0 or 1, respectively.
  • intent(inout,inplace) is intent(inplace).
  • intent(in,inplace) is intent(inplace).
  • intent(hide) disables optional and required.
check([<C-booleanexpr>])

Perform consistency check of arguments by evaluating <C-booleanexpr>; if <C-booleanexpr> returns 0, an exception is raised.

If check(..) is not used then F2PY generates few standard checks (e.g. in a case of an array argument, check for the proper shape and size) automatically. Use check() to disable checks generated by F2PY.

depend([<names>])

This declares that the corresponding argument depends on the values of variables in the list <names>. For example, <init_expr> may use the values of other arguments. Using information given by depend(..) attributes, F2PY ensures that arguments are initialized in a proper order. If depend(..) attribute is not used then F2PY determines dependence relations automatically. Use depend() to disable dependence relations generated by F2PY.

When you edit dependence relations that were initially generated by F2PY, be careful not to break the dependence relations of other relevant variables. Another thing to watch out is cyclic dependencies. F2PY is able to detect cyclic dependencies when constructing wrappers and it complains if any are found.

allocatable
The corresponding variable is Fortran 90 allocatable array defined as Fortran 90 module data.
external

The corresponding argument is a function provided by user. The signature of this so-called call-back function can be defined

  • in __user__ module block,
  • or by demonstrative (or real, if the signature file is a real Fortran code) call in the <other statements> block.

For example, F2PY generates from

external cb_sub, cb_fun
integer n
real a(n),r
call cb_sub(a,n)
r = cb_fun(4)

the following call-back signatures:

subroutine cb_sub(a,n)
    real dimension(n) :: a
    integer optional,check(len(a)>=n),depend(a) :: n=len(a)
end subroutine cb_sub
function cb_fun(e_4_e) result (r)
    integer :: e_4_e
    real :: r
end function cb_fun

The corresponding user-provided Python function are then:

def cb_sub(a,[n]):
    ...
    return
def cb_fun(e_4_e):
    ...
    return r

See also intent(callback) attribute.

parameter
The corresponding variable is a parameter and it must have a fixed value. F2PY replaces all parameter occurrences by their corresponding values.

Extensions

F2PY directives

The so-called F2PY directives allow using F2PY signature file constructs also in Fortran 77/90 source codes. With this feature you can skip (almost) completely intermediate signature file generations and apply F2PY directly to Fortran source codes.

F2PY directive has the following form:

<comment char>f2py ...

where allowed comment characters for fixed and free format Fortran codes are cC*!# and !, respectively. Everything that follows <comment char>f2py is ignored by a compiler but read by F2PY as a normal Fortran, non-comment line:

When F2PY finds a line with F2PY directive, the directive is first replaced by 5 spaces and then the line is reread.

For fixed format Fortran codes, <comment char> must be at the first column of a file, of course. For free format Fortran codes, F2PY directives can appear anywhere in a file.

C expressions

C expressions are used in the following parts of signature files:

  • <init_expr> of variable initialization;
  • <C-booleanexpr> of the check attribute;
  • <arrayspec> of the ``dimension attribute;
  • callstatement statement, here also a C multiline block can be used.

A C expression may contain:

  • standard C constructs;

  • functions from math.h and Python.h;

  • variables from the argument list, presumably initialized before according to given dependence relations;

  • the following CPP macros:

    rank(<name>)

    Returns the rank of an array <name>.

    shape(<name>,<n>)

    Returns the <n>-th dimension of an array <name>.

    len(<name>)

    Returns the lenght of an array <name>.

    size(<name>)

    Returns the size of an array <name>.

    slen(<name>)

    Returns the length of a string <name>.

For initializing an array <array name>, F2PY generates a loop over all indices and dimensions that executes the following pseudo-statement:

<array name>(_i[0],_i[1],...) = <init_expr>;

where _i[<i>] refers to the <i>-th index value and that runs from 0 to shape(<array name>,<i>)-1.

For example, a function myrange(n) generated from the following signature

subroutine myrange(a,n)
  fortranname        ! myrange is a dummy wrapper
  integer intent(in) :: n
  real*8 intent(c,out),dimension(n),depend(n) :: a = _i[0]
end subroutine myrange

is equivalent to numpy.arange(n,dtype=float).

Warning

F2PY may lower cases also in C expressions when scanning Fortran codes (see --[no]-lower option).

Multiline blocks

A multiline block starts with ''' (triple single-quotes) and ends with ''' in some strictly subsequent line. Multiline blocks can be used only within .pyf files. The contents of a multiline block can be arbitrary (except that it cannot contain ''') and no transformations (e.g. lowering cases) are applied to it.

Currently, multiline blocks can be used in the following constructs:

  • as a C expression of the callstatement statement;
  • as a C type specification of the callprotoargument statement;
  • as a C code block of the usercode statement;
  • as a list of C arrays of the pymethoddef statement;
  • as documentation string.


Using F2PY bindings in Python

  • F2PY Users Guide and Reference Manual
  • next
  • previous

Table Of Contents

  • Using F2PY bindings in Python
    • Scalar arguments
    • String arguments
    • Array arguments
    • Call-back arguments
      • Resolving arguments to call-back functions
    • Common blocks
    • Fortran 90 module data
      • Allocatable arrays

Previous topic

Signature file

Next topic

Using F2PY

Using F2PY bindings in Python

All wrappers for Fortran/C routines, common blocks, or for Fortran 90 module data generated by F2PY are exposed to Python as fortran type objects. Routine wrappers are callable fortran type objects while wrappers to Fortran data have attributes referring to data objects.

All fortran type object have attribute _cpointer that contains CObject referring to the C pointer of the corresponding Fortran/C function or variable in C level. Such CObjects can be used as an callback argument of F2PY generated functions to bypass Python C/API layer of calling Python functions from Fortran or C when the computational part of such functions is implemented in C or Fortran and wrapped with F2PY (or any other tool capable of providing CObject of a function).

Consider a Fortran 77 file ftype.f:

C FILE: FTYPE.F
      SUBROUTINE FOO(N)
      INTEGER N
Cf2py integer optional,intent(in) :: n = 13
      REAL A,X
      COMMON /DATA/ A,X(3)
      PRINT*, "IN FOO: N=",N," A=",A," X=[",X(1),X(2),X(3),"]"
      END
C END OF FTYPE.F

and build a wrapper using f2py -c ftype.f -m ftype.

In Python:

>>> import ftype
>>> print ftype.__doc__
This module 'ftype' is auto-generated with f2py (version:2.28.198-1366).
Functions:
  foo(n=13)
COMMON blocks:
  /data/ a,x(3)
.
>>> type(ftype.foo),type(ftype.data)
(<type 'fortran'>, <type 'fortran'>)
>>> ftype.foo()
 IN FOO: N= 13 A=  0. X=[  0.  0.  0.]
>>> ftype.data.a = 3
>>> ftype.data.x = [1,2,3]
>>> ftype.foo()
 IN FOO: N= 13 A=  3. X=[  1.  2.  3.]
>>> ftype.data.x[1] = 45
>>> ftype.foo(24)
 IN FOO: N= 24 A=  3. X=[  1.  45.  3.]
>>> ftype.data.x
array([  1.,  45.,   3.],'f')

Scalar arguments

In general, a scalar argument of a F2PY generated wrapper function can be ordinary Python scalar (integer, float, complex number) as well as an arbitrary sequence object (list, tuple, array, string) of scalars. In the latter case, the first element of the sequence object is passed to Fortran routine as a scalar argument.

Note that when type-casting is required and there is possible loss of information (e.g. when type-casting float to integer or complex to float), F2PY does not raise any exception. In complex to real type-casting only the real part of a complex number is used.

intent(inout) scalar arguments are assumed to be array objects in order to in situ changes to be effective. It is recommended to use arrays with proper type but also other types work.

Consider the following Fortran 77 code:

C FILE: SCALAR.F
      SUBROUTINE FOO(A,B)
      REAL*8 A, B
Cf2py intent(in) a
Cf2py intent(inout) b
      PRINT*, "    A=",A," B=",B
      PRINT*, "INCREMENT A AND B"
      A = A + 1D0
      B = B + 1D0
      PRINT*, "NEW A=",A," B=",B
      END
C END OF FILE SCALAR.F

and wrap it using f2py -c -m scalar scalar.f.

In Python:

>>> import scalar
>>> print scalar.foo.__doc__
foo - Function signature:
  foo(a,b)
Required arguments:
  a : input float
  b : in/output rank-0 array(float,'d')

>>> scalar.foo(2,3)
     A=  2. B=  3.
 INCREMENT A AND B
 NEW A=  3. B=  4.
>>> import numpy
>>> a=numpy.array(2)   # these are integer rank-0 arrays
>>> b=numpy.array(3)
>>> scalar.foo(a,b)
     A=  2. B=  3.
 INCREMENT A AND B
 NEW A=  3. B=  4.
>>> print a,b            # note that only b is changed in situ
2 4

String arguments

F2PY generated wrapper functions accept (almost) any Python object as a string argument, str is applied for non-string objects. Exceptions are Numpy arrays that must have type code 'c' or '1' when used as string arguments.

A string can have arbitrary length when using it as a string argument to F2PY generated wrapper function. If the length is greater than expected, the string is truncated. If the length is smaller that expected, additional memory is allocated and filled with \0.

Because Python strings are immutable, an intent(inout) argument expects an array version of a string in order to in situ changes to be effective.

Consider the following Fortran 77 code:

C FILE: STRING.F
      SUBROUTINE FOO(A,B,C,D)
      CHARACTER*5 A, B
      CHARACTER*(*) C,D
Cf2py intent(in) a,c
Cf2py intent(inout) b,d
      PRINT*, "A=",A
      PRINT*, "B=",B
      PRINT*, "C=",C
      PRINT*, "D=",D
      PRINT*, "CHANGE A,B,C,D"
      A(1:1) = 'A'
      B(1:1) = 'B'
      C(1:1) = 'C'
      D(1:1) = 'D'
      PRINT*, "A=",A
      PRINT*, "B=",B
      PRINT*, "C=",C
      PRINT*, "D=",D
      END
C END OF FILE STRING.F

and wrap it using f2py -c -m mystring string.f.

Python session:

>>> import mystring
>>> print mystring.foo.__doc__
foo - Function signature:
  foo(a,b,c,d)
Required arguments:
  a : input string(len=5)
  b : in/output rank-0 array(string(len=5),'c')
  c : input string(len=-1)
  d : in/output rank-0 array(string(len=-1),'c')

>>> import numpy
>>> a=numpy.array('123')
>>> b=numpy.array('123')
>>> c=numpy.array('123')
>>> d=numpy.array('123')
>>> mystring.foo(a,b,c,d)
 A=123
 B=123
 C=123
 D=123
 CHANGE A,B,C,D
 A=A23
 B=B23
 C=C23
 D=D23
>>> a.tostring(),b.tostring(),c.tostring(),d.tostring()
('123', 'B23', '123', 'D23')

Array arguments

In general, array arguments of F2PY generated wrapper functions accept arbitrary sequences that can be transformed to Numpy array objects. An exception is intent(inout) array arguments that always must be proper-contiguous and have proper type, otherwise an exception is raised. Another exception is intent(inplace) array arguments that attributes will be changed in-situ if the argument has different type than expected (see intent(inplace) attribute for more information).

In general, if a Numpy array is proper-contiguous and has a proper type then it is directly passed to wrapped Fortran/C function. Otherwise, an element-wise copy of an input array is made and the copy, being proper-contiguous and with proper type, is used as an array argument.

There are two types of proper-contiguous Numpy arrays:

  • Fortran-contiguous arrays when data is stored column-wise, i.e. indexing of data as stored in memory starts from the lowest dimension;
  • C-contiguous or simply contiguous arrays when data is stored row-wise, i.e. indexing of data as stored in memory starts from the highest dimension.

For one-dimensional arrays these notions coincide.

For example, an 2x2 array A is Fortran-contiguous if its elements are stored in memory in the following order:

A[0,0] A[1,0] A[0,1] A[1,1]

and C-contiguous if the order is as follows:

A[0,0] A[0,1] A[1,0] A[1,1]

To test whether an array is C-contiguous, use .iscontiguous() method of Numpy arrays. To test for Fortran contiguity, all F2PY generated extension modules provide a function has_column_major_storage(<array>). This function is equivalent to <array>.flags.f_contiguous but more efficient.

Usually there is no need to worry about how the arrays are stored in memory and whether the wrapped functions, being either Fortran or C functions, assume one or another storage order. F2PY automatically ensures that wrapped functions get arguments with proper storage order; the corresponding algorithm is designed to make copies of arrays only when absolutely necessary. However, when dealing with very large multidimensional input arrays with sizes close to the size of the physical memory in your computer, then a care must be taken to use always proper-contiguous and proper type arguments.

To transform input arrays to column major storage order before passing them to Fortran routines, use a function as_column_major_storage(<array>) that is provided by all F2PY generated extension modules.

Consider Fortran 77 code:

C FILE: ARRAY.F
      SUBROUTINE FOO(A,N,M)
C
C     INCREMENT THE FIRST ROW AND DECREMENT THE FIRST COLUMN OF A
C
      INTEGER N,M,I,J
      REAL*8 A(N,M)
Cf2py intent(in,out,copy) a
Cf2py integer intent(hide),depend(a) :: n=shape(a,0), m=shape(a,1)
      DO J=1,M
         A(1,J) = A(1,J) + 1D0
      ENDDO
      DO I=1,N
         A(I,1) = A(I,1) - 1D0
      ENDDO
      END
C END OF FILE ARRAY.F

and wrap it using f2py -c -m arr array.f -DF2PY_REPORT_ON_ARRAY_COPY=1.

In Python:

>>> import arr
>>> from numpy import array
>>> print arr.foo.__doc__
foo - Function signature:
  a = foo(a,[overwrite_a])
Required arguments:
  a : input rank-2 array('d') with bounds (n,m)
Optional arguments:
  overwrite_a := 0 input int
Return objects:
  a : rank-2 array('d') with bounds (n,m)

>>> a=arr.foo([[1,2,3],
...            [4,5,6]])
copied an array using PyArray_CopyFromObject: size=6, elsize=8
>>> print a
[[ 1.  3.  4.]
 [ 3.  5.  6.]]
>>> a.iscontiguous(), arr.has_column_major_storage(a)
(0, 1)
>>> b=arr.foo(a)              # even if a is proper-contiguous
...                           # and has proper type, a copy is made
...                           # forced by intent(copy) attribute
...                           # to preserve its original contents
...
copied an array using copy_ND_array: size=6, elsize=8
>>> print a
[[ 1.  3.  4.]
 [ 3.  5.  6.]]
>>> print b
[[ 1.  4.  5.]
 [ 2.  5.  6.]]
>>> b=arr.foo(a,overwrite_a=1) # a is passed directly to Fortran
...                            # routine and its contents is discarded
...
>>> print a
[[ 1.  4.  5.]
 [ 2.  5.  6.]]
>>> print b
[[ 1.  4.  5.]
 [ 2.  5.  6.]]
>>> a is b                       # a and b are acctually the same objects
1
>>> print arr.foo([1,2,3])       # different rank arrays are allowed
copied an array using PyArray_CopyFromObject: size=3, elsize=8
[ 1.  1.  2.]
>>> print arr.foo([[[1],[2],[3]]])
copied an array using PyArray_CopyFromObject: size=3, elsize=8
[ [[ 1.]
  [ 3.]
  [ 4.]]]
>>>
>>> # Creating arrays with column major data storage order:
...
>>> s = arr.as_column_major_storage(array([[1,2,3],[4,5,6]]))
copied an array using copy_ND_array: size=6, elsize=4
>>> arr.has_column_major_storage(s)
1
>>> print s
[[1 2 3]
 [4 5 6]]
>>> s2 = arr.as_column_major_storage(s)
>>> s2 is s    # an array with column major storage order
               # is returned immediately
1

Call-back arguments

F2PY supports calling Python functions from Fortran or C codes.

Consider the following Fortran 77 code:

C FILE: CALLBACK.F
      SUBROUTINE FOO(FUN,R)
      EXTERNAL FUN
      INTEGER I
      REAL*8 R
Cf2py intent(out) r
      R = 0D0
      DO I=-5,5
         R = R + FUN(I)
      ENDDO
      END
C END OF FILE CALLBACK.F

and wrap it using f2py -c -m callback callback.f.

In Python:

>>> import callback
>>> print callback.foo.__doc__
foo - Function signature:
  r = foo(fun,[fun_extra_args])
Required arguments:
  fun : call-back function
Optional arguments:
  fun_extra_args := () input tuple
Return objects:
  r : float
Call-back functions:
  def fun(i): return r
  Required arguments:
    i : input int
  Return objects:
    r : float

>>> def f(i): return i*i
...
>>> print callback.foo(f)
110.0
>>> print callback.foo(lambda i:1)
11.0

In the above example F2PY was able to guess accurately the signature of a call-back function. However, sometimes F2PY cannot establish the signature as one would wish and then the signature of a call-back function must be modified in the signature file manually. Namely, signature files may contain special modules (the names of such modules contain a substring __user__) that collect various signatures of call-back functions. Callback arguments in routine signatures have attribute external (see also intent(callback) attribute). To relate a callback argument and its signature in __user__ module block, use use statement as illustrated below. The same signature of a callback argument can be referred in different routine signatures.

We use the same Fortran 77 code as in previous example but now we’ll pretend that F2PY was not able to guess the signatures of call-back arguments correctly. First, we create an initial signature file callback2.pyf using F2PY:

f2py -m callback2 -h callback2.pyf callback.f

Then modify it as follows

!    -*- f90 -*-
python module __user__routines
    interface
        function fun(i) result (r)
            integer :: i
            real*8 :: r
        end function fun
    end interface
end python module __user__routines

python module callback2
    interface
        subroutine foo(f,r)
            use __user__routines, f=>fun
            external f
            real*8 intent(out) :: r
        end subroutine foo
    end interface
end python module callback2

Finally, build the extension module using f2py -c callback2.pyf callback.f.

An example Python session would be identical to the previous example except that argument names would differ.

Sometimes a Fortran package may require that users provide routines that the package will use. F2PY can construct an interface to such routines so that Python functions could be called from Fortran.

Consider the following `Fortran 77 subroutine`__ that takes an array and applies a function func to its elements.

      subroutine calculate(x,n)
cf2py intent(callback) func
      external func
c     The following lines define the signature of func for F2PY:
cf2py real*8 y
cf2py y = func(y)
c
cf2py intent(in,out,copy) x
      integer n,i
      real*8 x(n)
      do i=1,n
         x(i) = func(x(i))
      end do
      end

It is expected that function func has been defined externally. In order to use a Python function as func, it must have an attribute intent(callback) (it must be specified before the external statement).

Finally, build an extension module using f2py -c -m foo calculate.f

In Python:

>>> import foo
>>> foo.calculate(range(5), lambda x: x*x)
array([  0.,   1.,   4.,   9.,  16.])
>>> import math
>>> foo.calculate(range(5), math.exp)
array([  1.        ,   2.71828175,   7.38905621,  20.08553696,  54.59814835])

The function is included as an argument to the python function call to the Fortran subroutine even though it was not in the Fortran subroutine argument list. The “external” refers to the C function generated by f2py, not the python function itself. The python function must be supplied to the C function.

The callback function may also be explicitly set in the module. Then it is not necessary to pass the function in the argument list to the Fortran function. This may be desired if the Fortran function calling the python callback function is itself called by another Fortran function.

Consider the following Fortran 77 subroutine:

      subroutine f1()
         print *, "in f1, calling f2 twice.."
         call f2()
         call f2()
         return
      end

      subroutine f2()
cf2py    intent(callback, hide) fpy
         external fpy
         print *, "in f2, calling f2py.."
         call fpy()
         return
      end

and wrap it using f2py -c -m pfromf extcallback.f.

In Python:

>>> import pfromf
>>> pfromf.f2()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
pfromf.error: Callback fpy not defined (as an argument or module pfromf attribute).

>>> def f(): print "python f"
...
>>> pfromf.fpy = f
>>> pfromf.f2()
 in f2, calling f2py..
python f
>>> pfromf.f1()
 in f1, calling f2 twice..
 in f2, calling f2py..
python f
 in f2, calling f2py..
python f
>>>

Resolving arguments to call-back functions

F2PY generated interface is very flexible with respect to call-back arguments. For each call-back argument an additional optional argument <name>_extra_args is introduced by F2PY. This argument can be used to pass extra arguments to user provided call-back arguments.

If a F2PY generated wrapper function expects the following call-back argument:

def fun(a_1,...,a_n):
   ...
   return x_1,...,x_k

but the following Python function

def gun(b_1,...,b_m):
   ...
   return y_1,...,y_l

is provided by an user, and in addition,

fun_extra_args = (e_1,...,e_p)

is used, then the following rules are applied when a Fortran or C function calls the call-back argument gun:

  • If p == 0 then gun(a_1, ..., a_q) is called, here q = min(m, n).
  • If n + p <= m then gun(a_1, ..., a_n, e_1, ..., e_p) is called.
  • If p <= m < n + p then gun(a_1, ..., a_q, e_1, ..., e_p) is called, here q=m-p.
  • If p > m then gun(e_1, ..., e_m) is called.
  • If n + p is less than the number of required arguments to gun then an exception is raised.

The function gun may return any number of objects as a tuple. Then following rules are applied:

  • If k < l, then y_{k + 1}, ..., y_l are ignored.
  • If k > l, then only x_1, ..., x_l are set.

Common blocks

F2PY generates wrappers to common blocks defined in a routine signature block. Common blocks are visible by all Fortran codes linked with the current extension module, but not to other extension modules (this restriction is due to how Python imports shared libraries). In Python, the F2PY wrappers to common blocks are fortran type objects that have (dynamic) attributes related to data members of common blocks. When accessed, these attributes return as Numpy array objects (multidimensional arrays are Fortran-contiguous) that directly link to data members in common blocks. Data members can be changed by direct assignment or by in-place changes to the corresponding array objects.

Consider the following Fortran 77 code:

C FILE: COMMON.F
      SUBROUTINE FOO
      INTEGER I,X
      REAL A
      COMMON /DATA/ I,X(4),A(2,3)
      PRINT*, "I=",I
      PRINT*, "X=[",X,"]"
      PRINT*, "A=["
      PRINT*, "[",A(1,1),",",A(1,2),",",A(1,3),"]"
      PRINT*, "[",A(2,1),",",A(2,2),",",A(2,3),"]"
      PRINT*, "]"
      END
C END OF COMMON.F

and wrap it using f2py -c -m common common.f.

In Python:

>>> import common
>>> print common.data.__doc__
i - 'i'-scalar
x - 'i'-array(4)
a - 'f'-array(2,3)

>>> common.data.i = 5
>>> common.data.x[1] = 2
>>> common.data.a = [[1,2,3],[4,5,6]]
>>> common.foo()
 I= 5
 X=[ 0 2 0 0]
 A=[
 [  1.,  2.,  3.]
 [  4.,  5.,  6.]
 ]
>>> common.data.a[1] = 45
>>> common.foo()
 I= 5
 X=[ 0 2 0 0]
 A=[
 [  1.,  2.,  3.]
 [  45.,  45.,  45.]
 ]
>>> common.data.a                 # a is Fortran-contiguous
array([[  1.,   2.,   3.],
       [ 45.,  45.,  45.]],'f')

Fortran 90 module data

The F2PY interface to Fortran 90 module data is similar to Fortran 77 common blocks.

Consider the following Fortran 90 code:

module mod
  integer i
  integer :: x(4)
  real, dimension(2,3) :: a
  real, allocatable, dimension(:,:) :: b
contains
  subroutine foo
    integer k
    print*, "i=",i
    print*, "x=[",x,"]"
    print*, "a=["
    print*, "[",a(1,1),",",a(1,2),",",a(1,3),"]"
    print*, "[",a(2,1),",",a(2,2),",",a(2,3),"]"
    print*, "]"
    print*, "Setting a(1,2)=a(1,2)+3"
    a(1,2) = a(1,2)+3
  end subroutine foo
end module mod

and wrap it using f2py -c -m moddata moddata.f90.

In Python:

>>> import moddata
>>> print moddata.mod.__doc__
i - 'i'-scalar
x - 'i'-array(4)
a - 'f'-array(2,3)
foo - Function signature:
  foo()

>>> moddata.mod.i = 5
>>> moddata.mod.x[:2] = [1,2]
>>> moddata.mod.a = [[1,2,3],[4,5,6]]
>>> moddata.mod.foo()
 i=           5
 x=[           1           2           0           0 ]
 a=[
 [   1.000000     ,   2.000000     ,   3.000000     ]
 [   4.000000     ,   5.000000     ,   6.000000     ]
 ]
 Setting a(1,2)=a(1,2)+3
>>> moddata.mod.a               # a is Fortran-contiguous
array([[ 1.,  5.,  3.],
       [ 4.,  5.,  6.]],'f')

Allocatable arrays

F2PY has basic support for Fortran 90 module allocatable arrays.

Consider the following Fortran 90 code:

module mod
  real, allocatable, dimension(:,:) :: b
contains
  subroutine foo
    integer k
    if (allocated(b)) then
       print*, "b=["
       do k = 1,size(b,1)
          print*, b(k,1:size(b,2))
       enddo
       print*, "]"
    else
       print*, "b is not allocated"
    endif
  end subroutine foo
end module mod

and wrap it using f2py -c -m allocarr allocarr.f90.

In Python:

>>> import allocarr
>>> print allocarr.mod.__doc__
b - 'f'-array(-1,-1), not allocated
foo - Function signature:
  foo()

>>> allocarr.mod.foo()
 b is not allocated
>>> allocarr.mod.b = [[1,2,3],[4,5,6]]         # allocate/initialize b
>>> allocarr.mod.foo()
 b=[
   1.000000       2.000000       3.000000
   4.000000       5.000000       6.000000
 ]
>>> allocarr.mod.b                             # b is Fortran-contiguous
array([[ 1.,  2.,  3.],
       [ 4.,  5.,  6.]],'f')
>>> allocarr.mod.b = [[1,2,3],[4,5,6],[7,8,9]] # reallocate/initialize b
>>> allocarr.mod.foo()
 b=[
   1.000000       2.000000       3.000000
   4.000000       5.000000       6.000000
   7.000000       8.000000       9.000000
 ]
>>> allocarr.mod.b = None                      # deallocate array
>>> allocarr.mod.foo()
 b is not allocated


Using F2PY

  • F2PY Users Guide and Reference Manual
  • next
  • previous

Table Of Contents

  • Using F2PY
    • Command f2py
    • Python module f2py2e

Previous topic

Using F2PY bindings in Python

Next topic

Using via numpy.distutils

Using F2PY

F2PY can be used either as a command line tool f2py or as a Python module f2py2e.

Command f2py

When used as a command line tool, f2py has three major modes, distinguished by the usage of -c and -h switches:

  1. To scan Fortran sources and generate a signature file, use

    f2py -h <filename.pyf> <options> <fortran files>   \
  [[ only: <fortran functions>  : ]                \
   [ skip: <fortran functions>  : ]]...            \
  [<fortran files> ...]

    Note that a Fortran source file can contain many routines, and not necessarily all routines are needed to be used from Python. So, you can either specify which routines should be wrapped (in only: .. : part) or which routines F2PY should ignored (in skip: .. : part).

    If <filename.pyf> is specified as stdout then signatures are send to standard output instead of a file.

    Among other options (see below), the following options can be used in this mode:

    --overwrite-signature

    Overwrite existing signature file.

  2. To construct an extension module, use

    f2py <options> <fortran files>          \
  [[ only: <fortran functions>  : ]     \
   [ skip: <fortran functions>  : ]]... \
  [<fortran files> ...]

    The constructed extension module is saved as <modulename>module.c to the current directory.

    Here <fortran files> may also contain signature files. Among other options (see below), the following options can be used in this mode:

    --debug-capi

    Add debugging hooks to the extension module. When using this extension module, various information about the wrapper is printed to standard output, for example, the values of variables, the steps taken, etc.

    -include'<includefile>'

    Add a CPP #include statement to the extension module source. <includefile> should be given in one of the following forms:

    "filename.ext"
<filename.ext>

    The include statement is inserted just before the wrapper functions. This feature enables using arbitrary C functions (defined in <includefile>) in F2PY generated wrappers.

    This option is deprecated. Use usercode statement to specify C code snippets directly in signature files

    --[no-]wrap-functions

    Create Fortran subroutine wrappers to Fortran functions. --wrap-functions is default because it ensures maximum portability and compiler independence.

    --include-paths <path1>:<path2>:..

    Search include files from given directories.

    --help-link [<list of resources names>]

    List system resources found by numpy_distutils/system_info.py. For example, try f2py --help-link lapack_opt.

  3. To build an extension module, use

    f2py -c <options> <fortran files>       \
  [[ only: <fortran functions>  : ]     \
   [ skip: <fortran functions>  : ]]... \
  [ <fortran/c source files> ] [ <.o, .a, .so files> ]

    If <fortran files> contains a signature file, then a source for an extension module is constructed, all Fortran and C sources are compiled, and finally all object and library files are linked to the extension module <modulename>.so which is saved into the current directory.

    If <fortran files> does not contain a signature file, then an extension module is constructed by scanning all Fortran source codes for routine signatures.

    Among other options (see below) and options described in previous mode, the following options can be used in this mode:

    --help-fcompiler

    List available Fortran compilers.

    --help-compiler [depreciated]

    List available Fortran compilers.

    --fcompiler=<Vendor>

    Specify Fortran compiler type by vendor.

    --f77exec=<path>

    Specify the path to F77 compiler

    --fcompiler-exec=<path> [depreciated]

    Specify the path to F77 compiler

    --f90exec=<path>

    Specify the path to F90 compiler

    --f90compiler-exec=<path> [depreciated]

    Specify the path to F90 compiler

    --f77flags=<string>

    Specify F77 compiler flags

    --f90flags=<string>

    Specify F90 compiler flags

    --opt=<string>

    Specify optimization flags

    --arch=<string>

    Specify architecture specific optimization flags

    --noopt

    Compile without optimization

    --noarch

    Compile without arch-dependent optimization

    --debug

    Compile with debugging information

    -l<libname>

    Use the library <libname> when linking.

    -D<macro>[=<defn=1>]

    Define macro <macro> as <defn>.

    -U<macro>

    Define macro <macro>

    -I<dir>

    Append directory <dir> to the list of directories searched for include files.

    -L<dir>

    Add directory <dir> to the list of directories to be searched for -l.

    link-<resource>

    Link extension module with <resource> as defined by numpy_distutils/system_info.py. E.g. to link with optimized LAPACK libraries (vecLib on MacOSX, ATLAS elsewhere), use --link-lapack_opt. See also --help-link switch.

    When building an extension module, a combination of the following macros may be required for non-gcc Fortran compilers:

    -DPREPEND_FORTRAN
-DNO_APPEND_FORTRAN
-DUPPERCASE_FORTRAN

    To test the performance of F2PY generated interfaces, use -DF2PY_REPORT_ATEXIT. Then a report of various timings is printed out at the exit of Python. This feature may not work on all platforms, currently only Linux platform is supported.

    To see whether F2PY generated interface performs copies of array arguments, use -DF2PY_REPORT_ON_ARRAY_COPY=<int>. When the size of an array argument is larger than <int>, a message about the coping is sent to stderr.

Other options:

-m <modulename>
Name of an extension module. Default is untitled. Don’t use this option if a signature file (*.pyf) is used.
--[no-]lower
Do [not] lower the cases in <fortran files>. By default, --lower is assumed with -h switch, and --no-lower without the -h switch.
--build-dir <dirname>
All F2PY generated files are created in <dirname>. Default is tempfile.mkdtemp().
--quiet
Run quietly.
--verbose
Run with extra verbosity.
-v
Print f2py version ID and exit.

Execute f2py without any options to get an up-to-date list of available options.

Python module f2py2e

Warning

The current Python interface to f2py2e module is not mature and may change in future depending on users needs.

The following functions are provided by the f2py2e module:

run_main(<list>)

Equivalent to running:

f2py <args>

where <args>=string.join(<list>,' '), but in Python. Unless -h is used, this function returns a dictionary containing information on generated modules and their dependencies on source files. For example, the command f2py -m scalar scalar.f can be executed from Python as follows

>>> import f2py2e
>>> r=f2py2e.run_main(['-m','scalar','docs/usersguide/scalar.f'])
Reading fortran codes...
        Reading file 'docs/usersguide/scalar.f'
Post-processing...
        Block: scalar
                        Block: FOO
Building modules...
        Building module "scalar"...
        Wrote C/API module "scalar" to file "./scalarmodule.c"
>>> print r
{'scalar': {'h': ['/home/users/pearu/src_cvs/f2py2e/src/fortranobject.h'],
         'csrc': ['./scalarmodule.c',
                  '/home/users/pearu/src_cvs/f2py2e/src/fortranobject.c']}}

You cannot build extension modules with this function, that is, using -c is not allowed. Use compile command instead, see below.

compile(source, modulename='untitled', extra_args='', verbose=1, source_fn=None)

Build extension module from Fortran 77 source string source. Return 0 if successful. Note that this function actually calls f2py -c .. from shell to ensure safety of the current Python process. For example,

>>> import f2py2e
>>> fsource = '''
...       subroutine foo
...       print*, "Hello world!"
...       end
... '''
>>> f2py2e.compile(fsource,modulename='hello',verbose=0)
0
>>> import hello
>>> hello.foo()
 Hello world!


Using via numpy.distutils

  • F2PY Users Guide and Reference Manual
  • next
  • previous

Previous topic

Using F2PY

Next topic

Advanced F2PY usages

Using via numpy.distutils

numpy.distutils is part of Numpy extending standard Python distutils to deal with Fortran sources and F2PY signature files, e.g. compile Fortran sources, call F2PY to construct extension modules, etc.

Example

Consider the following setup file:

from __future__ import division, absolute_import, print_function

from numpy.distutils.core import Extension

ext1 = Extension(name = 'scalar',
                 sources = ['scalar.f'])
ext2 = Extension(name = 'fib2',
                 sources = ['fib2.pyf', 'fib1.f'])

if __name__ == "__main__":
    from numpy.distutils.core import setup
    setup(name = 'f2py_example',
          description       = "F2PY Users Guide examples",
          author            = "Pearu Peterson",
          author_email      = "pearu@cens.ioc.ee",
          ext_modules = [ext1, ext2]
          )
# End of setup_example.py

Running

python setup_example.py build

will build two extension modules scalar and fib2 to the build directory.

numpy.distutils extends distutils with the following features:

  • Extension class argument sources may contain Fortran source files. In addition, the list sources may contain at most one F2PY signature file, and then the name of an Extension module must match with the <modulename> used in signature file. It is assumed that an F2PY signature file contains exactly one python module block.

    If sources does not contain a signature files, then F2PY is used to scan Fortran source files for routine signatures to construct the wrappers to Fortran codes.

    Additional options to F2PY process can be given using Extension class argument f2py_options.

  • The following new distutils commands are defined:

    build_src

    to construct Fortran wrapper extension modules, among many other things.

    config_fc

    to change Fortran compiler options

    as well as build_ext and build_clib commands are enhanced to support Fortran sources.

    Run

    python <setup.py file> config_fc build_src build_ext --help

    to see available options for these commands.

  • When building Python packages containing Fortran sources, then one can choose different Fortran compilers by using build_ext command option --fcompiler=<Vendor>. Here <Vendor> can be one of the following names:

    absoft sun mips intel intelv intele intelev nag compaq compaqv gnu vast pg hpux

    See numpy_distutils/fcompiler.py for up-to-date list of supported compilers or run

    f2py -c --help-fcompiler


Advanced F2PY usages

  • F2PY Users Guide and Reference Manual
  • next
  • previous

Table Of Contents

  • Advanced F2PY usages
    • Adding self-written functions to F2PY generated modules
    • Modifying the dictionary of a F2PY generated module

Previous topic

Using via numpy.distutils

Next topic

Contributing to Numpy

Advanced F2PY usages

Adding self-written functions to F2PY generated modules

Self-written Python C/API functions can be defined inside signature files using usercode and pymethoddef statements (they must be used inside the python module block). For example, the following signature file spam.pyf

!    -*- f90 -*-
python module spam
    usercode '''
  static char doc_spam_system[] = "Execute a shell command.";
  static PyObject *spam_system(PyObject *self, PyObject *args)
  {
    char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = system(command);
    return Py_BuildValue("i", sts);
  }
    '''
    pymethoddef '''
    {"system",  spam_system, METH_VARARGS, doc_spam_system},
    '''
end python module spam

wraps the C library function system():

f2py -c spam.pyf

In Python:

>>> import spam
>>> status = spam.system('whoami')
pearu
>> status = spam.system('blah')
sh: line 1: blah: command not found

Modifying the dictionary of a F2PY generated module

The following example illustrates how to add an user-defined variables to a F2PY generated extension module. Given the following signature file

!    -*- f90 -*-
python module var
  usercode '''
    int BAR = 5;
  '''
  interface
    usercode '''
      PyDict_SetItemString(d,"BAR",PyInt_FromLong(BAR));
    '''
  end interface
end python module

compile it as f2py -c var.pyf.

Notice that the second usercode statement must be defined inside an interface block and where the module dictionary is available through the variable d (see f2py var.pyf-generated varmodule.c for additional details).

In Python:

>>> import var
>>> var.BAR
5


Contributing to Numpy

  • next
  • previous

Previous topic

Advanced F2PY usages

Next topic

Working with NumPy source code

Contributing to Numpy

  • Working with NumPy source code
    • Introduction
      • Install git
    • Following the latest source
      • Get the local copy of the code
      • Updating the code
    • Git for development
      • Getting started with Git development
      • Git configuration
      • Development workflow
    • git resources
      • Tutorials and summaries
      • Advanced git workflow
      • Manual pages online

For core developers: see Development workflow.


Working with NumPy source code

  • Contributing to Numpy
  • next
  • previous

Previous topic

Contributing to Numpy

Next topic

Introduction

Working with NumPy source code

Contents:

  • Introduction
    • Install git
  • Following the latest source
    • Get the local copy of the code
    • Updating the code
  • Git for development
    • Getting started with Git development
    • Git configuration
    • Development workflow
  • git resources
    • Tutorials and summaries
    • Advanced git workflow
    • Manual pages online


Introduction

  • Contributing to Numpy
  • Working with NumPy source code
  • index
  • next
  • previous

Table Of Contents

  • Introduction
    • Install git
      • Overview
      • In detail

Previous topic

Working with NumPy source code

Next topic

Following the latest source

Introduction

These pages describe a git and github workflow for the NumPy project.

There are several different workflows here, for different ways of working with NumPy.

This is not a comprehensive git reference, it’s just a workflow for our own project. It’s tailored to the github hosting service. You may well find better or quicker ways of getting stuff done with git, but these should get you started.

For general resources for learning git see git resources.

Install git

Overview

Debian / Ubuntu | sudo apt-get install git-core
Fedora | sudo yum install git-core
Windows | Download and install msysGit
OS X | Use the git-osx-installer

In detail

See the git page for the most recent information.

Have a look at the github install help pages available from github help

There are good instructions here: http://book.git-scm.com/2_installing_git.html


Following the latest source

  • Contributing to Numpy
  • Working with NumPy source code
  • index
  • next
  • previous

Table Of Contents

  • Following the latest source
    • Get the local copy of the code
    • Updating the code

Previous topic

Introduction

Next topic

Git for development

Following the latest source

These are the instructions if you just want to follow the latest NumPy source, but you don’t need to do any development for now. If you do want to contribute a patch (excellent!) or do more extensive NumPy development, see Development workflow.

The steps are:

  • Install git
  • get local copy of the git repository from Github
  • update local copy from time to time

Get the local copy of the code

From the command line:

git clone git://github.com/numpy/numpy.git

You now have a copy of the code tree in the new numpy directory. If this doesn’t work you can try the alternative read-only url:

git clone https://github.com/numpy/numpy.git

Updating the code

From time to time you may want to pull down the latest code. Do this with:

cd numpy
git fetch
git merge --ff-only

The tree in numpy will now have the latest changes from the initial repository.


Git for development

  • Contributing to Numpy
  • Working with NumPy source code
  • index
  • next
  • previous

Previous topic

Following the latest source

Next topic

Getting started with Git development

Git for development

Contents:

  • Getting started with Git development
    • Basic Git setup
    • Making your own copy (fork) of NumPy
    • Set up your fork
  • Git configuration
    • Overview
    • In detail
  • Development workflow
    • Basic workflow
    • Additional things you might want to do


Getting started with Git development

  • Contributing to Numpy
  • Working with NumPy source code
  • Git for development
  • index
  • next
  • previous

Table Of Contents

  • Getting started with Git development
    • Basic Git setup
    • Making your own copy (fork) of NumPy
      • Set up and configure a github account
      • Create your own forked copy of NumPy
    • Set up your fork
      • Overview
      • In detail
        • Clone your fork
        • Linking your repository to the upstream repo

Previous topic

Git for development

Next topic

Git configuration

Getting started with Git development

This section and the next describe in detail how to set up git for working with the NumPy source code. If you have git already set up, skip to Development workflow.

Basic Git setup

  • Install git.

  • Introduce yourself to Git:

    git config --global user.email you@yourdomain.example.com
git config --global user.name "Your Name Comes Here"

Making your own copy (fork) of NumPy

You need to do this only once. The instructions here are very similar to the instructions at http://help.github.com/forking/ - please see that page for more detail. We’re repeating some of it here just to give the specifics for the NumPy project, and to suggest some default names.

Set up and configure a github account

If you don’t have a github account, go to the github page, and make one.

You then need to configure your account to allow write access - see the Generating SSH keys help on github help.

Create your own forked copy of NumPy

  1. Log into your github account.

  2. Go to the NumPy github home at NumPy github.

  3. Click on the fork button:

    After a short pause, you should find yourself at the home page for your own forked copy of NumPy.

Set up your fork

First you follow the instructions for Making your own copy (fork) of NumPy.

Overview

git clone git@github.com:your-user-name/numpy.git
cd numpy
git remote add upstream git://github.com/numpy/numpy.git

In detail

Clone your fork

  1. Clone your fork to the local computer with git clone git@github.com:your-user-name/numpy.git

  2. Investigate. Change directory to your new repo: cd numpy. Then git branch -a to show you all branches. You’ll get something like:

    * master
remotes/origin/master

    This tells you that you are currently on the master branch, and that you also have a remote connection to origin/master. What remote repository is remote/origin? Try git remote -v to see the URLs for the remote. They will point to your github fork.

    Now you want to connect to the upstream NumPy github repository, so you can merge in changes from trunk.

Linking your repository to the upstream repo

cd numpy
git remote add upstream git://github.com/numpy/numpy.git

upstream here is just the arbitrary name we’re using to refer to the main NumPy repository at NumPy github.

Note that we’ve used git:// for the URL rather than git@. The git:// URL is read only. This means we that we can’t accidentally (or deliberately) write to the upstream repo, and we are only going to use it to merge into our own code.

Just for your own satisfaction, show yourself that you now have a new ‘remote’, with git remote -v show, giving you something like:

upstream     git://github.com/numpy/numpy.git (fetch)
upstream     git://github.com/numpy/numpy.git (push)
origin       git@github.com:your-user-name/numpy.git (fetch)
origin       git@github.com:your-user-name/numpy.git (push)


Git configuration

  • Contributing to Numpy
  • Working with NumPy source code
  • Git for development
  • index
  • next
  • previous

Table Of Contents

  • Git configuration
    • Overview
    • In detail
      • user.name and user.email
      • Aliases
      • Editor
      • Merging

Previous topic

Getting started with Git development

Next topic

Development workflow

Git configuration

Overview

Your personal git configurations are saved in the .gitconfig file in your home directory. Here is an example .gitconfig file:

[user]
        name = Your Name
        email = you@yourdomain.example.com

[alias]
        ci = commit -a
        co = checkout
        st = status -a
        stat = status -a
        br = branch
        wdiff = diff --color-words

[core]
        editor = vim

[merge]
        summary = true

You can edit this file directly or you can use the git config --global command:

git config --global user.name "Your Name"
git config --global user.email you@yourdomain.example.com
git config --global alias.ci "commit -a"
git config --global alias.co checkout
git config --global alias.st "status -a"
git config --global alias.stat "status -a"
git config --global alias.br branch
git config --global alias.wdiff "diff --color-words"
git config --global core.editor vim
git config --global merge.summary true

To set up on another computer, you can copy your ~/.gitconfig file, or run the commands above.

In detail

user.name and user.email

It is good practice to tell git who you are, for labeling any changes you make to the code. The simplest way to do this is from the command line:

git config --global user.name "Your Name"
git config --global user.email you@yourdomain.example.com

This will write the settings into your git configuration file, which should now contain a user section with your name and email:

[user]
      name = Your Name
      email = you@yourdomain.example.com

Of course you’ll need to replace Your Name and you@yourdomain.example.com with your actual name and email address.

Aliases

You might well benefit from some aliases to common commands.

For example, you might well want to be able to shorten git checkout to git co. Or you may want to alias git diff --color-words (which gives a nicely formatted output of the diff) to git wdiff

The following git config --global commands:

git config --global alias.ci "commit -a"
git config --global alias.co checkout
git config --global alias.st "status -a"
git config --global alias.stat "status -a"
git config --global alias.br branch
git config --global alias.wdiff "diff --color-words"

will create an alias section in your .gitconfig file with contents like this:

[alias]
        ci = commit -a
        co = checkout
        st = status -a
        stat = status -a
        br = branch
        wdiff = diff --color-words

Editor

You may also want to make sure that your editor of choice is used

git config --global core.editor vim

Merging

To enforce summaries when doing merges (~/.gitconfig file again):

[merge]
   log = true

Or from the command line:

git config --global merge.log true


Development workflow

  • Contributing to Numpy
  • Working with NumPy source code
  • Git for development
  • index
  • next
  • previous

Table Of Contents

  • Development workflow
    • Basic workflow
      • Making a new feature branch
      • The editing workflow
        • Overview
        • In more detail
        • Writing the commit message
      • Rebasing on master
        • Recovering from mess-ups
      • Asking for your changes to be merged with the main repo
        • Asking for code review
        • Filing a pull request
      • Pushing changes to the main repo
    • Additional things you might want to do
      • Rewriting commit history
      • Deleting a branch on github
      • Several people sharing a single repository
      • Exploring your repository
      • Backporting

Previous topic

Git configuration

Next topic

git resources

Development workflow

You already have your own forked copy of the NumPy repository, by following Making your own copy (fork) of NumPy, Set up your fork, you have configured git by following Git configuration, and have linked the upstream repository as explained in Linking your repository to the upstream repo.

What is described below is a recommended workflow with Git.

Basic workflow

In short:

  1. Update your master branch if it’s not up to date. Then start a new feature branch for each set of edits that you do. See below.

    Avoid putting new commits in your master branch.

  2. Hack away! See below

  3. Avoid merging other branches into your feature branch while you are working.

    You can optionally rebase if really needed, see below.

  4. When finished:

    • Contributors: push your feature branch to your own Github repo, and ask for code review or make a pull request.

    • Core developers (if you want to push changes without further review):

      # First, either (i) rebase on upstream -- if you have only few commits
git fetch upstream
git rebase upstream/master

# or, (ii) merge to upstream -- if you have many related commits
git fetch upstream
git merge --no-ff upstream/master

# Recheck that what is there is sensible
git log --oneline --graph
git log -p upstream/master..

# Finally, push branch to upstream master
git push upstream my-new-feature:master

      See below.

Note

It’s usually a good idea to use the -n flag to git push to check first that you’re about to push the changes you want to the place you want.

This way of working helps to keep work well organized and the history as clear as possible.

Note

Do not use git pull — this avoids common mistakes if you are new to Git. Instead, always do git fetch followed by git rebase, git merge --ff-only or git merge --no-ff, depending on what you intend.

See also

See discussions on linux git workflow, and ipython git workflow.

Making a new feature branch

To update your master branch, use:

git fetch upstream
git merge upstream/master --ff-only

To create a new branch and check it out, use:

git checkout -b my-new-feature upstream/master

Generally, you will want to keep this branch also on your public github fork of NumPy. To do this, you git push this new branch up to your github repo. Generally (if you followed the instructions in these pages, and by default), git will have a link to your github repo, called origin. You push up to your own repo on github with:

git push origin my-new-feature

In git >= 1.7 you can ensure that the link is correctly set by using the --set-upstream option:

git push --set-upstream origin my-new-feature

From now on git will know that my-new-feature is related to the my-new-feature branch in your own github repo.

The editing workflow

Overview

# hack hack
git add my_new_file
git commit -am 'ENH: some message'

# push the branch to your own Github repo
git push

In more detail

  1. Make some changes

  2. See which files have changed with git status (see git status). You’ll see a listing like this one:

    # On branch my-new-feature
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#  modified:   README
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#  INSTALL
no changes added to commit (use "git add" and/or "git commit -a")

  3. Check what the actual changes are with git diff (git diff).

  4. Add any new files to version control git add new_file_name (see git add).

  5. To commit all modified files into the local copy of your repo,, do git commit -am 'A commit message'. Note the -am options to commit. The m flag just signals that you’re going to type a message on the command line. If you leave it out, an editor will open in which you can compose your commit message. For non-trivial commits this is often the better choice. The a flag - you can just take on faith - or see why the -a flag? - and the helpful use-case description in the tangled working copy problem. The section on commit messages below might also be useful.

  6. To push the changes up to your forked repo on github, do a git push (see git push).

Writing the commit message

Commit messages should be clear and follow a few basic rules. Example:

ENH: add functionality X to numpy.<submodule>.

The first line of the commit message starts with a capitalized acronym
(options listed below) indicating what type of commit this is.  Then a blank
line, then more text if needed.  Lines shouldn't be longer than 80
characters.  If the commit is related to a ticket, indicate that with
"See #3456", "See ticket 3456", "Closes #3456" or similar.

Describing the motivation for a change, the nature of a bug for bug fixes or some details on what an enhancement does are also good to include in a commit message. Messages should be understandable without looking at the code changes. A commit message like MAINT: fixed another one is an example of what not to do; the reader has to go look for context elsewhere.

Standard acronyms to start the commit message with are:

API: an (incompatible) API change
BLD: change related to building numpy
BUG: bug fix
DEP: deprecate something, or remove a deprecated object
DEV: development tool or utility
DOC: documentation
ENH: enhancement
MAINT: maintenance commit (refactoring, typos, etc.)
REV: revert an earlier commit
STY: style fix (whitespace, PEP8)
TST: addition or modification of tests
REL: related to releasing numpy

Rebasing on master

This updates your feature branch with changes from the upstream NumPy github repo. If you do not absolutely need to do this, try to avoid doing it, except perhaps when you are finished.

First, it can be useful to update your master branch:

# go to the master branch
git checkout master
# pull changes from github
git fetch upstream
# update the master branch
git rebase upstream/master
# push it to your Github repo
git push

Then, the feature branch:

# go to the feature branch
git checkout my-new-feature
# make a backup in case you mess up
git branch tmp my-new-feature
# rebase on master
git rebase master

If you have made changes to files that have changed also upstream, this may generate merge conflicts that you need to resolve. Finally, remove the backup branch once the rebase succeeded:

git branch -D tmp

Recovering from mess-ups

Sometimes, you mess up merges or rebases. Luckily, in Git it is relatively straightforward to recover from such mistakes.

If you mess up during a rebase:

git rebase --abort

If you notice you messed up after the rebase:

# reset branch back to the saved point
git reset --hard tmp

If you forgot to make a backup branch:

# look at the reflog of the branch
git reflog show my-feature-branch

8630830 my-feature-branch@{0}: commit: BUG: io: close file handles immediately
278dd2a my-feature-branch@{1}: rebase finished: refs/heads/my-feature-branch onto 11ee694744f2552d
26aa21a my-feature-branch@{2}: commit: BUG: lib: make seek_gzip_factory not leak gzip obj
...

# reset the branch to where it was before the botched rebase
git reset --hard my-feature-branch@{2}

If you didn’t actually mess up but there are merge conflicts, you need to resolve those. This can be one of the trickier things to get right. For a good description of how to do this, see http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts

Asking for your changes to be merged with the main repo

When you feel your work is finished, you can ask for code review, or directly file a pull request.

Asking for code review

  1. Go to your repo URL - e.g. http://github.com/your-user-name/numpy.

  2. Click on the Branch list button:

  3. Click on the Compare button for your feature branch - here my-new-feature:

  4. If asked, select the base and comparison branch names you want to compare. Usually these will be master and my-new-feature (where that is your feature branch name).

  5. At this point you should get a nice summary of the changes. Copy the URL for this, and post it to the NumPy mailing list, asking for review. The URL will look something like: http://github.com/your-user-name/numpy/compare/master...my-new-feature. There’s an example at http://github.com/matthew-brett/nipy/compare/master...find-install-data See: http://github.com/blog/612-introducing-github-compare-view for more detail.

The generated comparison, is between your feature branch my-new-feature, and the place in master from which you branched my-new-feature. In other words, you can keep updating master without interfering with the output from the comparison. More detail? Note the three dots in the URL above (master...my-new-feature) and see Two and three dots in difference specs.

Filing a pull request

When you are ready to ask for the merge of your code:

  1. Go to the URL of your forked repo, say http://github.com/your-user-name/numpy.git.

  2. Click on the ‘Pull request’ button:

    Enter a message; we suggest you select only NumPy as the recipient. The message will go to the NumPy core developers. Please feel free to add others from the list as you like.

Pushing changes to the main repo

When you have a set of “ready” changes in a feature branch ready for Numpy’s master or maintenance/1.5.x branches, you can push them to upstream as follows:

  1. First, merge or rebase on the target branch.

    1. Only a few commits: prefer rebasing:

      git fetch upstream
git rebase upstream/master

      See above.

    2. Many related commits: consider creating a merge commit:

      git fetch upstream
git merge --no-ff upstream/master

  2. Check that what you are going to push looks sensible:

    git log -p upstream/master..
git log --oneline --graph

  3. Push to upstream:

    git push upstream my-feature-branch:master

Note

Avoid using git pull here.

Additional things you might want to do

Rewriting commit history

Note

Do this only for your own feature branches.

There’s an embarrassing typo in a commit you made? Or perhaps the you made several false starts you would like the posterity not to see.

This can be done via interactive rebasing.

Suppose that the commit history looks like this:

git log --oneline
eadc391 Fix some remaining bugs
a815645 Modify it so that it works
2dec1ac Fix a few bugs + disable
13d7934 First implementation
6ad92e5 * masked is now an instance of a new object, MaskedConstant
29001ed Add pre-nep for a copule of structured_array_extensions.
...

and 6ad92e5 is the last commit in the master branch. Suppose we want to make the following changes:

  • Rewrite the commit message for 13d7934 to something more sensible.
  • Combine the commits 2dec1ac, a815645, eadc391 into a single one.

We do as follows:

# make a backup of the current state
git branch tmp HEAD
# interactive rebase
git rebase -i 6ad92e5

This will open an editor with the following text in it:

pick 13d7934 First implementation
pick 2dec1ac Fix a few bugs + disable
pick a815645 Modify it so that it works
pick eadc391 Fix some remaining bugs

# Rebase 6ad92e5..eadc391 onto 6ad92e5
#
# Commands:
#  p, pick = use commit
#  r, reword = use commit, but edit the commit message
#  e, edit = use commit, but stop for amending
#  s, squash = use commit, but meld into previous commit
#  f, fixup = like "squash", but discard this commit's log message
#
# If you remove a line here THAT COMMIT WILL BE LOST.
# However, if you remove everything, the rebase will be aborted.
#

To achieve what we want, we will make the following changes to it:

r 13d7934 First implementation
pick 2dec1ac Fix a few bugs + disable
f a815645 Modify it so that it works
f eadc391 Fix some remaining bugs

This means that (i) we want to edit the commit message for 13d7934, and (ii) collapse the last three commits into one. Now we save and quit the editor.

Git will then immediately bring up an editor for editing the commit message. After revising it, we get the output:

[detached HEAD 721fc64] FOO: First implementation
 2 files changed, 199 insertions(+), 66 deletions(-)
[detached HEAD 0f22701] Fix a few bugs + disable
 1 files changed, 79 insertions(+), 61 deletions(-)
Successfully rebased and updated refs/heads/my-feature-branch.

and the history looks now like this:

0f22701 Fix a few bugs + disable
721fc64 ENH: Sophisticated feature
6ad92e5 * masked is now an instance of a new object, MaskedConstant

If it went wrong, recovery is again possible as explained above.

Deleting a branch on github

git checkout master
# delete branch locally
git branch -D my-unwanted-branch
# delete branch on github
git push origin :my-unwanted-branch

(Note the colon : before test-branch. See also: http://github.com/guides/remove-a-remote-branch

Several people sharing a single repository

If you want to work on some stuff with other people, where you are all committing into the same repository, or even the same branch, then just share it via github.

First fork NumPy into your account, as from Making your own copy (fork) of NumPy.

Then, go to your forked repository github page, say http://github.com/your-user-name/numpy

Click on the ‘Admin’ button, and add anyone else to the repo as a collaborator:

Now all those people can do:

git clone git@githhub.com:your-user-name/numpy.git

Remember that links starting with git@ use the ssh protocol and are read-write; links starting with git:// are read-only.

Your collaborators can then commit directly into that repo with the usual:

git commit -am 'ENH - much better code'
git push origin master # pushes directly into your repo

Exploring your repository

To see a graphical representation of the repository branches and commits:

gitk --all

To see a linear list of commits for this branch:

git log

You can also look at the network graph visualizer for your github repo.

Backporting

Backporting is the process of copying new feature/fixes committed in numpy/master back to stable release branches. To do this you make a branch off the branch you are backporting to, cherry pick the commits you want from numpy/master, and then submit a pull request for the branch containing the backport.

  1. Assuming you already have a fork of NumPy on Github. We need to update it from upstream:

    # Add upstream.
git remote add upstream https://github.com/numpy/numpy.git

# Get the latest updates.
git fetch upstream

# Make sure you are on master.
git checkout master

# Apply the updates locally.
git rebase upstream/master

# Push the updated code to your github repo.
git push origin

  2. Next you need to make the branch you will work on. This needs to be based on the older version of NumPy (not master):

    # Make a new branch based on numpy/maintenance/1.8.x,
# backport-3324 is our new name for the branch.
git checkout -b backport-3324 upstream/maintenance/1.8.x

  3. Now you need to apply the changes from master to this branch using git cherry-pick:

    # This pull request included commits aa7a047 to c098283 (inclusive)
# so you use the .. syntax (for a range of commits), the ^ makes the
# range inclusive.
git cherry-pick aa7a047^..c098283
...
# Fix any conflicts, then if needed:
git cherry-pick --continue

  4. You might run into some conflicts cherry picking here. These are resolved the same way as merge/rebase conflicts. Except here you can use git blame to see the difference between master and the backported branch to make sure nothing gets screwed up.

  5. Push the new branch to your Github repository:

    git push -u origin backport-3324

  6. Finally make a pull request using Github. Make sure it is against the maintenance branch and not master, Github will usually suggest you make the pull request against master.


git resources

  • Contributing to Numpy
  • Working with NumPy source code
  • index
  • next
  • previous

Table Of Contents

  • git resources
    • Tutorials and summaries
    • Advanced git workflow
    • Manual pages online

Previous topic

Development workflow

Next topic

Numpy Enhancement Proposals

git resources

Tutorials and summaries

  • github help has an excellent series of how-to guides.
  • learn.github has an excellent series of tutorials
  • The pro git book is a good in-depth book on git.
  • A git cheat sheet is a page giving summaries of common commands.
  • The git user manual
  • The git tutorial
  • The git community book
  • git ready - a nice series of tutorials
  • git casts - video snippets giving git how-tos.
  • git magic - extended introduction with intermediate detail
  • The git parable is an easy read explaining the concepts behind git.
  • Our own git foundation expands on the git parable.
  • Fernando Perez’ git page - Fernando’s git page - many links and tips
  • A good but technical page on git concepts
  • git svn crash course: git for those of us used to subversion

Advanced git workflow

There are many ways of working with git; here are some posts on the rules of thumb that other projects have come up with:

  • Linus Torvalds on git management
  • Linus Torvalds on linux git workflow . Summary; use the git tools to make the history of your edits as clean as possible; merge from upstream edits as little as possible in branches where you are doing active development.

Manual pages online

You can get these on your own machine with (e.g) git help push or (same thing) git push --help, but, for convenience, here are the online manual pages for some common commands:

  • git add
  • git branch
  • git checkout
  • git clone
  • git commit
  • git config
  • git diff
  • git log
  • git pull
  • git push
  • git remote
  • git status


Numpy Enhancement Proposals

  • next
  • previous

Table Of Contents

  • Numpy Enhancement Proposals
    • Implemented NEPs
    • Other NEPs

Previous topic

git resources

Next topic

A Mechanism for Overriding Ufuncs

Numpy Enhancement Proposals

Numpy Enhancement Proposals (NEPs) describe proposed changes to Numpy. NEPs are modeled on Python Enhancement Proposals (PEPs), and are typically written up when large changes to Numpy are proposed.

This page provides an overview of all NEPs, making only a distinction between the ones that have been implemented and those that have not been implemented.

Implemented NEPs

  • A Mechanism for Overriding Ufuncs
  • Generalized Universal Functions
  • Optimizing Iterator/UFunc Performance
  • A Simple File Format for NumPy Arrays

Other NEPs

  • Missing Data Functionality in NumPy
  • Cleaning the math configuration of numpy.core
  • A proposal for adding groupby functionality to NumPy
  • A proposal to build numpy without warning with a big set of warning flags
  • Replacing Trac with a different bug tracker
  • Deferred UFunc Evaluation
  • Structured array extensions
  • A proposal for implementing some date/time types in NumPy
  • A (third) proposal for implementing some date/time types in NumPy


A Mechanism for Overriding Ufuncs

  • Numpy Enhancement Proposals
  • next
  • previous

Table Of Contents

  • A Mechanism for Overriding Ufuncs
    • Executive summary
    • Motivation
    • Proposed interface
      • In combination with Python’s binary operations
    • Demo

Previous topic

Numpy Enhancement Proposals

Next topic

Generalized Universal Functions

A Mechanism for Overriding Ufuncs

Author: | Blake Griffith
Contact: | blake.g@utexa.edu
Date: | 2013-07-10
Author: | Pauli Virtanen
Author: | Nathaniel Smith

Executive summary

NumPy’s universal functions (ufuncs) currently have some limited functionality for operating on user defined subclasses of ndarray using __array_prepare__ and __array_wrap__ [1], and there is little to no support for arbitrary objects. e.g. SciPy’s sparse matrices [2] [3].

Here we propose adding a mechanism to override ufuncs based on the ufunc checking each of it’s arguments for a __numpy_ufunc__ method. On discovery of __numpy_ufunc__ the ufunc will hand off the operation to the method.

This covers some of the same ground as Travis Oliphant’s proposal to retro-fit NumPy with multi-methods [4], which would solve the same problem. The mechanism here follows more closely the way Python enables classes to override __mul__ and other binary operations.

[1] http://docs.scipy.org/doc/numpy/user/basics.subclassing.html
[2] https://github.com/scipy/scipy/issues/2123
[3] https://github.com/scipy/scipy/issues/1569
[4] http://technicaldiscovery.blogspot.com/2013/07/thoughts-after-scipy-2013-and-specific.html

Motivation

The current machinery for dispatching Ufuncs is generally agreed to be insufficient. There have been lengthy discussions and other proposed solutions [5].

Using ufuncs with subclasses of ndarray is limited to __array_prepare__ and __array_wrap__ to prepare the arguments, but these don’t allow you to for example change the shape or the data of the arguments. Trying to ufunc things that don’t subclass ndarray is even more difficult, as the input arguments tend to be cast to object arrays, which ends up producing surprising results.

Take this example of ufuncs interoperability with sparse matrices.:

In [1]: import numpy as np
import scipy.sparse as sp

a = np.random.randint(5, size=(3,3))
b = np.random.randint(5, size=(3,3))

asp = sp.csr_matrix(a)
bsp = sp.csr_matrix(b)

In [2]: a, b
Out[2]:(array([[0, 4, 4],
               [1, 3, 2],
               [1, 3, 1]]),
        array([[0, 1, 0],
               [0, 0, 1],
               [4, 0, 1]]))

In [3]: np.multiply(a, b) # The right answer
Out[3]: array([[0, 4, 0],
               [0, 0, 2],
               [4, 0, 1]])

In [4]: np.multiply(asp, bsp).todense() # calls __mul__ which does matrix multi
Out[4]: matrix([[16,  0,  8],
                [ 8,  1,  5],
                [ 4,  1,  4]], dtype=int64)

In [5]: np.multiply(a, bsp) # Returns NotImplemented to user, bad!
Out[5]: NotImplemted

Returning NotImplemented to user should not happen. Moreover:

In [6]: np.multiply(asp, b)
Out[6]: array([[ <3x3 sparse matrix of type '<class 'numpy.int64'>'
                with 8 stored elements in Compressed Sparse Row format>,
                    <3x3 sparse matrix of type '<class 'numpy.int64'>'
                with 8 stored elements in Compressed Sparse Row format>,
                    <3x3 sparse matrix of type '<class 'numpy.int64'>'
                with 8 stored elements in Compressed Sparse Row format>],
                   [ <3x3 sparse matrix of type '<class 'numpy.int64'>'
                with 8 stored elements in Compressed Sparse Row format>,
                    <3x3 sparse matrix of type '<class 'numpy.int64'>'
                with 8 stored elements in Compressed Sparse Row format>,
                    <3x3 sparse matrix of type '<class 'numpy.int64'>'
                with 8 stored elements in Compressed Sparse Row format>],
                   [ <3x3 sparse matrix of type '<class 'numpy.int64'>'
                with 8 stored elements in Compressed Sparse Row format>,
                    <3x3 sparse matrix of type '<class 'numpy.int64'>'
                with 8 stored elements in Compressed Sparse Row format>,
                    <3x3 sparse matrix of type '<class 'numpy.int64'>'
                with 8 stored elements in Compressed Sparse Row format>]], dtype=object)

Here, it appears that the sparse matrix was converted to a object array scalar, which was then multiplied with all elements of the b array. However, this behavior is more confusing than useful, and having a TypeError would be preferable.

Adding the __numpy_ufunc__ functionality fixes this and would deprecate the other ufunc modifying functions.

[5] http://mail.scipy.org/pipermail/numpy-discussion/2011-June/056945.html

Proposed interface

Objects that want to override Ufuncs can define a __numpy_ufunc__ method. The method signature is:

def __numpy_ufunc__(self, ufunc, method, i, inputs, **kwargs)

Here:

  • ufunc is the ufunc object that was called.
  • method is a string indicating which Ufunc method was called (one of "__call__", "reduce", "reduceat", "accumulate", "outer", "inner").
  • i is the index of self in inputs.
  • inputs is a tuple of the input arguments to the ufunc
  • kwargs are the keyword arguments passed to the function. The out arguments are always contained in kwargs, how positional variables are passed is discussed below.

The ufunc’s arguments are first normalized into a tuple of input data (inputs), and dict of keyword arguments. If there are output arguments they are handeled as follows:

  • One positional output variable x is passed in the kwargs dict as out : x.
  • Multiple positional output variables x0, x1, ... are passed as a tuple in the kwargs dict as out : (x0, x1, ...).
  • Keyword output variables like out = x and out = (x0, x1, ...) are passed unchanged to the kwargs dict like out : x and out : (x0, x1, ...) respectively.
  • Combinations of positional and keyword output variables are not supported.

The function dispatch proceeds as follows:

  • If one of the input arguments implements __numpy_ufunc__ it is executed instead of the Ufunc.
  • If more than one of the input arguments implements __numpy_ufunc__, they are tried in the following order: subclasses before superclasses, otherwise left to right. The first __numpy_ufunc__ method returning something else than NotImplemented determines the return value of the Ufunc.
  • If all __numpy_ufunc__ methods of the input arguments return NotImplemented, a TypeError is raised.
  • If a __numpy_ufunc__ method raises an error, the error is propagated immediately.

If none of the input arguments has a __numpy_ufunc__ method, the execution falls back on the default ufunc behaviour.

In combination with Python’s binary operations

The __numpy_ufunc__ mechanism is fully independent of Python’s standard operator override mechanism, and the two do not interact directly.

They however have indirect interactions, because Numpy’s ndarray type implements its binary operations via Ufuncs. Effectively, we have:

class ndarray(object):
    ...
    def __mul__(self, other):
        return np.multiply(self, other)

Suppose now we have a second class:

class MyObject(object):
    def __numpy_ufunc__(self, *a, **kw):
        return "ufunc"
    def __mul__(self, other):
        return 1234
    def __rmul__(self, other):
        return 4321

In this case, standard Python override rules combined with the above discussion imply:

a = MyObject()
b = np.array([0])

a * b    # == 1234       OK
b * a    # == "ufunc"    surprising

This is not what would be naively expected, and is therefore somewhat undesirable behavior.

The reason why this occurs is: because MyObject is not an ndarray subclass, Python resolves the expression b * a by calling first b.__mul__. Since Numpy implements this via an Ufunc, the call is forwarded to __numpy_ufunc__ and not to __rmul__. Note that if MyObject is a subclass of ndarray, Python calls a.__rmul__ first. The issue is therefore that __numpy_ufunc__ implements “virtual subclassing” of ndarray behavior, without actual subclassing.

This issue can be resolved by a modification of the binary operation methods in Numpy:

class ndarray(object):
    ...
    def __mul__(self, other):
        if (not isinstance(other, self.__class__)
                and hasattr(other, '__numpy_ufunc__')
                and hasattr(other, '__rmul__')):
            return NotImplemented
        return np.multiply(self, other)

    def __imul__(self, other):
        if (other.__class__ is not self.__class__
                and hasattr(other, '__numpy_ufunc__')
                and hasattr(other, '__rmul__')):
            return NotImplemented
        return np.multiply(self, other, out=self)

b * a    # == 4321    OK

The rationale here is the following: since the user class explicitly defines both __numpy_ufunc__ and __rmul__, the implementor has very likely made sure that the __rmul__ method can process ndarrays. If not, the special case is simple to deal with (just call np.multiply).

The exclusion of subclasses of self can be made because Python itself calls the right-hand method first in this case. Moreover, it is desirable that ndarray subclasses are able to inherit the right-hand binary operation methods from ndarray.

The same priority shuffling needs to be done also for the in-place operations, so that MyObject.__rmul__ is prioritized over ndarray.__imul__.

Demo

A pull request[6]_ has been made including the changes proposed in this NEP. Here is a demo highlighting the functionality.:

In [1]: import numpy as np;

In [2]: a = np.array([1])

In [3]: class B():
   ...:     def __numpy_ufunc__(self, func, method, pos, inputs, **kwargs):
   ...:         return "B"
   ...:

In [4]: b = B()

In [5]: np.dot(a, b)
Out[5]: 'B'

In [6]: np.multiply(a, b)
Out[6]: 'B'

A simple __numpy_ufunc__ has been added to SciPy’s sparse matrices Currently this only handles np.dot and np.multiply because it was the two most common cases where users would attempt to use sparse matrices with ufuncs. The method is defined below:

def __numpy_ufunc__(self, func, method, pos, inputs, **kwargs):
    """Method for compatibility with NumPy's ufuncs and dot
    functions.
    """

    without_self = list(inputs)
    del without_self[pos]
    without_self = tuple(without_self)

    if func == np.multiply:
        return self.multiply(*without_self)

    elif func == np.dot:
        if pos == 0:
            return self.__mul__(inputs[1])
        if pos == 1:
            return self.__rmul__(inputs[0])
    else:
        return NotImplemented

So we now get the expected behavior when using ufuncs with sparse matrices.:

In [1]: import numpy as np; import scipy.sparse as sp

In [2]: a = np.random.randint(3, size=(3,3))

In [3]: b = np.random.randint(3, size=(3,3))

In [4]: asp = sp.csr_matrix(a); bsp = sp.csr_matrix(b)

In [5]: np.dot(a,b)
Out[5]:
array([[2, 4, 8],
       [2, 4, 8],
        [2, 2, 3]])

In [6]: np.dot(asp,b)
Out[6]:
array([[2, 4, 8],
       [2, 4, 8],
       [2, 2, 3]], dtype=int64)

In [7]: np.dot(asp, bsp).A
Out[7]:
array([[2, 4, 8],
       [2, 4, 8],
       [2, 2, 3]], dtype=int64)


Generalized Universal Functions

  • Numpy Enhancement Proposals
  • next
  • previous

Table Of Contents

  • Generalized Universal Functions
    • Definitions
    • Details of Signature
    • C-API for implementing Elementary Functions

Previous topic

A Mechanism for Overriding Ufuncs

Next topic

Optimizing Iterator/UFunc Performance

Generalized Universal Functions

There is a general need for looping over not only functions on scalars but also over functions on vectors (or arrays), as explained on http://scipy.org/scipy/numpy/wiki/GeneralLoopingFunctions. We propose to realize this concept by generalizing the universal functions (ufuncs), and provide a C implementation that adds ~500 lines to the numpy code base. In current (specialized) ufuncs, the elementary function is limited to element-by-element operations, whereas the generalized version supports “sub-array” by “sub-array” operations. The Perl vector library PDL provides a similar functionality and its terms are re-used in the following.

Each generalized ufunc has information associated with it that states what the “core” dimensionality of the inputs is, as well as the corresponding dimensionality of the outputs (the element-wise ufuncs have zero core dimensions). The list of the core dimensions for all arguments is called the “signature” of a ufunc. For example, the ufunc numpy.add has signature (),()->() defining two scalar inputs and one scalar output.

Another example is (see the GeneralLoopingFunctions page) the function inner1d(a,b) with a signature of (i),(i)->(). This applies the inner product along the last axis of each input, but keeps the remaining indices intact. For example, where a is of shape (3,5,N) and b is of shape (5,N), this will return an output of shape (3,5). The underlying elementary function is called 3*5 times. In the signature, we specify one core dimension (i) for each input and zero core dimensions () for the output, since it takes two 1-d arrays and returns a scalar. By using the same name i, we specify that the two corresponding dimensions should be of the same size (or one of them is of size 1 and will be broadcasted).

The dimensions beyond the core dimensions are called “loop” dimensions. In the above example, this corresponds to (3,5).

The usual numpy “broadcasting” rules apply, where the signature determines how the dimensions of each input/output object are split into core and loop dimensions:

  1. While an input array has a smaller dimensionality than the corresponding number of core dimensions, 1’s are pre-pended to its shape.
  2. The core dimensions are removed from all inputs and the remaining dimensions are broadcasted; defining the loop dimensions.
  3. The output is given by the loop dimensions plus the output core dimensions.

Definitions

Elementary Function
Each ufunc consists of an elementary function that performs the most basic operation on the smallest portion of array arguments (e.g. adding two numbers is the most basic operation in adding two arrays). The ufunc applies the elementary function multiple times on different parts of the arrays. The input/output of elementary functions can be vectors; e.g., the elementary function of inner1d takes two vectors as input.
Signature
A signature is a string describing the input/output dimensions of the elementary function of a ufunc. See section below for more details.
Core Dimension
The dimensionality of each input/output of an elementary function is defined by its core dimensions (zero core dimensions correspond to a scalar input/output). The core dimensions are mapped to the last dimensions of the input/output arrays.
Dimension Name
A dimension name represents a core dimension in the signature. Different dimensions may share a name, indicating that they are of the same size (or are broadcastable).
Dimension Index
A dimension index is an integer representing a dimension name. It enumerates the dimension names according to the order of the first occurrence of each name in the signature.

Details of Signature

The signature defines “core” dimensionality of input and output variables, and thereby also defines the contraction of the dimensions. The signature is represented by a string of the following format:

  • Core dimensions of each input or output array are represented by a list of dimension names in parentheses, (i_1,...,i_N); a scalar input/output is denoted by (). Instead of i_1, i_2, etc, one can use any valid Python variable name.
  • Dimension lists for different arguments are separated by ",". Input/output arguments are separated by "->".
  • If one uses the same dimension name in multiple locations, this enforces the same size (or broadcastable size) of the corresponding dimensions.

The formal syntax of signatures is as follows:

<Signature>            ::= <Input arguments> "->" <Output arguments>
<Input arguments>      ::= <Argument list>
<Output arguments>     ::= <Argument list>
<Argument list>        ::= nil | <Argument> | <Argument> "," <Argument list>
<Argument>             ::= "(" <Core dimension list> ")"
<Core dimension list>  ::= nil | <Dimension name> |
                           <Dimension name> "," <Core dimension list>
<Dimension name>       ::= valid Python variable name

Notes:

  1. All quotes are for clarity.
  2. Core dimensions that share the same name must be broadcastable, as the two i in our example above. Each dimension name typically corresponding to one level of looping in the elementary function’s implementation.
  3. White spaces are ignored.

Here are some examples of signatures:

add | (),()->() |
inner1d | (i),(i)->() |
sum1d | (i)->() |
dot2d | (m,n),(n,p)->(m,p) | matrix multiplication
outer_inner | (i,t),(j,t)->(i,j) | inner over the last dimension, outer over the second to last, and loop/broadcast over the rest.

C-API for implementing Elementary Functions

The current interface remains unchanged, and PyUFunc_FromFuncAndData can still be used to implement (specialized) ufuncs, consisting of scalar elementary functions.

One can use PyUFunc_FromFuncAndDataAndSignature to declare a more general ufunc. The argument list is the same as PyUFunc_FromFuncAndData, with an additional argument specifying the signature as C string.

Furthermore, the callback function is of the same type as before, void (*foo)(char **args, intp *dimensions, intp *steps, void *func). When invoked, args is a list of length nargs containing the data of all input/output arguments. For a scalar elementary function, steps is also of length nargs, denoting the strides used for the arguments. dimensions is a pointer to a single integer defining the size of the axis to be looped over.

For a non-trivial signature, dimensions will also contain the sizes of the core dimensions as well, starting at the second entry. Only one size is provided for each unique dimension name and the sizes are given according to the first occurrence of a dimension name in the signature.

The first nargs elements of steps remain the same as for scalar ufuncs. The following elements contain the strides of all core dimensions for all arguments in order.

For example, consider a ufunc with signature (i,j),(i)->(). In this case, args will contain three pointers to the data of the input/output arrays a, b, c. Furthermore, dimensions will be [N, I, J] to define the size of N of the loop and the sizes I and J for the core dimensions i and j. Finally, steps will be [a_N, b_N, c_N, a_i, a_j, b_i], containing all necessary strides.


Optimizing Iterator/UFunc Performance

  • Numpy Enhancement Proposals
  • next
  • previous

Table Of Contents

  • Optimizing Iterator/UFunc Performance
    • Table of Contents
    • Abstract
    • Motivation
      • Image Compositing Example
    • Improving Cache-Coherency
      • Output Layout Selection Algorithm
    • Coalescing Dimensions
    • Inner Loop Specialization
    • Implementation Details
      • Iterator Rewrite
      • Proposed Iterator Memory Layout
      • Proposed Iterator API
        • Old -> New Iterator API Conversion
        • Iterator Pointer Type
        • Construction and Destruction
        • Functions For Iteration
        • Examples
        • Python Lambda UFunc Example
        • Python Addition Example
        • Image Compositing Example Revisited
        • Image Compositing With NumExpr

Previous topic

Generalized Universal Functions

Next topic

A Simple File Format for NumPy Arrays

Optimizing Iterator/UFunc Performance

Author: | Mark Wiebe <mwwiebe@gmail.com>
Content-Type: | text/x-rst
Created: | 25-Nov-2010

Table of Contents

Contents

  • Optimizing Iterator/UFunc Performance
    • Table of Contents
    • Abstract
    • Motivation
      • Image Compositing Example
    • Improving Cache-Coherency
      • Output Layout Selection Algorithm
    • Coalescing Dimensions
    • Inner Loop Specialization
    • Implementation Details
      • Iterator Rewrite
      • Proposed Iterator Memory Layout
      • Proposed Iterator API
        • Old -> New Iterator API Conversion
        • Iterator Pointer Type
        • Construction and Destruction
        • Functions For Iteration
        • Examples
        • Python Lambda UFunc Example
        • Python Addition Example
        • Image Compositing Example Revisited
        • Image Compositing With NumExpr

Abstract

This NEP proposes to replace the NumPy iterator and multi-iterator with a single new iterator, designed to be more flexible and allow for more cache-friendly data access. The new iterator also subsumes much of the core ufunc functionality, making it easy to get the current ufunc benefits in contexts which don’t precisely fit the ufunc mold. Key benefits include:

  • automatic reordering to find a cache-friendly access pattern
  • standard and customizable broadcasting
  • automatic type/byte-order/alignment conversions
  • optional buffering to minimize conversion memory usage
  • optional output arrays, with automatic allocation when unsupplied
  • automatic output or common type selection

A large fraction of this iterator design has already been implemented with promising results. Construction overhead is slightly greater (a.flat: 0.5 us, nditer(a): 1.4 us and broadcast(a,b): 1.4 us, nditer([a,b]): 2.2 us), but, as shown in an example, it is already possible to improve on the performance of the built-in NumPy mechanisms in pure Python code together with the iterator. One example rewrites np.add, getting a four times improvement with some Fortran-contiguous arrays, and another improves image compositing code from 1.4s to 180ms.

The implementation attempts to take into account the design decisions made in the NumPy 2.0 refactor, to make its future integration into libndarray relatively simple.

Motivation

NumPy defaults to returning C-contiguous arrays from UFuncs. This can result in extremely poor memory access patterns when dealing with data that is structured differently. A simple timing example illustrates this with a more than eight times performance hit from adding Fortran-contiguous arrays together. All timings are done using Numpy 2.0dev (Nov 22, 2010) on an Athlon 64 X2 4200+, with a 64-bit OS.:

In [1]: import numpy as np
In [2]: a = np.arange(1000000,dtype=np.float32).reshape(10,10,10,10,10,10)
In [3]: b, c, d = a.copy(), a.copy(), a.copy()

In [4]: timeit a+b+c+d
10 loops, best of 3: 28.5 ms per loop

In [5]: timeit a.T+b.T+c.T+d.T
1 loops, best of 3: 237 ms per loop

In [6]: timeit a.T.ravel('A')+b.T.ravel('A')+c.T.ravel('A')+d.T.ravel('A')
10 loops, best of 3: 29.6 ms per loop

In this case, it is simple to recover the performance by switching to a view of the memory, adding, then reshaping back. To further examine the problem and see how it isn’t always as trivial to work around, let’s consider simple code for working with image buffers in NumPy.

Image Compositing Example

For a more realistic example, consider an image buffer. Images are generally stored in a Fortran-contiguous order, and the colour channel can be treated as either a structured ‘RGB’ type or an extra dimension of length three. The resulting memory layout is neither C- nor Fortran-contiguous, but is easy to work with directly in NumPy, because of the flexibility of the ndarray. This appears ideal, because it makes the memory layout compatible with typical C or C++ image code, while simultaneously giving natural access in Python. Getting the color of pixel (x,y) is just ‘image[x,y]’.

The performance of this layout in NumPy turns out to be very poor. Here is code which creates two black images, and does an ‘over’ compositing operation on them.:

In [9]: image1 = np.zeros((1080,1920,3), dtype=np.float32).swapaxes(0,1)
In [10]: alpha1 = np.zeros((1080,1920,1), dtype=np.float32).swapaxes(0,1)
In [11]: image2 = np.zeros((1080,1920,3), dtype=np.float32).swapaxes(0,1)
In [12]: alpha2 = np.zeros((1080,1920,1), dtype=np.float32).swapaxes(0,1)
In [13]: def composite_over(im1, al1, im2, al2):
   ....:     return (im1 + (1-al1)*im2, al1 + (1-al1)*al2)

In [14]: timeit composite_over(image1,alpha1,image2,alpha2)
1 loops, best of 3: 3.51 s per loop

If we give up the convenient layout, and use the C-contiguous default, the performance is about seven times better.:

In [16]: image1 = np.zeros((1080,1920,3), dtype=np.float32)
In [17]: alpha1 = np.zeros((1080,1920,1), dtype=np.float32)
In [18]: image2 = np.zeros((1080,1920,3), dtype=np.float32)
In [19]: alpha2 = np.zeros((1080,1920,1), dtype=np.float32)

In [20]: timeit composite_over(image1,alpha1,image2,alpha2)
1 loops, best of 3: 581 ms per loop

But this is not all, since it turns out that broadcasting the alpha channel is exacting a performance price as well. If we use an alpha channel with 3 values instead of one, we get:

In [21]: image1 = np.zeros((1080,1920,3), dtype=np.float32)
In [22]: alpha1 = np.zeros((1080,1920,3), dtype=np.float32)
In [23]: image2 = np.zeros((1080,1920,3), dtype=np.float32)
In [24]: alpha2 = np.zeros((1080,1920,3), dtype=np.float32)

In [25]: timeit composite_over(image1,alpha1,image2,alpha2)
1 loops, best of 3: 313 ms per loop

For a final comparison, let’s see how it performs when we use one-dimensional arrays to ensure just a single loop does the calculation.:

In [26]: image1 = np.zeros((1080*1920*3), dtype=np.float32)
In [27]: alpha1 = np.zeros((1080*1920*3), dtype=np.float32)
In [28]: image2 = np.zeros((1080*1920*3), dtype=np.float32)
In [29]: alpha2 = np.zeros((1080*1920*3), dtype=np.float32)

In [30]: timeit composite_over(image1,alpha1,image2,alpha2)
1 loops, best of 3: 312 ms per loop

To get a reference performance number, I implemented this simple operation straightforwardly in C (careful to use the same compile options as NumPy). If I emulated the memory allocation and layout of the Python code, the performance was roughly 0.3 seconds, very much in line with NumPy’s performance. Combining the operations into one pass reduced the time to roughly 0.15 seconds.

A slight variation of this example is to use a single memory block with four channels (1920,1080,4) instead of separate image and alpha. This is more typical in image processing applications, and here’s how that looks with a C-contiguous layout.:

In [31]: image1 = np.zeros((1080,1920,4), dtype=np.float32)
In [32]: image2 = np.zeros((1080,1920,4), dtype=np.float32)
In [33]: def composite_over(im1, im2):
   ....:     ret = (1-im1[:,:,-1])[:,:,np.newaxis]*im2
   ....:     ret += im1
   ....:     return ret

In [34]: timeit composite_over(image1,image2)
1 loops, best of 3: 481 ms per loop

To see the improvements that implementation of the new iterator as proposed can produce, go to the example continued after the proposed API, near the bottom of the document.

Improving Cache-Coherency

In order to get the best performance from UFunc calls, the pattern of memory reads should be as regular as possible. Modern CPUs attempt to predict the memory read/write pattern and fill the cache ahead of time. The most predictable pattern is for all the inputs and outputs to be sequentially processed in the same order.

I propose that by default, the memory layout of the UFunc outputs be as close to that of the inputs as possible. Whenever there is an ambiguity or a mismatch, it defaults to a C-contiguous layout.

To understand how to accomplish this, we first consider the strides of all the inputs after the shapes have been normalized for broadcasting. By determining whether a set of strides are compatible and/or ambiguous, we can determine an output memory layout which maximizes coherency.

In broadcasting, the input shapes are first transformed to broadcast shapes by prepending singular dimensions, then the broadcast strides are created, where any singular dimension’s stride is set to zero.

Strides may be negative as well, and in certain cases this can be normalized to fit the following discussion. If all the strides for a particular axis are negative or zero, the strides for that dimension can be negated after adjusting the base data pointers appropriately.

Here’s an example of how three inputs with C-contiguous layouts result in broadcast strides. To simplify things, the examples use an itemsize of 1.

Input shapes: | (5,3,7) | (5,3,1) | (1,7)
Broadcast shapes: | (5,3,7) | (5,3,1) | (1,1,7)
Broadcast strides: | (21,7,1) | (3,1,0) | (0,0,1)

Compatible Strides - A set of strides are compatible if there exists a permutation of the axes such that the strides are decreasing for every stride in the set, excluding entries that are zero.

The example above satisfies the definition with the identity permutation. In the motivation image example, the strides are slightly different if we separate the colour and alpha information or not. The permutation which demonstrates compatibility here is the transposition (0,1).

Input/Broadcast shapes: | Image (1920, 1080, 3) | Alpha (1920, 1080, 1)
Broadcast strides (separate): | (3,5760,1) | (1,1920,0)
Broadcast strides (together): | (4,7680,1) | (4,7680,0)

Ambiguous Strides - A set of compatible strides are ambiguous if more than one permutation of the axes exists such that the strides are decreasing for every stride in the set, excluding entries that are zero.

This typically occurs when every axis has a 0-stride somewhere in the set of strides. The simplest example is in two dimensions, as follows.

Broadcast shapes: | (1,3) | (5,1)
Broadcast strides: | (0,1) | (1,0)

There may, however, be unambiguous compatible strides without a single input forcing the entire layout, as in this example:

Broadcast shapes: | (1,3,4) | (5,3,1)
Broadcast strides: | (0,4,1) | (3,1,0)

In the face of ambiguity, we have a choice to either completely throw away the fact that the strides are compatible, or try to resolve the ambiguity by adding an additional constraint. I think the appropriate choice is to resolve it by picking the memory layout closest to C-contiguous, but still compatible with the input strides.

Output Layout Selection Algorithm

The output ndarray memory layout we would like to produce is as follows:

Consistent/Unambiguous strides: | The single consistent layout
Consistent/Ambiguous strides: | The consistent layout closest to C-contiguous
Inconsistent strides: | C-contiguous

Here is pseudo-code for an algorithm to compute the permutation for the output layout.:

perm = range(ndim) # Identity, i.e. C-contiguous
# Insertion sort, ignoring 0-strides
# Note that the sort must be stable, and 0-strides may
# be reordered if necessary, but should be moved as little
# as possible.
for i0 = 1 to ndim-1:
    # ipos is where perm[i0] will get inserted
    ipos = i0
    j0 = perm[i0]
    for i1 = i0-1 to 0:
        j1 = perm[i1]
        ambig, shouldswap = True, False
        # Check whether any strides are ordered wrong
        for strides in broadcast_strides:
            if strides[j0] != 0 and strides[j1] != 0:
                if strides[j0] > strides[j1]:
                    # Only set swap if it's still ambiguous.
                    if ambig:
                        shouldswap = True
                else:
                    # Set swap even if it's not ambiguous,
                    # because not swapping is the choice
                    # for conflicts as well.
                    shouldswap = False
                ambig = False
        # If there was an unambiguous comparison, either shift ipos
        # to i1 or stop looking for the comparison
        if not ambig:
            if shouldswap:
                ipos = i1
            else:
                break
    # Insert perm[i0] into the right place
    if ipos != i0:
       for i1 = i0-1 to ipos:
         perm[i1+1] = perm[i1]
       perm[ipos] = j0
# perm is now the closest consistent ordering to C-contiguous
return perm

Coalescing Dimensions

In many cases, the memory layout allows for the use of a one-dimensional loop instead of tracking multiple coordinates within the iterator. The existing code already exploits this when the data is C-contiguous, but since we’re reordering the axes, we can apply this optimization more generally.

Once the iteration strides have been sorted to be monotonically decreasing, any dimensions which could be coalesced are side by side. If for all the operands, incrementing by strides[i+1] shape[i+1] times is the same as incrementing by strides[i], or strides[i+1]*shape[i+1] == strides[i], dimensions i and i+1 can be coalesced into a single dimension.

Here is pseudo-code for coalescing.:

# Figure out which pairs of dimensions can be coalesced
can_coalesce = [False]*ndim
for strides, shape in zip(broadcast_strides, broadcast_shape):
    for i = 0 to ndim-2:
        if strides[i+1]*shape[i+1] == strides[i]:
            can_coalesce[i] = True
# Coalesce the types
new_ndim = ndim - count_nonzero(can_coalesce)
for strides, shape in zip(broadcast_strides, broadcast_shape):
    j = 0
    for i = 0 to ndim-1:
        # Note that can_coalesce[ndim-1] is always False, so
        # there is no out-of-bounds access here.
        if can_coalesce[i]:
            shape[i+1] = shape[i]*shape[i+1]
        else:
            strides[j] = strides[i]
            shape[j] = shape[i]
            j += 1

Inner Loop Specialization

Specialization is handled purely by the inner loop function, so this optimization is independent of the others. Some specialization is already done, like for the reduce operation. The idea is mentioned in http://projects.scipy.org/numpy/wiki/ProjectIdeas, “use intrinsics (SSE-instructions) to speed up low-level loops in NumPy.”

Here are some possibilities for two-argument functions, covering the important cases of add/subtract/multiply/divide.

  • The first or second argument is a single value (i.e. a 0 stride value) and does not alias the output. arr = arr + 1; arr = 1 + arr
    • Can load the constant once instead of reloading it from memory every time
  • The strides match the size of the data type. C- or Fortran-contiguous data, for example
    • Can do a simple loop without using strides
  • The strides match the size of the data type, and they are both 16-byte aligned (or differ from 16-byte aligned by the same offset)
    • Can use SSE to process multiple values at once
  • The first input and the output are the same single value (i.e. a reduction operation).
    • This is already specialized for many UFuncs in the existing code

The above cases are not generally mutually exclusive, for example a constant argument may be combined with SSE when the strides match the data type size, and reductions can be optimized with SSE as well.

Implementation Details

Except for inner loop specialization, the discussed optimizations significantly affect ufunc_object.c and the PyArrayIterObject/PyArrayMultiIterObject used to do the broadcasting. In general, it should be possible to emulate the current behavior where it is desired, but I believe the default should be to produce and manipulate memory layouts which will give the best performance.

To support the new cache-friendly behavior, we introduce a new option ‘K’ (for “keep”) for any order= parameter.

The proposed ‘order=’ flags become as follows:

‘C’ | C-contiguous layout
‘F’ | Fortran-contiguous layout
‘A’ | ‘F’ if the input(s) have a Fortran-contiguous layout, ‘C’ otherwise (“Any Contiguous”)
‘K’ | a layout equivalent to ‘C’ followed by some permutation of the axes, as close to the layout of the input(s) as possible (“Keep Layout”)

Or as an enum:

/* For specifying array memory layout or iteration order */
typedef enum {
        /* Fortran order if inputs are all Fortran, C otherwise */
        NPY_ANYORDER=-1,
        /* C order */
        NPY_CORDER=0,
        /* Fortran order */
        NPY_FORTRANORDER=1,
        /* An order as close to the inputs as possible */
        NPY_KEEPORDER=2
} NPY_ORDER;

Perhaps a good strategy is to first implement the capabilities discussed here without changing the defaults. Once they are implemented and well-tested, the defaults can change from order='C' to order='K' everywhere appropriate. UFuncs additionally should gain an order= parameter to control the layout of their output(s).

The iterator can do automatic casting, and I have created a sequence of progressively more permissive casting rules. Perhaps for 2.0, NumPy could adopt this enum as its prefered way of dealing with casting.:

/* For specifying allowed casting in operations which support it */
typedef enum {
        /* Only allow identical types */
        NPY_NO_CASTING=0,
        /* Allow identical and byte swapped types */
        NPY_EQUIV_CASTING=1,
        /* Only allow safe casts */
        NPY_SAFE_CASTING=2,
        /* Allow safe casts and casts within the same kind */
        NPY_SAME_KIND_CASTING=3,
        /* Allow any casts */
        NPY_UNSAFE_CASTING=4
} NPY_CASTING;

Iterator Rewrite

Based on an analysis of the code, it appears that refactoring the existing iteration objects to implement these optimizations is prohibitively difficult. Additionally, some usage of the iterator requires modifying internal values or flags, so code using the iterator would have to change anyway. Thus we propose creating a new iterator object which subsumes the existing iterator functionality and expands it to account for the optimizations.

High level goals for the replacement iterator include:

  • Small memory usage and a low number of memory allocations.
  • Simple cases (like flat arrays) should have very little overhead.
  • Combine single and multiple iteration into one object.

Capabilities that should be provided to user code:

  • Iterate in C, Fortran, or “Fastest” (default) order.
  • Track a C-style or Fortran-style flat index if requested (existing iterator always tracks a C-style index). This can be done independently of the iteration order.
  • Track the coordinates if requested (the existing iterator requires manually changing an internal iterator flag to guarantee this).
  • Skip iteration of the last internal dimension so that it can be processed with an inner loop.
  • Jump to a specific coordinate in the array.
  • Iterate an arbitrary subset of axes (to support, for example, reduce with multiple axes at once).
  • Ability to automatically allocate output parameters if a NULL input is provided, These outputs should have a memory layout matching the iteration order, and are the mechanism for the order='K' support.
  • Automatic copying and/or buffering of inputs which do not satisfy type/byte-order/alignment requirements. The caller’s iteration inner loop should be the same no matter what buffering or copying is done.

Notes for implementation:

  • User code must never touch the inside of the iterator. This allows for drastic changes of the internal memory layout in the future, if higher-performance implementation strategies are found.
  • Use a function pointer instead of a macro for iteration. This way, specializations can be created for the common cases, like when ndim is small, for different flag settings, and when the number of arrays iterated is small. Also, an iteration pattern can be prescribed that makes a copy of the function pointer first to allow the compiler to keep the function pointer in a register.
  • Dynamically create the memory layout, to minimize the number of cache lines taken up by the iterator (for LP64, sizeof(PyArrayIterObject) is about 2.5KB, and a binary operation like plus needs three of these for the Multi-Iterator).
  • Isolate the C-API object from Python reference counting, so that it can be used naturally from C. The Python object then becomes a wrapper around the C iterator. This is analogous to the PEP 3118 design separation of Py_buffer and memoryview.

Proposed Iterator Memory Layout

The following struct describes the iterator memory. All items are packed together, which means that different values of the flags, ndim, and niter will produce slightly different layouts.

struct {
    /* Flags indicate what optimizations have been applied, and
     * affect the layout of this struct. */
    uint32 itflags;
    /* Number of iteration dimensions.  If FLAGS_HASCOORDS is set,
     * it matches the creation ndim, otherwise it may be smaller.  */
    uint16 ndim;
    /* Number of objects being iterated.  This is fixed at creation time. */
    uint16 niter;

    /* The number of times the iterator will iterate */
    intp itersize;

    /* The permutation is only used when FLAGS_HASCOORDS is set,
     * and is placed here so its position depends on neither ndim
     * nor niter. */
    intp perm[ndim];

    /* The data types of all the operands */
    PyArray_Descr *dtypes[niter];
    /* Backups of the starting axisdata 'ptr' values, to support Reset */
    char *resetdataptr[niter];
    /* Backup of the starting index value, to support Reset */
    npy_intp resetindex;

    /* When the iterator is destroyed, Py_XDECREF is called on all
       these objects */
    PyObject *objects[niter];

    /* Flags indicating read/write status and buffering
     * for each operand. */
    uint8 opitflags[niter];
    /* Padding to make things intp-aligned again */
    uint8 padding[];

    /* If some or all of the inputs are being buffered */
    #if (flags&FLAGS_BUFFERED)
    struct buffer_data {
        /* The size of the buffer, and which buffer we're on.
         * the i-th iteration has i = buffersize*bufferindex+pos
         */
        intp buffersize;
        /* For tracking position inside the buffer */
        intp size, pos;
        /* The strides for the pointers */
        intp stride[niter];
        /* Pointers to the data for the current iterator position.
         * The buffer_data.value ptr[i] equals either
         * axis_data[0].ptr[i] or buffer_data.buffers[i] depending
         * on whether copying to the buffer was necessary.
         */
        char* ptr[niter];
        /* Functions to do the copyswap and casting necessary */
        transferfn_t readtransferfn[niter];
        void *readtransferdata[niter];
        transferfn_t writetransferfn[niter];
        void *writetransferdata[niter];
        /* Pointers to the allocated buffers for operands
         * which the iterator determined needed buffering
         */
        char *buffers[niter];
    };
    #endif /* FLAGS_BUFFERED */

    /* Data per axis, starting with the most-frequently
     * updated, and in decreasing order after that. */
    struct axis_data {
        /* The shape of this axis */
        intp shape;
        /* The current coordinate along this axis */
        intp coord;
        /* The operand and index strides for this axis
        intp stride[niter];
        {intp indexstride;} #if (flags&FLAGS_HASINDEX);
        /* The operand pointers and index values for this axis */
        char* ptr[niter];
        {intp index;} #if (flags&FLAGS_HASINDEX);
    }[ndim];
};

The array of axis_data structs is ordered to be in increasing rapidity of increment updates. If the perm is the identity, this means it’s reversed from the C-order. This is done so data items touched most often are closest to the beginning of the struct, where the common properties are, resulting in increased cache coherency. It also simplifies the iternext call, while making getcoord and related functions slightly more complicated.

Proposed Iterator API

The existing iterator API includes functions like PyArrayIter_Check, PyArray_Iter* and PyArray_ITER_*. The multi-iterator array includes PyArray_MultiIter*, PyArray_Broadcast, and PyArray_RemoveSmallest. The new iterator design replaces all of this functionality with a single object and associated API. One goal of the new API is that all uses of the existing iterator should be replaceable with the new iterator without significant effort.

The C-API naming convention chosen is based on the one in the numpy-refactor branch, where libndarray has the array named NpyArray and functions named NpyArray_*. The iterator is named NpyIter and functions are named NpyIter_*.

The Python exposure has the iterator named np.nditer. One possible release strategy for this iterator would be to release a 1.X (1.6?) version with the iterator added, but not used by the NumPy code. Then, 2.0 can be release with it fully integrated. If this strategy is chosen, the naming convention and API should be finalized as much as possible before the 1.X release. The name np.iter can’t be used because it conflicts with the Python built-in iter. I would suggest the name np.nditer within Python, as it is currently unused.

In addition to the performance goals set out for the new iterator, it appears the API can be refactored to better support some common NumPy programming idioms.

By moving some functionality currently in the UFunc code into the iterator, it should make it easier for extension code which wants to emulate UFunc behavior in cases which don’t quite fit the UFunc paradigm. In particular, emulating the UFunc buffering behavior is not a trivial enterprise.

Old -> New Iterator API Conversion

For the regular iterator:

PyArray_IterNew | NpyIter_New
PyArray_IterAllButAxis | NpyIter_New + axes parameter or Iterator flag NPY_ITER_NO_INNER_ITERATION
PyArray_BroadcastToShape | NOT SUPPORTED (but could be, if needed)
PyArrayIter_Check | Will need to add this in Python exposure
PyArray_ITER_RESET | NpyIter_Reset
PyArray_ITER_NEXT | Function pointer from NpyIter_GetIterNext
PyArray_ITER_DATA | NpyIter_GetDataPtrArray
PyArray_ITER_GOTO | NpyIter_GotoCoords
PyArray_ITER_GOTO1D | NpyIter_GotoIndex
PyArray_ITER_NOTDONE | Return value of iternext function pointer

For the multi-iterator:

PyArray_MultiIterNew | NpyIter_MultiNew
PyArray_MultiIter_RESET | NpyIter_Reset
PyArray_MultiIter_NEXT | Function pointer from NpyIter_GetIterNext
PyArray_MultiIter_DATA | NpyIter_GetDataPtrArray
PyArray_MultiIter_NEXTi | NOT SUPPORTED (always lock-step iteration)
PyArray_MultiIter_GOTO | NpyIter_GotoCoords
PyArray_MultiIter_GOTO1D | NpyIter_GotoIndex
PyArray_MultiIter_NOTDONE | Return value of iternext function pointer
PyArray_Broadcast | Handled by NpyIter_MultiNew
PyArray_RemoveSmallest | Iterator flag NPY_ITER_NO_INNER_ITERATION

For other API calls:

PyArray_ConvertToCommonType Iterator flag NPY_ITER_COMMON_DTYPE

Iterator Pointer Type

The iterator structure is internally generated, but a type is still needed to provide warnings and/or errors when the wrong type is passed to the API. We do this with a typedef of an incomplete struct

typedef struct NpyIter_InternalOnly NpyIter;

Construction and Destruction

NpyIter* NpyIter_New(PyArrayObject* op, npy_uint32 flags, NPY_ORDER order, NPY_CASTING casting, PyArray_Descr* dtype, npy_intp a_ndim, npy_intp *axes, npy_intp buffersize)

Creates an iterator for the given numpy array object op.

Flags that may be passed in flags are any combination of the global and per-operand flags documented in NpyIter_MultiNew, except for NPY_ITER_ALLOCATE.

Any of the NPY_ORDER enum values may be passed to order. For efficient iteration, NPY_KEEPORDER is the best option, and the other orders enforce the particular iteration pattern.

Any of the NPY_CASTING enum values may be passed to casting. The values include NPY_NO_CASTING, NPY_EQUIV_CASTING, NPY_SAFE_CASTING, NPY_SAME_KIND_CASTING, and NPY_UNSAFE_CASTING. To allow the casts to occur, copying or buffering must also be enabled.

If dtype isn’t NULL, then it requires that data type. If copying is allowed, it will make a temporary copy if the data is castable. If UPDATEIFCOPY is enabled, it will also copy the data back with another cast upon iterator destruction.

If a_ndim is greater than zero, axes must also be provided. In this case, axes is an a_ndim-sized array of op‘s axes. A value of -1 in axes means newaxis. Within the axes array, axes may not be repeated.

If buffersize is zero, a default buffer size is used, otherwise it specifies how big of a buffer to use. Buffers which are powers of 2 such as 512 or 1024 are recommended.

Returns NULL if there is an error, otherwise returns the allocated iterator.

To make an iterator similar to the old iterator, this should work.:

iter = NpyIter_New(op, NPY_ITER_READWRITE,
                    NPY_CORDER, NPY_NO_CASTING, NULL, 0, NULL);

If you want to edit an array with aligned double code, but the order doesn’t matter, you would use this.:

dtype = PyArray_DescrFromType(NPY_DOUBLE);
iter = NpyIter_New(op, NPY_ITER_READWRITE |
                    NPY_ITER_BUFFERED |
                    NPY_ITER_NBO,
                    NPY_ITER_ALIGNED,
                    NPY_KEEPORDER,
                    NPY_SAME_KIND_CASTING,
                    dtype, 0, NULL);
Py_DECREF(dtype);

NpyIter* NpyIter_MultiNew(npy_intp niter, PyArrayObject** op, npy_uint32 flags, NPY_ORDER order, NPY_CASTING casting, npy_uint32 *op_flags, PyArray_Descr** op_dtypes, npy_intp oa_ndim, npy_intp **op_axes, npy_intp buffersize)

Creates an iterator for broadcasting the niter array objects provided in op.

For normal usage, use 0 for oa_ndim and NULL for op_axes. See below for a description of these parameters, which allow for custom manual broadcasting as well as reordering and leaving out axes.

Any of the NPY_ORDER enum values may be passed to order. For efficient iteration, NPY_KEEPORDER is the best option, and the other orders enforce the particular iteration pattern. When using NPY_KEEPORDER, if you also want to ensure that the iteration is not reversed along an axis, you should pass the flag NPY_ITER_DONT_NEGATE_STRIDES.

Any of the NPY_CASTING enum values may be passed to casting. The values include NPY_NO_CASTING, NPY_EQUIV_CASTING, NPY_SAFE_CASTING, NPY_SAME_KIND_CASTING, and NPY_UNSAFE_CASTING. To allow the casts to occur, copying or buffering must also be enabled.

If op_dtypes isn’t NULL, it specifies a data type or NULL for each op[i].

The parameter oa_ndim, when non-zero, specifies the number of dimensions that will be iterated with customized broadcasting. If it is provided, op_axes must also be provided. These two parameters let you control in detail how the axes of the operand arrays get matched together and iterated. In op_axes, you must provide an array of niter pointers to oa_ndim-sized arrays of type npy_intp. If an entry in op_axes is NULL, normal broadcasting rules will apply. In op_axes[j][i] is stored either a valid axis of op[j], or -1 which means newaxis. Within each op_axes[j] array, axes may not be repeated. The following example is how normal broadcasting applies to a 3-D array, a 2-D array, a 1-D array and a scalar.:

npy_intp oa_ndim = 3;               /* # iteration axes */
npy_intp op0_axes[] = {0, 1, 2};    /* 3-D operand */
npy_intp op1_axes[] = {-1, 0, 1};   /* 2-D operand */
npy_intp op2_axes[] = {-1, -1, 0};  /* 1-D operand */
npy_intp op3_axes[] = {-1, -1, -1}  /* 0-D (scalar) operand */
npy_intp *op_axes[] = {op0_axes, op1_axes, op2_axes, op3_axes};

If buffersize is zero, a default buffer size is used, otherwise it specifies how big of a buffer to use. Buffers which are powers of 2 such as 512 or 1024 are recommended.

Returns NULL if there is an error, otherwise returns the allocated iterator.

Flags that may be passed in flags, applying to the whole iterator, are:

NPY_ITER_C_INDEX, NPY_ITER_F_INDEX

Causes the iterator to track an index matching C or Fortran order. These options are mutually exclusive.

NPY_ITER_COORDS

Causes the iterator to track array coordinates. This prevents the iterator from coalescing axes to produce bigger inner loops.

NPY_ITER_NO_INNER_ITERATION

Causes the iterator to skip iteration of the innermost loop, allowing the user of the iterator to handle it.

This flag is incompatible with NPY_ITER_C_INDEX, NPY_ITER_F_INDEX, and NPY_ITER_COORDS.

NPY_ITER_DONT_NEGATE_STRIDES

This only affects the iterator when NPY_KEEPORDER is specified for the order parameter. By default with NPY_KEEPORDER, the iterator reverses axes which have negative strides, so that memory is traversed in a forward direction. This disables this step. Use this flag if you want to use the underlying memory-ordering of the axes, but don’t want an axis reversed. This is the behavior of numpy.ravel(a, order='K'), for instance.

NPY_ITER_COMMON_DTYPE

Causes the iterator to convert all the operands to a common data type, calculated based on the ufunc type promotion rules. The flags for each operand must be set so that the appropriate casting is permitted, and copying or buffering must be enabled.

If the common data type is known ahead of time, don’t use this flag. Instead, set the requested dtype for all the operands.

NPY_ITER_REFS_OK

Indicates that arrays with reference types (object arrays or structured arrays containing an object type) may be accepted and used in the iterator. If this flag is enabled, the caller must be sure to check whether NpyIter_IterationNeedsAPI(iter) is true, in which case it may not release the GIL during iteration.

NPY_ITER_ZEROSIZE_OK

Indicates that arrays with a size of zero should be permitted. Since the typical iteration loop does not naturally work with zero-sized arrays, you must check that the IterSize is non-zero before entering the iteration loop.

NPY_ITER_REDUCE_OK

Permits writeable operands with a dimension with zero stride and size greater than one. Note that such operands must be read/write.

When buffering is enabled, this also switches to a special buffering mode which reduces the loop length as necessary to not trample on values being reduced.

Note that if you want to do a reduction on an automatically allocated output, you must use NpyIter_GetOperandArray to get its reference, then set every value to the reduction unit before doing the iteration loop. In the case of a buffered reduction, this means you must also specify the flag NPY_ITER_DELAY_BUFALLOC, then reset the iterator after initializing the allocated operand to prepare the buffers.

NPY_ITER_RANGED

Enables support for iteration of sub-ranges of the full iterindex range [0, NpyIter_IterSize(iter)). Use the function NpyIter_ResetToIterIndexRange to specify a range for iteration.

This flag can only be used with NPY_ITER_NO_INNER_ITERATION when NPY_ITER_BUFFERED is enabled. This is because without buffering, the inner loop is always the size of the innermost iteration dimension, and allowing it to get cut up would require special handling, effectively making it more like the buffered version.

NPY_ITER_BUFFERED

Causes the iterator to store buffering data, and use buffering to satisfy data type, alignment, and byte-order requirements. To buffer an operand, do not specify the NPY_ITER_COPY or NPY_ITER_UPDATEIFCOPY flags, because they will override buffering. Buffering is especially useful for Python code using the iterator, allowing for larger chunks of data at once to amortize the Python interpreter overhead.

If used with NPY_ITER_NO_INNER_ITERATION, the inner loop for the caller may get larger chunks than would be possible without buffering, because of how the strides are laid out.

Note that if an operand is given the flag NPY_ITER_COPY or NPY_ITER_UPDATEIFCOPY, a copy will be made in preference to buffering. Buffering will still occur when the array was broadcast so elements need to be duplicated to get a constant stride.

In normal buffering, the size of each inner loop is equal to the buffer size, or possibly larger if NPY_ITER_GROWINNER is specified. If NPY_ITER_REDUCE_OK is enabled and a reduction occurs, the inner loops may become smaller depending on the structure of the reduction.

NPY_ITER_GROWINNER

When buffering is enabled, this allows the size of the inner loop to grow when buffering isn’t necessary. This option is best used if you’re doing a straight pass through all the data, rather than anything with small cache-friendly arrays of temporary values for each inner loop.

NPY_ITER_DELAY_BUFALLOC

When buffering is enabled, this delays allocation of the buffers until one of the NpyIter_Reset* functions is called. This flag exists to avoid wasteful copying of buffer data when making multiple copies of a buffered iterator for multi-threaded iteration.

Another use of this flag is for setting up reduction operations. After the iterator is created, and a reduction output is allocated automatically by the iterator (be sure to use READWRITE access), its value may be initialized to the reduction unit. Use NpyIter_GetOperandArray to get the object. Then, call NpyIter_Reset to allocate and fill the buffers with their initial values.

Flags that may be passed in op_flags[i], where 0 <= i < niter:

NPY_ITER_READWRITE, NPY_ITER_READONLY, NPY_ITER_WRITEONLY

Indicate how the user of the iterator will read or write to op[i]. Exactly one of these flags must be specified per operand.

NPY_ITER_COPY

Allow a copy of op[i] to be made if it does not meet the data type or alignment requirements as specified by the constructor flags and parameters.

NPY_ITER_UPDATEIFCOPY

Triggers NPY_ITER_COPY, and when an array operand is flagged for writing and is copied, causes the data in a copy to be copied back to op[i] when the iterator is destroyed.

If the operand is flagged as write-only and a copy is needed, an uninitialized temporary array will be created and then copied to back to op[i] on destruction, instead of doing the unecessary copy operation.

NPY_ITER_NBO, NPY_ITER_ALIGNED, NPY_ITER_CONTIG

Causes the iterator to provide data for op[i] that is in native byte order, aligned according to the dtype requirements, contiguous, or any combination.

By default, the iterator produces pointers into the arrays provided, which may be aligned or unaligned, and with any byte order. If copying or buffering is not enabled and the operand data doesn’t satisfy the constraints, an error will be raised.

The contiguous constraint applies only to the inner loop, successive inner loops may have arbitrary pointer changes.

If the requested data type is in non-native byte order, the NBO flag overrides it and the requested data type is converted to be in native byte order.

NPY_ITER_ALLOCATE

This is for output arrays, and requires that the flag NPY_ITER_WRITEONLY be set. If op[i] is NULL, creates a new array with the final broadcast dimensions, and a layout matching the iteration order of the iterator.

When op[i] is NULL, the requested data type op_dtypes[i] may be NULL as well, in which case it is automatically generated from the dtypes of the arrays which are flagged as readable. The rules for generating the dtype are the same is for UFuncs. Of special note is handling of byte order in the selected dtype. If there is exactly one input, the input’s dtype is used as is. Otherwise, if more than one input dtypes are combined together, the output will be in native byte order.

After being allocated with this flag, the caller may retrieve the new array by calling NpyIter_GetOperandArray and getting the i-th object in the returned C array. The caller must call Py_INCREF on it to claim a reference to the array.

NPY_ITER_NO_SUBTYPE

For use with NPY_ITER_ALLOCATE, this flag disables allocating an array subtype for the output, forcing it to be a straight ndarray.

TODO: Maybe it would be better to introduce a function NpyIter_GetWrappedOutput and remove this flag?

NPY_ITER_NO_BROADCAST

Ensures that the input or output matches the iteration dimensions exactly.

NPY_ITER_WRITEABLE_REFERENCES

By default, the iterator fails on creation if the iterator has a writeable operand where the data type involves Python references. Adding this flag indicates that the code using the iterator is aware of this possibility and handles it correctly.

NpyIter *NpyIter_Copy(NpyIter *iter)

Makes a copy of the given iterator. This function is provided primarily to enable multi-threaded iteration of the data.

TODO: Move this to a section about multithreaded iteration.

The recommended approach to multithreaded iteration is to first create an iterator with the flags NPY_ITER_NO_INNER_ITERATION, NPY_ITER_RANGED, NPY_ITER_BUFFERED, NPY_ITER_DELAY_BUFALLOC, and possibly NPY_ITER_GROWINNER. Create a copy of this iterator for each thread (minus one for the first iterator). Then, take the iteration index range [0, NpyIter_GetIterSize(iter)) and split it up into tasks, for example using a TBB parallel_for loop. When a thread gets a task to execute, it then uses its copy of the iterator by calling NpyIter_ResetToIterIndexRange and iterating over the full range.

When using the iterator in multi-threaded code or in code not holding the Python GIL, care must be taken to only call functions which are safe in that context. NpyIter_Copy cannot be safely called without the Python GIL, because it increments Python references. The Reset* and some other functions may be safely called by passing in the errmsg parameter as non-NULL, so that the functions will pass back errors through it instead of setting a Python exception.

int NpyIter_UpdateIter(NpyIter *iter, npy_intp i, npy_uint32 op_flags, NPY_CASTING casting, PyArray_Descr *dtype) UNIMPLEMENTED

Updates the i-th operand within the iterator to possibly have a new data type or more restrictive flag attributes. A use-case for this is to allow the automatic allocation to determine an output data type based on the standard NumPy type promotion rules, then use this function to convert the inputs and possibly the automatic output to a different data type during processing.

This operation can only be done if NPY_ITER_COORDS was passed as a flag to the iterator. If coordinates are not needed, call the function NpyIter_RemoveCoords() once no more calls to NpyIter_UpdateIter are needed.

If the i-th operand has already been copied, an error is thrown. To avoid this, leave all the flags out except the read/write indicators for any operand that later has NpyIter_UpdateIter called on it.

The flags that may be passed in op_flags are NPY_ITER_COPY, NPY_ITER_UPDATEIFCOPY, NPY_ITER_NBO, NPY_ITER_ALIGNED, NPY_ITER_CONTIG.

int NpyIter_RemoveAxis(NpyIter *iter, npy_intp axis)

Removes an axis from iteration. This requires that NPY_ITER_COORDS was set for iterator creation, and does not work if buffering is enabled or an index is being tracked. This function also resets the iterator to its initial state.

This is useful for setting up an accumulation loop, for example. The iterator can first be created with all the dimensions, including the accumulation axis, so that the output gets created correctly. Then, the accumulation axis can be removed, and the calculation done in a nested fashion.

WARNING: This function may change the internal memory layout of the iterator. Any cached functions or pointers from the iterator must be retrieved again!

Returns NPY_SUCCEED or NPY_FAIL.

int NpyIter_RemoveCoords(NpyIter *iter)

If the iterator has coordinates, this strips support for them, and does further iterator optimizations that are possible if coordinates are not needed. This function also resets the iterator to its initial state.

WARNING: This function may change the internal memory layout of the iterator. Any cached functions or pointers from the iterator must be retrieved again!

After calling this function, NpyIter_HasCoords(iter) will return false.

Returns NPY_SUCCEED or NPY_FAIL.

int NpyIter_RemoveInnerLoop(NpyIter *iter)

If UpdateIter/RemoveCoords was used, you may want to specify the flag NPY_ITER_NO_INNER_ITERATION. This flag is not permitted together with NPY_ITER_COORDS, so this function is provided to enable the feature after NpyIter_RemoveCoords is called. This function also resets the iterator to its initial state.

WARNING: This function changes the internal logic of the iterator. Any cached functions or pointers from the iterator must be retrieved again!

Returns NPY_SUCCEED or NPY_FAIL.

int NpyIter_Deallocate(NpyIter *iter)

Deallocates the iterator object. This additionally frees any copies made, triggering UPDATEIFCOPY behavior where necessary.

Returns NPY_SUCCEED or NPY_FAIL.

int NpyIter_Reset(NpyIter *iter, char **errmsg)

Resets the iterator back to its initial state, at the beginning of the iteration range.

Returns NPY_SUCCEED or NPY_FAIL. If errmsg is non-NULL, no Python exception is set when NPY_FAIL is returned. Instead, *errmsg is set to an error message. When errmsg is non-NULL, the function may be safely called without holding the Python GIL.

int NpyIter_ResetToIterIndexRange(NpyIter *iter, npy_intp istart, npy_intp iend, char **errmsg)

Resets the iterator and restricts it to the iterindex range [istart, iend). See NpyIter_Copy for an explanation of how to use this for multi-threaded iteration. This requires that the flag NPY_ITER_RANGED was passed to the iterator constructor.

If you want to reset both the iterindex range and the base pointers at the same time, you can do the following to avoid extra buffer copying (be sure to add the return code error checks when you copy this code).:

/* Set to a trivial empty range */
NpyIter_ResetToIterIndexRange(iter, 0, 0);
/* Set the base pointers */
NpyIter_ResetBasePointers(iter, baseptrs);
/* Set to the desired range */
NpyIter_ResetToIterIndexRange(iter, istart, iend);

Returns NPY_SUCCEED or NPY_FAIL. If errmsg is non-NULL, no Python exception is set when NPY_FAIL is returned. Instead, *errmsg is set to an error message. When errmsg is non-NULL, the function may be safely called without holding the Python GIL.

int NpyIter_ResetBasePointers(NpyIter *iter, char **baseptrs, char **errmsg)

Resets the iterator back to its initial state, but using the values in baseptrs for the data instead of the pointers from the arrays being iterated. This functions is intended to be used, together with the op_axes parameter, by nested iteration code with two or more iterators.

Returns NPY_SUCCEED or NPY_FAIL. If errmsg is non-NULL, no Python exception is set when NPY_FAIL is returned. Instead, *errmsg is set to an error message. When errmsg is non-NULL, the function may be safely called without holding the Python GIL.

TODO: Move the following into a special section on nested iterators.

Creating iterators for nested iteration requires some care. All the iterator operands must match exactly, or the calls to NpyIter_ResetBasePointers will be invalid. This means that automatic copies and output allocation should not be used haphazardly. It is possible to still use the automatic data conversion and casting features of the iterator by creating one of the iterators with all the conversion parameters enabled, then grabbing the allocated operands with the NpyIter_GetOperandArray function and passing them into the constructors for the rest of the iterators.

WARNING: When creating iterators for nested iteration, the code must not use a dimension more than once in the different iterators. If this is done, nested iteration will produce out-of-bounds pointers during iteration.

WARNING: When creating iterators for nested iteration, buffering can only be applied to the innermost iterator. If a buffered iterator is used as the source for baseptrs, it will point into a small buffer instead of the array and the inner iteration will be invalid.

The pattern for using nested iterators is as follows.:

NpyIter *iter1, *iter1;
NpyIter_IterNext_Fn iternext1, iternext2;
char **dataptrs1;

/*
 * With the exact same operands, no copies allowed, and
 * no axis in op_axes used both in iter1 and iter2.
 * Buffering may be enabled for iter2, but not for iter1.
 */
iter1 = ...; iter2 = ...;

iternext1 = NpyIter_GetIterNext(iter1);
iternext2 = NpyIter_GetIterNext(iter2);
dataptrs1 = NpyIter_GetDataPtrArray(iter1);

do {
    NpyIter_ResetBasePointers(iter2, dataptrs1);
    do {
        /* Use the iter2 values */
    } while (iternext2(iter2));
} while (iternext1(iter1));

int NpyIter_GotoCoords(NpyIter *iter, npy_intp *coords)

Adjusts the iterator to point to the ndim coordinates pointed to by coords. Returns an error if coordinates are not being tracked, the coordinates are out of bounds, or inner loop iteration is disabled.

Returns NPY_SUCCEED or NPY_FAIL.

int NpyIter_GotoIndex(NpyIter *iter, npy_intp index)

Adjusts the iterator to point to the index specified. If the iterator was constructed with the flag NPY_ITER_C_INDEX, index is the C-order index, and if the iterator was constructed with the flag NPY_ITER_F_INDEX, index is the Fortran-order index. Returns an error if there is no index being tracked, the index is out of bounds, or inner loop iteration is disabled.

Returns NPY_SUCCEED or NPY_FAIL.

npy_intp NpyIter_GetIterSize(NpyIter *iter)

Returns the number of elements being iterated. This is the product of all the dimensions in the shape.

npy_intp NpyIter_GetReduceBlockSizeFactor(NpyIter *iter) UNIMPLEMENTED

This provides a factor that must divide into the blocksize used for ranged iteration to safely multithread a reduction. If the iterator has no reduction, it returns 1.

When using ranged iteration to multithread a reduction, there are two possible ways to do the reduction:

If there is a big reduction to a small output, make a temporary array initialized to the reduction unit for each thread, then have each thread reduce into its temporary. When that is complete, combine the temporaries together. You can detect this case by observing that NpyIter_GetReduceBlockSizeFactor returns a large value, for instance half or a third of NpyIter_GetIterSize. You should also check that the output is small just to be sure.

If there are many small reductions to a big output, and the reduction dimensions are inner dimensions, NpyIter_GetReduceBlockSizeFactor will return a small number, and as long as the block size you choose for multithreading is NpyIter_GetReduceBlockSizeFactor(iter)*n for some n, the operation will be safe.

The bad case is when the a reduction dimension is the outermost loop in the iterator. For example, if you have a C-order array with shape (3,1000,1000), and you reduce on dimension 0, NpyIter_GetReduceBlockSizeFactor will return a size equal to NpyIter_GetIterSize for NPY_KEEPORDER or NPY_CORDER iteration orders. While it is bad for the CPU cache, perhaps in the future another order possibility could be provided, maybe NPY_REDUCEORDER, which pushes the reduction axes to the inner loop, but otherwise is the same as NPY_KEEPORDER.

npy_intp NpyIter_GetIterIndex(NpyIter *iter)

Gets the iterindex of the iterator, which is an index matching the iteration order of the iterator.

void NpyIter_GetIterIndexRange(NpyIter *iter, npy_intp *istart, npy_intp *iend)

Gets the iterindex sub-range that is being iterated. If NPY_ITER_RANGED was not specified, this always returns the range [0, NpyIter_IterSize(iter)).

int NpyIter_GotoIterIndex(NpyIter *iter, npy_intp iterindex)

Adjusts the iterator to point to the iterindex specified. The IterIndex is an index matching the iteration order of the iterator. Returns an error if the iterindex is out of bounds, buffering is enabled, or inner loop iteration is disabled.

Returns NPY_SUCCEED or NPY_FAIL.

int NpyIter_HasInnerLoop(NpyIter *iter

Returns 1 if the iterator handles the inner loop, or 0 if the caller needs to handle it. This is controlled by the constructor flag NPY_ITER_NO_INNER_ITERATION.

int NpyIter_HasCoords(NpyIter *iter)

Returns 1 if the iterator was created with the NPY_ITER_COORDS flag, 0 otherwise.

int NpyIter_HasIndex(NpyIter *iter)

Returns 1 if the iterator was created with the NPY_ITER_C_INDEX or NPY_ITER_F_INDEX flag, 0 otherwise.

int NpyIter_IsBuffered(NpyIter *iter)

Returns 1 if the iterator was created with the NPY_ITER_BUFFERED flag, 0 otherwise.

int NpyIter_IsGrowInner(NpyIter *iter)

Returns 1 if the iterator was created with the NPY_ITER_GROWINNER flag, 0 otherwise.

npy_intp NpyIter_GetBufferSize(NpyIter *iter)

If the iterator is buffered, returns the size of the buffer being used, otherwise returns 0.

npy_intp NpyIter_GetNDim(NpyIter *iter)

Returns the number of dimensions being iterated. If coordinates were not requested in the iterator constructor, this value may be smaller than the number of dimensions in the original objects.

npy_intp NpyIter_GetNIter(NpyIter *iter)

Returns the number of objects being iterated.

npy_intp *NpyIter_GetAxisStrideArray(NpyIter *iter, npy_intp axis)

Gets the array of strides for the specified axis. Requires that the iterator be tracking coordinates, and that buffering not be enabled.

This may be used when you want to match up operand axes in some fashion, then remove them with NpyIter_RemoveAxis to handle their processing manually. By calling this function before removing the axes, you can get the strides for the manual processing.

Returns NULL on error.

int NpyIter_GetShape(NpyIter *iter, npy_intp *outshape)

Returns the broadcast shape of the iterator in outshape. This can only be called on an iterator which supports coordinates.

Returns NPY_SUCCEED or NPY_FAIL.

PyArray_Descr **NpyIter_GetDescrArray(NpyIter *iter)

This gives back a pointer to the niter data type Descrs for the objects being iterated. The result points into iter, so the caller does not gain any references to the Descrs.

This pointer may be cached before the iteration loop, calling iternext will not change it.

PyObject **NpyIter_GetOperandArray(NpyIter *iter)

This gives back a pointer to the niter operand PyObjects that are being iterated. The result points into iter, so the caller does not gain any references to the PyObjects.

PyObject *NpyIter_GetIterView(NpyIter *iter, npy_intp i)

This gives back a reference to a new ndarray view, which is a view into the i-th object in the array NpyIter_GetOperandArray(), whose dimensions and strides match the internal optimized iteration pattern. A C-order iteration of this view is equivalent to the iterator’s iteration order.

For example, if an iterator was created with a single array as its input, and it was possible to rearrange all its axes and then collapse it into a single strided iteration, this would return a view that is a one-dimensional array.

void NpyIter_GetReadFlags(NpyIter *iter, char *outreadflags)

Fills niter flags. Sets outreadflags[i] to 1 if op[i] can be read from, and to 0 if not.

void NpyIter_GetWriteFlags(NpyIter *iter, char *outwriteflags)

Fills niter flags. Sets outwriteflags[i] to 1 if op[i] can be written to, and to 0 if not.

Functions For Iteration

NpyIter_IterNext_Fn NpyIter_GetIterNext(NpyIter *iter, char **errmsg)

Returns a function pointer for iteration. A specialized version of the function pointer may be calculated by this function instead of being stored in the iterator structure. Thus, to get good performance, it is required that the function pointer be saved in a variable rather than retrieved for each loop iteration.

Returns NULL if there is an error. If errmsg is non-NULL, no Python exception is set when NPY_FAIL is returned. Instead, *errmsg is set to an error message. When errmsg is non-NULL, the function may be safely called without holding the Python GIL.

The typical looping construct is as follows.:

NpyIter_IterNext_Fn iternext = NpyIter_GetIterNext(iter, NULL);
char **dataptr = NpyIter_GetDataPtrArray(iter);

do {
    /* use the addresses dataptr[0], ... dataptr[niter-1] */
} while(iternext(iter));

When NPY_ITER_NO_INNER_ITERATION is specified, the typical inner loop construct is as follows.:

NpyIter_IterNext_Fn iternext = NpyIter_GetIterNext(iter, NULL);
char **dataptr = NpyIter_GetDataPtrArray(iter);
npy_intp *stride = NpyIter_GetInnerStrideArray(iter);
npy_intp *size_ptr = NpyIter_GetInnerLoopSizePtr(iter), size;
npy_intp iiter, niter = NpyIter_GetNIter(iter);

do {
    size = *size_ptr;
    while (size--) {
        /* use the addresses dataptr[0], ... dataptr[niter-1] */
        for (iiter = 0; iiter < niter; ++iiter) {
            dataptr[iiter] += stride[iiter];
        }
    }
} while (iternext());

Observe that we are using the dataptr array inside the iterator, not copying the values to a local temporary. This is possible because when iternext() is called, these pointers will be overwritten with fresh values, not incrementally updated.

If a compile-time fixed buffer is being used (both flags NPY_ITER_BUFFERED and NPY_ITER_NO_INNER_ITERATION), the inner size may be used as a signal as well. The size is guaranteed to become zero when iternext() returns false, enabling the following loop construct. Note that if you use this construct, you should not pass NPY_ITER_GROWINNER as a flag, because it will cause larger sizes under some circumstances.:

/* The constructor should have buffersize passed as this value */
#define FIXED_BUFFER_SIZE 1024

NpyIter_IterNext_Fn iternext = NpyIter_GetIterNext(iter, NULL);
char **dataptr = NpyIter_GetDataPtrArray(iter);
npy_intp *stride = NpyIter_GetInnerStrideArray(iter);
npy_intp *size_ptr = NpyIter_GetInnerLoopSizePtr(iter), size;
npy_intp i, iiter, niter = NpyIter_GetNIter(iter);

/* One loop with a fixed inner size */
size = *size_ptr;
while (size == FIXED_BUFFER_SIZE) {
    /*
     * This loop could be manually unrolled by a factor
     * which divides into FIXED_BUFFER_SIZE
     */
    for (i = 0; i < FIXED_BUFFER_SIZE; ++i) {
        /* use the addresses dataptr[0], ... dataptr[niter-1] */
        for (iiter = 0; iiter < niter; ++iiter) {
            dataptr[iiter] += stride[iiter];
        }
    }
    iternext();
    size = *size_ptr;
}

/* Finish-up loop with variable inner size */
if (size > 0) do {
    size = *size_ptr;
    while (size--) {
        /* use the addresses dataptr[0], ... dataptr[niter-1] */
        for (iiter = 0; iiter < niter; ++iiter) {
            dataptr[iiter] += stride[iiter];
        }
    }
} while (iternext());

NpyIter_GetCoords_Fn NpyIter_GetGetCoords(NpyIter *iter, char **errmsg)

Returns a function pointer for getting the coordinates of the iterator. Returns NULL if the iterator does not support coordinates. It is recommended that this function pointer be cached in a local variable before the iteration loop.

Returns NULL if there is an error. If errmsg is non-NULL, no Python exception is set when NPY_FAIL is returned. Instead, *errmsg is set to an error message. When errmsg is non-NULL, the function may be safely called without holding the Python GIL.

char **NpyIter_GetDataPtrArray(NpyIter *iter)

This gives back a pointer to the niter data pointers. If NPY_ITER_NO_INNER_ITERATION was not specified, each data pointer points to the current data item of the iterator. If no inner iteration was specified, it points to the first data item of the inner loop.

This pointer may be cached before the iteration loop, calling iternext will not change it. This function may be safely called without holding the Python GIL.

npy_intp *NpyIter_GetIndexPtr(NpyIter *iter)

This gives back a pointer to the index being tracked, or NULL if no index is being tracked. It is only useable if one of the flags NPY_ITER_C_INDEX or NPY_ITER_F_INDEX were specified during construction.

When the flag NPY_ITER_NO_INNER_ITERATION is used, the code needs to know the parameters for doing the inner loop. These functions provide that information.

npy_intp *NpyIter_GetInnerStrideArray(NpyIter *iter)

Returns a pointer to an array of the niter strides, one for each iterated object, to be used by the inner loop.

This pointer may be cached before the iteration loop, calling iternext will not change it. This function may be safely called without holding the Python GIL.

npy_intp* NpyIter_GetInnerLoopSizePtr(NpyIter *iter)

Returns a pointer to the number of iterations the inner loop should execute.

This address may be cached before the iteration loop, calling iternext will not change it. The value itself may change during iteration, in particular if buffering is enabled. This function may be safely called without holding the Python GIL.

void NpyIter_GetInnerFixedStrideArray(NpyIter *iter, npy_intp *out_strides)

Gets an array of strides which are fixed, or will not change during the entire iteration. For strides that may change, the value NPY_MAX_INTP is placed in the stride.

Once the iterator is prepared for iteration (after a reset if NPY_DELAY_BUFALLOC was used), call this to get the strides which may be used to select a fast inner loop function. For example, if the stride is 0, that means the inner loop can always load its value into a variable once, then use the variable throughout the loop, or if the stride equals the itemsize, a contiguous version for that operand may be used.

This function may be safely called without holding the Python GIL.

Examples

A copy function using the iterator. The order parameter is used to control the memory layout of the allocated result.

If the input is a reference type, this function will fail. To fix this, the code must be changed to specially handle writeable references, and add NPY_ITER_WRITEABLE_REFERENCES to the flags.:

/* NOTE: This code has not been compiled/tested */
PyObject *CopyArray(PyObject *arr, NPY_ORDER order)
{
    NpyIter *iter;
    NpyIter_IterNext_Fn iternext;
    PyObject *op[2], *ret;
    npy_uint32 flags;
    npy_uint32 op_flags[2];
    npy_intp itemsize, *innersizeptr, innerstride;
    char **dataptrarray;

    /*
     * No inner iteration - inner loop is handled by CopyArray code
     */
    flags = NPY_ITER_NO_INNER_ITERATION;
    /*
     * Tell the constructor to automatically allocate the output.
     * The data type of the output will match that of the input.
     */
    op[0] = arr;
    op[1] = NULL;
    op_flags[0] = NPY_ITER_READONLY;
    op_flags[1] = NPY_ITER_WRITEONLY | NPY_ITER_ALLOCATE;

    /* Construct the iterator */
    iter = NpyIter_MultiNew(2, op, flags, order, NPY_NO_CASTING,
                            op_flags, NULL, 0, NULL);
    if (iter == NULL) {
        return NULL;
    }

    /*
     * Make a copy of the iternext function pointer and
     * a few other variables the inner loop needs.
     */
    iternext = NpyIter_GetIterNext(iter);
    innerstride = NpyIter_GetInnerStrideArray(iter)[0];
    itemsize = NpyIter_GetDescrArray(iter)[0]->elsize;
    /*
     * The inner loop size and data pointers may change during the
     * loop, so just cache the addresses.
     */
    innersizeptr = NpyIter_GetInnerLoopSizePtr(iter);
    dataptrarray = NpyIter_GetDataPtrArray(iter);

    /*
     * Note that because the iterator allocated the output,
     * it matches the iteration order and is packed tightly,
     * so we don't need to check it like the input.
     */
    if (innerstride == itemsize) {
        do {
            memcpy(dataptrarray[1], dataptrarray[0],
                                    itemsize * (*innersizeptr));
        } while (iternext(iter));
    } else {
        /* Should specialize this further based on item size... */
        npy_intp i;
        do {
            npy_intp size = *innersizeptr;
            char *src = dataaddr[0], *dst = dataaddr[1];
            for(i = 0; i < size; i++, src += innerstride, dst += itemsize) {
                memcpy(dst, src, itemsize);
            }
        } while (iternext(iter));
    }

    /* Get the result from the iterator object array */
    ret = NpyIter_GetOperandArray(iter)[1];
    Py_INCREF(ret);

    if (NpyIter_Deallocate(iter) != NPY_SUCCEED) {
        Py_DECREF(ret);
        return NULL;
    }

    return ret;
}

Python Lambda UFunc Example

To show how the new iterator allows the definition of efficient UFunc-like functions in pure Python, we demonstrate the function luf, which makes a lambda-expression act like a UFunc. This is very similar to the numexpr library, but only takes a few lines of code.

First, here is the definition of the luf function.:

def luf(lamdaexpr, *args, **kwargs):
    """Lambda UFunc

        e.g.
        c = luf(lambda i,j:i+j, a, b, order='K',
                            casting='safe', buffersize=8192)

        c = np.empty(...)
        luf(lambda i,j:i+j, a, b, out=c, order='K',
                            casting='safe', buffersize=8192)
    """

    nargs = len(args)
    op = args + (kwargs.get('out',None),)
    it = np.nditer(op, ['buffered','no_inner_iteration'],
            [['readonly','nbo_aligned']]*nargs +
                            [['writeonly','allocate','no_broadcast']],
            order=kwargs.get('order','K'),
            casting=kwargs.get('casting','safe'),
            buffersize=kwargs.get('buffersize',0))
    while not it.finished:
        it[-1] = lamdaexpr(*it[:-1])
        it.iternext()

    return it.operands[-1]

Then, by using luf instead of straight Python expressions, we can gain some performance from better cache behavior.:

In [2]: a = np.random.random((50,50,50,10))
In [3]: b = np.random.random((50,50,1,10))
In [4]: c = np.random.random((50,50,50,1))

In [5]: timeit 3*a+b-(a/c)
1 loops, best of 3: 138 ms per loop

In [6]: timeit luf(lambda a,b,c:3*a+b-(a/c), a, b, c)
10 loops, best of 3: 60.9 ms per loop

In [7]: np.all(3*a+b-(a/c) == luf(lambda a,b,c:3*a+b-(a/c), a, b, c))
Out[7]: True

Python Addition Example

The iterator has been mostly written and exposed to Python. To see how it behaves, let’s see what we can do with the np.add ufunc. Even without changing the core of NumPy, we will be able to use the iterator to make a faster add function.

The Python exposure supplies two iteration interfaces, one which follows the Python iterator protocol, and another which mirrors the C-style do-while pattern. The native Python approach is better in most cases, but if you need the iterator’s coordinates or index, use the C-style pattern.

Here is how we might write an iter_add function, using the Python iterator protocol.:

def iter_add_py(x, y, out=None):
    addop = np.add

    it = np.nditer([x,y,out], [],
                [['readonly'],['readonly'],['writeonly','allocate']])

    for (a, b, c) in it:
        addop(a, b, c)

    return it.operands[2]

Here is the same function, but following the C-style pattern.:

def iter_add(x, y, out=None):
    addop = np.add

    it = np.nditer([x,y,out], [],
                [['readonly'],['readonly'],['writeonly','allocate']])

    while not it.finished:
        addop(it[0], it[1], it[2])
        it.iternext()

    return it.operands[2]

Some noteworthy points about this function:

  • Cache np.add as a local variable to reduce namespace lookups
  • Inputs are readonly, output is writeonly, and will be allocated automatically if it is None.
  • Uses np.add’s out parameter to avoid an extra copy.

Let’s create some test variables, and time this function as well as the built-in np.add.:

In [1]: a = np.arange(1000000,dtype='f4').reshape(100,100,100)
In [2]: b = np.arange(10000,dtype='f4').reshape(1,100,100)
In [3]: c = np.arange(10000,dtype='f4').reshape(100,100,1)

In [4]: timeit iter_add(a, b)
1 loops, best of 3: 7.03 s per loop

In [5]: timeit np.add(a, b)
100 loops, best of 3: 6.73 ms per loop

At a thousand times slower, this is clearly not very good. One feature of the iterator, designed to help speed up the inner loops, is the flag no_inner_iteration. This is the same idea as the old iterator’s PyArray_IterAllButAxis, but slightly smarter. Let’s modify iter_add to use this feature.:

def iter_add_noinner(x, y, out=None):
    addop = np.add

    it = np.nditer([x,y,out], ['no_inner_iteration'],
                [['readonly'],['readonly'],['writeonly','allocate']])

    for (a, b, c) in it:
        addop(a, b, c)

    return it.operands[2]

The performance improves dramatically.:

In[6]: timeit iter_add_noinner(a, b)
100 loops, best of 3: 7.1 ms per loop

The performance is basically as good as the built-in function! It turns out this is because the iterator was able to coalesce the last two dimensions, resulting in 100 adds of 10000 elements each. If the inner loop doesn’t become as large, the performance doesn’t improve as dramatically. Let’s use c instead of b to see how this works.:

In[7]: timeit iter_add_noinner(a, c)
10 loops, best of 3: 76.4 ms per loop

It’s still a lot better than seven seconds, but still over ten times worse than the built-in function. Here, the inner loop has 100 elements, and it’s iterating 10000 times. If we were coding in C, our performance would already be as good as the built-in performance, but in Python there is too much overhead.

This leads us to another feature of the iterator, its ability to give us views of the iterated memory. The views it gives us are structured so that processing them in C-order, like the built-in NumPy code does, gives the same access order as the iterator itself. Effectively, we are using the iterator to solve for a good memory access pattern, then using other NumPy machinery to efficiently execute it. Let’s modify iter_add once again.:

def iter_add_itview(x, y, out=None):
    it = np.nditer([x,y,out], [],
                [['readonly'],['readonly'],['writeonly','allocate']])

    (a, b, c) = it.itviews
    np.add(a, b, c)

    return it.operands[2]

Now the performance pretty closely matches the built-in function’s.:

In [8]: timeit iter_add_itview(a, b)
100 loops, best of 3: 6.18 ms per loop

In [9]: timeit iter_add_itview(a, c)
100 loops, best of 3: 6.69 ms per loop

Let us now step back to a case similar to the original motivation for the new iterator. Here are the same calculations in Fortran memory order instead Of C memory order.:

In [10]: a = np.arange(1000000,dtype='f4').reshape(100,100,100).T
In [12]: b = np.arange(10000,dtype='f4').reshape(100,100,1).T
In [11]: c = np.arange(10000,dtype='f4').reshape(1,100,100).T

In [39]: timeit np.add(a, b)
10 loops, best of 3: 34.3 ms per loop

In [41]: timeit np.add(a, c)
10 loops, best of 3: 31.6 ms per loop

In [44]: timeit iter_add_itview(a, b)
100 loops, best of 3: 6.58 ms per loop

In [43]: timeit iter_add_itview(a, c)
100 loops, best of 3: 6.33 ms per loop

As you can see, the performance of the built-in function dropped significantly, but our newly-written add function maintained essentially the same performance. As one final test, let’s try several adds chained together.:

In [4]: timeit np.add(np.add(np.add(a,b), c), a)
1 loops, best of 3: 99.5 ms per loop

In [9]: timeit iter_add_itview(iter_add_itview(iter_add_itview(a,b), c), a)
10 loops, best of 3: 29.3 ms per loop

Also, just to check that it’s doing the same thing,:

In [22]: np.all(
   ....: iter_add_itview(iter_add_itview(iter_add_itview(a,b), c), a) ==
   ....: np.add(np.add(np.add(a,b), c), a)
   ....: )

Out[22]: True

Image Compositing Example Revisited

For motivation, we had an example that did an ‘over’ composite operation on two images. Now let’s see how we can write the function with the new iterator.

Here is one of the original functions, for reference, and some random image data.:

In [5]: rand1 = np.random.random_sample(1080*1920*4).astype(np.float32)
In [6]: rand2 = np.random.random_sample(1080*1920*4).astype(np.float32)
In [7]: image1 = rand1.reshape(1080,1920,4).swapaxes(0,1)
In [8]: image2 = rand2.reshape(1080,1920,4).swapaxes(0,1)

In [3]: def composite_over(im1, im2):
  ....:     ret = (1-im1[:,:,-1])[:,:,np.newaxis]*im2
  ....:     ret += im1
  ....:     return ret

In [4]: timeit composite_over(image1,image2)
1 loops, best of 3: 1.39 s per loop

Here’s the same function, rewritten to use a new iterator. Note how easy it was to add an optional output parameter.:

In [5]: def composite_over_it(im1, im2, out=None, buffersize=4096):
  ....:     it = np.nditer([im1, im1[:,:,-1], im2, out],
  ....:                     ['buffered','no_inner_iteration'],
  ....:                     [['readonly']]*3+[['writeonly','allocate']],
  ....:                     op_axes=[None,[0,1,np.newaxis],None,None],
  ....:                     buffersize=buffersize)
  ....:     while not it.finished:
  ....:         np.multiply(1-it[1], it[2], it[3])
  ....:         it[3] += it[0]
  ....:         it.iternext()
  ....:     return it.operands[3]

In [6]: timeit composite_over_it(image1, image2)
1 loops, best of 3: 197 ms per loop

A big speed improvement, over even the best previous attempt using straight NumPy and a C-order array! By playing with the buffer size, we can see how the speed improves until we hit the limits of the CPU cache in the inner loop.:

In [7]: timeit composite_over_it(image1, image2, buffersize=2**7)
1 loops, best of 3: 1.23 s per loop

In [8]: timeit composite_over_it(image1, image2, buffersize=2**8)
1 loops, best of 3: 699 ms per loop

In [9]: timeit composite_over_it(image1, image2, buffersize=2**9)
1 loops, best of 3: 418 ms per loop

In [10]: timeit composite_over_it(image1, image2, buffersize=2**10)
1 loops, best of 3: 287 ms per loop

In [11]: timeit composite_over_it(image1, image2, buffersize=2**11)
1 loops, best of 3: 225 ms per loop

In [12]: timeit composite_over_it(image1, image2, buffersize=2**12)
1 loops, best of 3: 194 ms per loop

In [13]: timeit composite_over_it(image1, image2, buffersize=2**13)
1 loops, best of 3: 180 ms per loop

In [14]: timeit composite_over_it(image1, image2, buffersize=2**14)
1 loops, best of 3: 192 ms per loop

In [15]: timeit composite_over_it(image1, image2, buffersize=2**15)
1 loops, best of 3: 280 ms per loop

In [16]: timeit composite_over_it(image1, image2, buffersize=2**16)
1 loops, best of 3: 328 ms per loop

In [17]: timeit composite_over_it(image1, image2, buffersize=2**17)
1 loops, best of 3: 345 ms per loop

And finally, to double check that it’s working, we can compare the two functions.:

In [18]: np.all(composite_over(image1, image2) ==
    ...:        composite_over_it(image1, image2))
Out[18]: True

Image Compositing With NumExpr

As a test of the iterator, numexpr has been enhanced to allow use of the iterator instead of its internal broadcasting code. First, let’s implement the composite operation with numexpr.:

In [22]: def composite_over_ne(im1, im2, out=None):
   ....:     ima = im1[:,:,-1][:,:,np.newaxis]
   ....:     return ne.evaluate("im1+(1-ima)*im2")

In [23]: timeit composite_over_ne(image1,image2)
1 loops, best of 3: 1.25 s per loop

This beats the straight NumPy operation, but isn’t very good. Switching to the iterator version of numexpr, we get a big improvement over the straight Python function using the iterator. Note that this is on a dual core machine.:

In [29]: def composite_over_ne_it(im1, im2, out=None):
   ....:     ima = im1[:,:,-1][:,:,np.newaxis]
   ....:     return ne.evaluate_iter("im1+(1-ima)*im2")

In [30]: timeit composite_over_ne_it(image1,image2)
10 loops, best of 3: 67.2 ms per loop

In [31]: ne.set_num_threads(1)
In [32]: timeit composite_over_ne_it(image1,image2)
10 loops, best of 3: 91.1 ms per loop


A Simple File Format for NumPy Arrays

  • Numpy Enhancement Proposals
  • next
  • previous

Table Of Contents

  • A Simple File Format for NumPy Arrays
    • Abstract
    • Rationale
    • Use Cases
    • Requirements
    • Format Specification: Version 1.0
    • Conventions
    • Alternatives
    • Implementation
    • References
    • Copyright

Previous topic

Optimizing Iterator/UFunc Performance

Next topic

Missing Data Functionality in NumPy

A Simple File Format for NumPy Arrays

Author: Robert Kern <robert.kern@gmail.com> Status: Draft Created: 20-Dec-2007

Abstract

We propose a standard binary file format (NPY) for persisting a single arbitrary NumPy array on disk. The format stores all of the shape and dtype information necessary to reconstruct the array correctly even on another machine with a different architecture. The format is designed to be as simple as possible while achieving its limited goals. The implementation is intended to be pure Python and distributed as part of the main numpy package.

Rationale

A lightweight, omnipresent system for saving NumPy arrays to disk is a frequent need. Python in general has pickle [1] for saving most Python objects to disk. This often works well enough with NumPy arrays for many purposes, but it has a few drawbacks:

  • Dumping or loading a pickle file require the duplication of the data in memory. For large arrays, this can be a showstopper.
  • The array data is not directly accessible through memory-mapping. Now that numpy has that capability, it has proved very useful for loading large amounts of data (or more to the point: avoiding loading large amounts of data when you only need a small part).

Both of these problems can be addressed by dumping the raw bytes to disk using ndarray.tofile() and numpy.fromfile(). However, these have their own problems:

  • The data which is written has no information about the shape or dtype of the array.
  • It is incapable of handling object arrays.

The NPY file format is an evolutionary advance over these two approaches. Its design is mostly limited to solving the problems with pickles and tofile()/fromfile(). It does not intend to solve more complicated problems for which more complicated formats like HDF5 [2] are a better solution.

Use Cases

  • Neville Newbie has just started to pick up Python and NumPy. He has not installed many packages, yet, nor learned the standard library, but he has been playing with NumPy at the interactive prompt to do small tasks. He gets a result that he wants to save.
  • Annie Analyst has been using large nested record arrays to represent her statistical data. She wants to convince her R-using colleague, David Doubter, that Python and NumPy are awesome by sending him her analysis code and data. She needs the data to load at interactive speeds. Since David does not use Python usually, needing to install large packages would turn him off.
  • Simon Seismologist is developing new seismic processing tools. One of his algorithms requires large amounts of intermediate data to be written to disk. The data does not really fit into the industry-standard SEG-Y schema, but he already has a nice record-array dtype for using it internally.
  • Polly Parallel wants to split up a computation on her multicore machine as simply as possible. Parts of the computation can be split up among different processes without any communication between processes; they just need to fill in the appropriate portion of a large array with their results. Having several child processes memory-mapping a common array is a good way to achieve this.

Requirements

The format MUST be able to:

  • Represent all NumPy arrays including nested record arrays and object arrays.
  • Represent the data in its native binary form.
  • Be contained in a single file.
  • Support Fortran-contiguous arrays directly.
  • Store all of the necessary information to reconstruct the array including shape and dtype on a machine of a different architecture. Both little-endian and big-endian arrays must be supported and a file with little-endian numbers will yield a little-endian array on any machine reading the file. The types must be described in terms of their actual sizes. For example, if a machine with a 64-bit C “long int” writes out an array with “long ints”, a reading machine with 32-bit C “long ints” will yield an array with 64-bit integers.
  • Be reverse engineered. Datasets often live longer than the programs that created them. A competent developer should be able to create a solution in his preferred programming language to read most NPY files that he has been given without much documentation.
  • Allow memory-mapping of the data.
  • Be read from a filelike stream object instead of an actual file. This allows the implementation to be tested easily and makes the system more flexible. NPY files can be stored in ZIP files and easily read from a ZipFile object.
  • Store object arrays. Since general Python objects are complicated and can only be reliably serialized by pickle (if at all), many of the other requirements are waived for files containing object arrays. Files with object arrays do not have to be mmapable since that would be technically impossible. We cannot expect the pickle format to be reverse engineered without knowledge of pickle. However, one should at least be able to read and write object arrays with the same generic interface as other arrays.
  • Be read and written using APIs provided in the numpy package itself without any other libraries. The implementation inside numpy may be in C if necessary.

The format explicitly does not need to:

  • Support multiple arrays in a file. Since we require filelike objects to be supported, one could use the API to build an ad hoc format that supported multiple arrays. However, solving the general problem and use cases is beyond the scope of the format and the API for numpy.
  • Fully handle arbitrary subclasses of numpy.ndarray. Subclasses will be accepted for writing, but only the array data will be written out. A regular numpy.ndarray object will be created upon reading the file. The API can be used to build a format for a particular subclass, but that is out of scope for the general NPY format.

Format Specification: Version 1.0

The first 6 bytes are a magic string: exactly “x93NUMPY”.

The next 1 byte is an unsigned byte: the major version number of the file format, e.g. x01.

The next 1 byte is an unsigned byte: the minor version number of the file format, e.g. x00. Note: the version of the file format is not tied to the version of the numpy package.

The next 2 bytes form a little-endian unsigned short int: the length of the header data HEADER_LEN.

The next HEADER_LEN bytes form the header data describing the array’s format. It is an ASCII string which contains a Python literal expression of a dictionary. It is terminated by a newline (‘n’) and padded with spaces (‘x20’) to make the total length of the magic string + 4 + HEADER_LEN be evenly divisible by 16 for alignment purposes.

The dictionary contains three keys:

“descr” : dtype.descr
An object that can be passed as an argument to the numpy.dtype() constructor to create the array’s dtype.
“fortran_order” : bool
Whether the array data is Fortran-contiguous or not. Since Fortran-contiguous arrays are a common form of non-C-contiguity, we allow them to be written directly to disk for efficiency.
“shape” : tuple of int
The shape of the array.

For repeatability and readability, this dictionary is formatted using pprint.pformat() so the keys are in alphabetic order.

Following the header comes the array data. If the dtype contains Python objects (i.e. dtype.hasobject is True), then the data is a Python pickle of the array. Otherwise the data is the contiguous (either C- or Fortran-, depending on fortran_order) bytes of the array. Consumers can figure out the number of bytes by multiplying the number of elements given by the shape (noting that shape=() means there is 1 element) by dtype.itemsize.

Conventions

We recommend using the ”.npy” extension for files following this format. This is by no means a requirement; applications may wish to use this file format but use an extension specific to the application. In the absence of an obvious alternative, however, we suggest using ”.npy”.

For a simple way to combine multiple arrays into a single file, one can use ZipFile to contain multiple ”.npy” files. We recommend using the file extension ”.npz” for these archives.

Alternatives

The author believes that this system (or one along these lines) is about the simplest system that satisfies all of the requirements. However, one must always be wary of introducing a new binary format to the world.

HDF5 [2] is a very flexible format that should be able to represent all of NumPy’s arrays in some fashion. It is probably the only widely-used format that can faithfully represent all of NumPy’s array features. It has seen substantial adoption by the scientific community in general and the NumPy community in particular. It is an excellent solution for a wide variety of array storage problems with or without NumPy.

HDF5 is a complicated format that more or less implements a hierarchical filesystem-in-a-file. This fact makes satisfying some of the Requirements difficult. To the author’s knowledge, as of this writing, there is no application or library that reads or writes even a subset of HDF5 files that does not use the canonical libhdf5 implementation. This implementation is a large library that is not always easy to build. It would be infeasible to include it in numpy.

It might be feasible to target an extremely limited subset of HDF5. Namely, there would be only one object in it: the array. Using contiguous storage for the data, one should be able to implement just enough of the format to provide the same metadata that the proposed format does. One could still meet all of the technical requirements like mmapability.

We would accrue a substantial benefit by being able to generate files that could be read by other HDF5 software. Furthermore, by providing the first non-libhdf5 implementation of HDF5, we would be able to encourage more adoption of simple HDF5 in applications where it was previously infeasible because of the size of the library. The basic work may encourage similar dead-simple implementations in other languages and further expand the community.

The remaining concern is about reverse engineerability of the format. Even the simple subset of HDF5 would be very difficult to reverse engineer given just a file by itself. However, given the prominence of HDF5, this might not be a substantial concern.

In conclusion, we are going forward with the design laid out in this document. If someone writes code to handle the simple subset of HDF5 that would be useful to us, we may consider a revision of the file format.

Implementation

The current implementation is included in the 1.0.5 release of numpy.

http://github.com/numpy/numpy/blob/v1.5.0/numpy/lib/format.py

Specifically, the file format.py in this directory implements the format as described here.

References

[1] http://docs.python.org/lib/module-pickle.html

[2] http://hdf.ncsa.uiuc.edu/products/hdf5/index.html

Copyright

This document has been placed in the public domain.


Missing Data Functionality in NumPy

  • Numpy Enhancement Proposals
  • next
  • previous

Table Of Contents

  • Missing Data Functionality in NumPy
    • Table of Contents
    • Abstract
    • Definition of Missing Data
      • Unknown Yet Existing Data (NA)
      • Data That Doesn’t Exist Or Is Being Skipped (IGNORE)
    • Implementation Techniques For Missing Values
      • Bit Patterns Signalling Missing Values (bitpattern)
      • Boolean Masks Signalling Missing Values (mask)
    • Glossary of Terms
    • Missing Values as Seen in Python
      • Working With Missing Values
      • Accessing a Boolean Mask
      • Creating NA-Masked Arrays
      • NA-Masks When Constructing From Lists
      • Mask Implementation Details
      • New ndarray Methods
      • Element-wise UFuncs With Missing Values
      • Reduction UFuncs With Missing Values
      • Parameterized NA Data Types
      • Future Expansion to multi-NA Payloads
      • Differences with numpy.ma
      • Boolean Indexing
      • PEP 3118
      • Cython
      • Hard Masks
      • Shared Masks
      • Interaction With Pre-existing C API Usage
        • Numpy Documentation - How to extend NumPy
        • Tutorial From Cython Website
        • Numerical Python - JPL website
    • C Implementation Details
      • Mask Binary Format
    • C Iterator API Changes: Iteration With Masks
      • Iterator Mask Features
      • Iterator NA-array Features
    • Rejected Alternative
      • Parameterized Data Type Which Adds Additional Memory for the NA Flag
    • Acknowledgments

Previous topic

A Simple File Format for NumPy Arrays

Next topic

Cleaning the math configuration of numpy.core

Missing Data Functionality in NumPy

Author: | Mark Wiebe <mwwiebe@gmail.com>
Copyright: | Copyright 2011 by Enthought, Inc
License: | CC By-SA 3.0 (http://creativecommons.org/licenses/by-sa/3.0/)
Date: | 2011-06-23

Table of Contents

Contents

  • Missing Data Functionality in NumPy
    • Table of Contents
    • Abstract
    • Definition of Missing Data
      • Unknown Yet Existing Data (NA)
      • Data That Doesn’t Exist Or Is Being Skipped (IGNORE)
    • Implementation Techniques For Missing Values
      • Bit Patterns Signalling Missing Values (bitpattern)
      • Boolean Masks Signalling Missing Values (mask)
    • Glossary of Terms
    • Missing Values as Seen in Python
      • Working With Missing Values
      • Accessing a Boolean Mask
      • Creating NA-Masked Arrays
      • NA-Masks When Constructing From Lists
      • Mask Implementation Details
      • New ndarray Methods
      • Element-wise UFuncs With Missing Values
      • Reduction UFuncs With Missing Values
      • Parameterized NA Data Types
      • Future Expansion to multi-NA Payloads
      • Differences with numpy.ma
      • Boolean Indexing
      • PEP 3118
      • Cython
      • Hard Masks
      • Shared Masks
      • Interaction With Pre-existing C API Usage
        • Numpy Documentation - How to extend NumPy
        • Tutorial From Cython Website
        • Numerical Python - JPL website
    • C Implementation Details
      • Mask Binary Format
    • C Iterator API Changes: Iteration With Masks
      • Iterator Mask Features
      • Iterator NA-array Features
    • Rejected Alternative
      • Parameterized Data Type Which Adds Additional Memory for the NA Flag
    • Acknowledgments

Abstract

Users interested in dealing with missing data within NumPy are generally pointed to the masked array subclass of the ndarray, known as ‘numpy.ma’. This class has a number of users who depend strongly on its capabilities, but people who are accustomed to the deep integration of the missing data placeholder “NA” in the R project and others who find the programming interface challenging or inconsistent tend not to use it.

This NEP proposes to integrate a mask-based missing data solution into NumPy, with an additional bitpattern-based missing data solution that can be implemented concurrently or later integrating seamlessly with the mask-based solution.

The mask-based solution and the bitpattern-based solutions in this proposal offer the exact same missing value abstraction, with several differences in performance, memory overhead, and flexibility.

The mask-based solution is more flexible, supporting all behaviors of the bitpattern-based solution, but leaving the hidden values untouched whenever an element is masked.

The bitpattern-based solution requires less memory, is bit-level compatible with the 64-bit floating point representation used in R, but does not preserve the hidden values and in fact requires stealing at least one bit pattern from the underlying dtype to represent the missing value NA.

Both solutions are generic in the sense that they can be used with custom data types very easily, with no effort in the case of the masked solution, and with the requirement that a bit pattern to sacrifice be chosen in the case of the bitpattern solution.

Definition of Missing Data

In order to be able to develop an intuition about what computation will be done by various NumPy functions, a consistent conceptual model of what a missing element means must be applied. Ferreting out the behaviors people need or want when they are working with “missing data” seems to be tricky, but I believe that it boils down to two different ideas, each of which is internally self-consistent.

One of them, the “unknown yet existing data” interpretation, can be applied rigorously to all computations, while the other makes sense for some statistical operations like standard deviation but not for linear algebra operations like matrix product. Thus, making “unknown yet existing data” be the default interpretation is superior, providing a consistent model across all computations, and for those operations where the other interpretation makes sense, an optional parameter “skipna=” can be added.

For people who want the other interpretation to be default, a mechanism proposed elsewhere for customizing subclass ufunc behavior with a _numpy_ufunc_ member function would allow a subclass with a different default to be created.

Unknown Yet Existing Data (NA)

This is the approach taken in the R project, defining a missing element as something which does have a valid value which isn’t known, or is NA (not available). This proposal adopts this behavior as as the default for all operations involving missing values.

In this interpretation, nearly any computation with a missing input produces a missing output. For example, ‘sum(a)’ would produce a missing value if ‘a’ contained just one missing element. When the output value does not depend on one of the inputs, it is reasonable to output a value that is not NA, such as logical_and(NA, False) == False.

Some more complex arithmetic operations, such as matrix products, are well defined with this interpretation, and the result should be the same as if the missing values were NaNs. Actually implementing such things to the theoretical limit is probably not worth it, and in many cases either raising an exception or returning all missing values may be preferred to doing precise calculations.

Data That Doesn’t Exist Or Is Being Skipped (IGNORE)

Another useful interpretation is that the missing elements should be treated as if they didn’t exist in the array, and the operation should do its best to interpret what that means according to the data that’s left. In this case, ‘mean(a)’ would compute the mean of just the values that are available, adjusting both the sum and count it uses based on which values are missing. To be consistent, the mean of an array of all missing values must produce the same result as the mean of a zero-sized array without missing value support.

This kind of data can arise when conforming sparsely sampled data into a regular sampling pattern, and is a useful interpretation to use when attempting to get best-guess answers for many statistical queries.

In R, many functions take a parameter “na.rm=T” which means to treat the data as if the NA values are not part of the data set. This proposal defines a standard parameter “skipna=True” for this same purpose.

Implementation Techniques For Missing Values

In addition to there being two different interpretations of missing values, there are two different commonly used implementation techniques for missing values. While there are some differing default behaviors between existing implementations of the techniques, I believe that the design choices made in a new implementation must be made based on their merits, not by rote copying of previous designs.

Both masks and bitpatterns have different strong and weak points, depending on the application context. This NEP thus proposes to implement both. To enable the writing of generic “missing value” code which does not have to worry about whether the arrays it is using have taken one or the other approach, the missing value semantics will be identical for the two implementations.

Bit Patterns Signalling Missing Values (bitpattern)

One or more patterns of bits, for example a NaN with a particular payload, are chosen to represent the missing value placeholder NA.

A consequence of this approach is that assigning NA changes the bits holding the value, so that value is gone.

Additionally, for some types such as integers, a good and proper value must be sacrificed to enable this functionality.

Boolean Masks Signalling Missing Values (mask)

A mask is a parallel array of booleans, either one byte per element or one bit per element, allocated alongside the existing array data. In this NEP, the convention is chosen that True means the element is valid (unmasked), and False means the element is NA.

By taking care when writing any C algorithm that works with values and masks together, it is possible to have the memory for a value that is masked never be written to. This feature allows multiple simultaneous views of the same data with different choices of what is missing, a feature requested by many people on the mailing list.

This approach places no limitations on the values of the underlying data type, it may take on any binary pattern without affecting the NA behavior.

Glossary of Terms

Because the above discussions of the different concepts and their relationships are tricky to understand, here are more succinct definitions of the terms used in this NEP.

NA (Not Available/Propagate)
A placeholder for a value which is unknown to computations. That value may be temporarily hidden with a mask, may have been lost due to hard drive corruption, or gone for any number of reasons. For sums and products this means to produce NA if any of the inputs are NA. This is the same as NA in the R project.
IGNORE (Ignore/Skip)
A placeholder which should be treated by computations as if no value does or could exist there. For sums, this means act as if the value were zero, and for products, this means act as if the value were one. It’s as if the array were compressed in some fashion to not include that element.
bitpattern
A technique for implementing either NA or IGNORE, where a particular set of bit patterns are chosen from all the possible bit patterns of the value’s data type to signal that the element is NA or IGNORE.
mask
A technique for implementing either NA or IGNORE, where a boolean or enum array parallel to the data array is used to signal which elements are NA or IGNORE.
numpy.ma
The existing implementation of a particular form of masked arrays, which is part of the NumPy codebase.
Python API
All the interface mechanisms that are exposed to Python code for using missing values in NumPy. This API is designed to be Pythonic and fit into the way NumPy works as much as possible.
C API
All the implementation mechanisms exposed for CPython extensions written in C that want to support NumPy missing value support. This API is designed to be as natural as possible in C, and is usually prioritizes flexibility and high performance.

Missing Values as Seen in Python

Working With Missing Values

NumPy will gain a global singleton called numpy.NA, similar to None, but with semantics reflecting its status as a missing value. In particular, trying to treat it as a boolean will raise an exception, and comparisons with it will produce numpy.NA instead of True or False. These basics are adopted from the behavior of the NA value in the R project. To dig deeper into the ideas, http://en.wikipedia.org/wiki/Ternary_logic#Kleene_logic provides a starting point.

For example,:

>>> np.array([1.0, 2.0, np.NA, 7.0], maskna=True)
array([1., 2., NA, 7.], maskna=True)
>>> np.array([1.0, 2.0, np.NA, 7.0], dtype='NA')
array([1., 2., NA, 7.], dtype='NA[<f8]')
>>> np.array([1.0, 2.0, np.NA, 7.0], dtype='NA[f4]')
array([1., 2., NA, 7.], dtype='NA[<f4]')

produce arrays with values [1.0, 2.0, <inaccessible>, 7.0] / mask [Exposed, Exposed, Hidden, Exposed], and values [1.0, 2.0, <NA bitpattern>, 7.0] for the masked and NA dtype versions respectively.

The np.NA singleton may accept a dtype= keyword parameter, indicating that it should be treated as an NA of a particular data type. This is also a mechanism for preserving the dtype in a NumPy scalar-like fashion. Here’s what this looks like:

>>> np.sum(np.array([1.0, 2.0, np.NA, 7.0], maskna=True))
NA(dtype='<f8')
>>> np.sum(np.array([1.0, 2.0, np.NA, 7.0], dtype='NA[f8]'))
NA(dtype='NA[<f8]')

Assigning a value to an array always causes that element to not be NA, transparently unmasking it if necessary. Assigning numpy.NA to the array masks that element or assigns the NA bitpattern for the particular dtype. In the mask-based implementation, the storage behind a missing value may never be accessed in any way, other than to unmask it by assigning its value.

To test if a value is missing, the function “np.isna(arr[0])” will be provided. One of the key reasons for the NumPy scalars is to allow their values into dictionaries.

All operations which write to masked arrays will not affect the value unless they also unmask that value. This allows the storage behind masked elements to still be relied on if they are still accessible from another view which doesn’t have them masked. For example, the following was run on the missingdata work-in-progress branch:

>>> a = np.array([1,2])
>>> b = a.view(maskna=True)
>>> b
array([1, 2], maskna=True)
>>> b[0] = np.NA
>>> b
array([NA, 2], maskna=True)
>>> a
array([1, 2])
>>> # The underlying number 1 value in 'a[0]' was untouched

Copying values between the mask-based implementation and the bitpattern implementation will transparently do the correct thing, turning the bitpattern into a masked value, or a masked value into the bitpattern where appropriate. The one exception is if a valid value in a masked array happens to have the NA bitpattern, copying this value to the NA form of the dtype will cause it to become NA as well.

When operations are done between arrays with NA dtypes and masked arrays, the result will be masked arrays. This is because in some cases the NA dtypes cannot represent all the values in the masked array, so going to masked arrays is the only way to preserve all aspects of the data.

If np.NA or masked values are copied to an array without support for missing values enabled, an exception will be raised. Adding a mask to the target array would be problematic, because then having a mask would be a “viral” property consuming extra memory and reducing performance in unexpected ways.

By default, the string “NA” will be used to represent missing values in str and repr outputs. A global configuration will allow this to be changed, exactly extending the way nan and inf are treated. The following works in the current draft implementation:

>>> a = np.arange(6, maskna=True)
>>> a[3] = np.NA
>>> a
array([0, 1, 2, NA, 4, 5], maskna=True)
>>> np.set_printoptions(nastr='blah')
>>> a
array([0, 1, 2, blah, 4, 5], maskna=True)

For floating point numbers, Inf and NaN are separate concepts from missing values. If a division by zero occurs in an array with default missing value support, an unmasked Inf or NaN will be produced. To mask those values, a further ‘a[np.logical_not(a.isfinite(a)] = np.NA’ can achieve that. For the bitpattern approach, the parameterized dtype(‘NA[f8,InfNan]’) described in a later section can be used to get these semantics without the extra manipulation.

A manual loop through a masked array like:

>>> a = np.arange(5., maskna=True)
>>> a[3] = np.NA
>>> a
array([ 0.,  1.,  2., NA,  4.], maskna=True)
>>> for i in range(len(a)):
...     a[i] = np.log(a[i])
...
__main__:2: RuntimeWarning: divide by zero encountered in log
>>> a
array([       -inf,  0.        ,  0.69314718, NA,  1.38629436], maskna=True)

works even with masked values, because ‘a[i]’ returns an NA object with a data type associated, that can be treated properly by the ufuncs.

Accessing a Boolean Mask

The mask used to implement missing data in the masked approach is not accessible from Python directly. This is partially due to differing opinions on whether True in the mask should mean “missing” or “not missing” Additionally, exposing the mask directly would preclude a potential space optimization, where a bit-level instead of a byte-level mask is used to get a factor of eight memory usage improvement.

To access a mask directly, there are two functions provided. They work equivalently for both arrays with masks and NA bit patterns, so they are specified in terms of NA and available values instead of masked and unmasked values. The functions are ‘np.isna’ and ‘np.isavail’, which test for NA or available values respectively.

Creating NA-Masked Arrays

The usual way to create an array with an NA mask is to pass the keyword parameter maskna=True to one of the constructors. Most functions that create a new array take this parameter, and produce an NA-masked array with all its elements exposed when the parameter is set to True.

There are also two flags which indicate and control the nature of the mask used in masked arrays. These flags can be used to add a mask, or ensure the mask isn’t a view into another array’s mask.

First is ‘arr.flags.maskna’, which is True for all masked arrays and may be set to True to add a mask to an array which does not have one.

Second is ‘arr.flags.ownmaskna’, which is True if the array owns the memory to the mask, and False if the array has no mask, or has a view into the mask of another array. If this is set to True in a masked array, the array will create a copy of the mask so that further modifications to the mask will not affect the original mask from which the view was taken.

NA-Masks When Constructing From Lists

The initial design of NA-mask construction was to make all construction fully explicit. This turns out to be unwieldy when working interactively with NA-masked arrays, and having an object array be created instead of an NA-masked array can be very surprising.

Because of this, the design has been changed to enable an NA-mask whenever creating an array from lists which have an NA object in them. There could be some debate of whether one should create NA-masks or NA-bitpatterns by default, but due to the time constraints it was only feasible to tackle NA-masks, and extending the NA-mask support more fully throughout NumPy seems much more reasonable than starting another system and ending up with two incomplete systems.

Mask Implementation Details

The memory ordering of the mask will always match the ordering of the array it is associated with. A Fortran-style array will have a Fortran-style mask, etc.

When a view of an array with a mask is taken, the view will have a mask which is also a view of the mask in the original array. This means unmasking values in views will also unmask them in the original array, and if a mask is added to an array, it will not be possible to ever remove that mask except to create a new array copying the data but not the mask.

It is still possible to temporarily treat an array with a mask without giving it one, by first creating a view of the array and then adding a mask to that view. A data set can be viewed with multiple different masks simultaneously, by creating multiple views, and giving each view a mask.

New ndarray Methods

New functions added to the numpy namespace are:

np.isna(arr) [IMPLEMENTED]
    Returns a boolean array with True whereever the array is masked
    or matches the NA bitpattern, and False elsewhere

np.isavail(arr)
    Returns a boolean array with False whereever the array is masked
    or matches the NA bitpattern, and True elsewhere

New functions added to the ndarray are:

arr.copy(..., replacena=np.NA)
    Modification to the copy function which replaces NA values,
    either masked or with the NA bitpattern, with the 'replacena='
    parameter suppled. When 'replacena' isn't NA, the copied
    array is unmasked and has the 'NA' part stripped from the
    parameterized dtype ('NA[f8]' becomes just 'f8').

    The default for replacena is chosen to be np.NA instead of None,
    because it may be desirable to replace NA with None in an
    NA-masked object array.

    For future multi-NA support, 'replacena' could accept a dictionary
    mapping the NA payload to the value to substitute for that
    particular NA. NAs with payloads not appearing in the dictionary
    would remain as NA unless a 'default' key was also supplied.

    Both the parameter to replacena and the values in the dictionaries
    can be either scalars or arrays which get broadcast onto 'arr'.

arr.view(maskna=True) [IMPLEMENTED]
    This is a shortcut for
    >>> a = arr.view()
    >>> a.flags.maskna = True

arr.view(ownmaskna=True) [IMPLEMENTED]
    This is a shortcut for
    >>> a = arr.view()
    >>> a.flags.maskna = True
    >>> a.flags.ownmaskna = True

Element-wise UFuncs With Missing Values

As part of the implementation, ufuncs and other operations will have to be extended to support masked computation. Because this is a useful feature in general, even outside the context of a masked array, in addition to working with masked arrays ufuncs will take an optional ‘where=’ parameter which allows the use of boolean arrays to choose where a computation should be done.:

>>> np.add(a, b, out=b, where=(a > threshold))

A benefit of having this ‘where=’ parameter is that it provides a way to temporarily treat an object with a mask without ever creating a masked array object. In the example above, this would only do the add for the array elements with True in the ‘where’ clause, and neither ‘a’ nor ‘b’ need to be masked arrays.

If the ‘out’ parameter isn’t specified, use of the ‘where=’ parameter will produce an array with a mask as the result, with missing values for everywhere the ‘where’ clause had the value False.

For boolean operations, the R project special cases logical_and and logical_or so that logical_and(NA, False) is False, and logical_or(NA, True) is True. On the other hand, 0 * NA isn’t 0, but here the NA could represent Inf or NaN, in which case 0 * the backing value wouldn’t be 0 anyway.

For NumPy element-wise ufuncs, the design won’t support this ability for the mask of the output to depend simultaneously on the mask and the value of the inputs. The NumPy 1.6 nditer, however, makes it fairly easy to write standalone functions which look and feel just like ufuncs, but deviate from their behavior. The functions logical_and and logical_or can be moved into standalone function objects which are backwards compatible with the current ufuncs.

Reduction UFuncs With Missing Values

Reduction operations like ‘sum’, ‘prod’, ‘min’, and ‘max’ will operate consistently with the idea that a masked value exists, but its value is unknown.

An optional parameter ‘skipna=’ will be added to those functions which can interpret it appropriately to do the operation as if just the unmasked values existed.

With ‘skipna=True’, when all the input values are masked, ‘sum’ and ‘prod’ will produce the additive and multiplicative identities respectively, while ‘min’ and ‘max’ will produce masked values. Statistics operations which require a count, like ‘mean’ and ‘std’ will also use the unmasked value counts for their calculations if ‘skipna=True’, and produce masked values when all the inputs are masked.

Some examples:

>>> a = np.array([1., 3., np.NA, 7.], maskna=True)
>>> np.sum(a)
array(NA, dtype='<f8', maskna=True)
>>> np.sum(a, skipna=True)
11.0
>>> np.mean(a)
NA(dtype='<f8')
>>> np.mean(a, skipna=True)
3.6666666666666665

>>> a = np.array([np.NA, np.NA], dtype='f8', maskna=True)
>>> np.sum(a, skipna=True)
0.0
>>> np.max(a, skipna=True)
array(NA, dtype='<f8', maskna=True)
>>> np.mean(a)
NA(dtype='<f8')
>>> np.mean(a, skipna=True)
/home/mwiebe/virtualenvs/dev/lib/python2.7/site-packages/numpy/core/fromnumeric.py:2374: RuntimeWarning: invalid value encountered in double_scalars
  return mean(axis, dtype, out)
nan

The functions ‘np.any’ and ‘np.all’ require some special consideration, just as logical_and and logical_or do. Maybe the best way to describe their behavior is through a series of examples:

>>> np.any(np.array([False, False, False], maskna=True))
False
>>> np.any(np.array([False, np.NA, False], maskna=True))
NA
>>> np.any(np.array([False, np.NA, True], maskna=True))
True

>>> np.all(np.array([True, True, True], maskna=True))
True
>>> np.all(np.array([True, np.NA, True], maskna=True))
NA
>>> np.all(np.array([False, np.NA, True], maskna=True))
False

Since ‘np.any’ is the reduction for ‘np.logical_or’, and ‘np.all’ is the reduction for ‘np.logical_and’, it makes sense for them to have a ‘skipna=’ parameter like the other similar reduction functions.

Parameterized NA Data Types

A masked array isn’t the only way to deal with missing data, and some systems deal with the problem by defining a special “NA” value, for data which is missing. This is distinct from NaN floating point values, which are the result of bad floating point calculation values, but many people use NaNs for this purpose.

In the case of IEEE floating point values, it is possible to use a particular NaN value, of which there are many, for “NA”, distinct from NaN. For signed integers, a reasonable approach would be to use the minimum storable value, which doesn’t have a corresponding positive value. For unsigned integers, the maximum storage value seems most reasonable.

With the goal of providing a general mechanism, a parameterized type mechanism for this is much more attractive than creating separate nafloat32, nafloat64, naint64, nauint64, etc dtypes. If this is viewed as an alternative way of treating the mask except without value preservation, this parameterized type can work together with the mask in a special way to produce a value + mask combination on the fly, and use the exact same computational infrastructure as the masked array system. This allows one to avoid the need to write special case code for each ufunc and for each na* dtype, something that is hard to avoid when building a separate independent dtype implementation for each na* dtype.

Reliable conversions with the NA bitpattern preserved across primitive types requires consideration as well. Even in the simple case of double -> float, where this is supported by hardware, the NA value will get lost because the NaN payload is typically not preserved. The ability to have different bit masks specified for the same underlying type also needs to convert properly. With a well-defined interface converting to/from a (value,flag) pair, this becomes straightforward to support generically.

This approach also provides some opportunities for some subtle variations with IEEE floats. By default, one exact bit-pattern, a silent NaN with a payload that won’t be generated by hardware floating point operations, would be used. The choice R has made could be this default.

Additionally, it might be nice to sometimes treat all NaNs as missing values. This requires a slightly more complex mapping to convert the floating point values into mask/value combinations, and converting back would always produce the default NaN used by NumPy. Finally, treating both NaNs and Infs as missing values would be just a slight variation of the NaN version.

Strings require a slightly different handling, because they may be any size. One approach is to use a one-character signal consisting of one of the first 32 ASCII/unicode values. There are many possible values to use here, like 0x15 ‘Negative Acknowledgement’ or 0x10 ‘Data Link Escape’.

The Object dtype has an obvious signal, the np.NA singleton itself. Any dtype with object semantics won’t be able to have this customized, since specifying bit patterns applies only to plain binary data, not data with object semantics of construction and destructions.

Struct dtypes are more of a core primitive dtype, in the same fashion that this parameterized NA-capable dtype is. It won’t be possible to put these as the parameter for the parameterized NA-dtype.

The dtype names would be parameterized similar to how the datetime64 is parameterized by the metadata unit. What name to use may require some debate, but “NA” seems like a reasonable choice. With the default missing value bit-pattern, these dtypes would look like np.dtype(‘NA[float32]’), np.dtype(‘NA[f8]’), or np.dtype(‘NA[i64]’).

To override the bit pattern that signals a missing value, a raw value in the format of a hexadecimal unsigned integer can be given, and in the above special cases for floating point, special strings can be provided. The defaults for some cases, written explicitly in this form, are then:

np.dtype('NA[?,0x02]')
np.dtype('NA[i4,0x80000000]')
np.dtype('NA[u4,0xffffffff]')
np.dtype('NA[f4,0x7f8007a2')
np.dtype('NA[f8,0x7ff00000000007a2') (R-compatible bitpattern)
np.dtype('NA[S16,0x15]') (using the NAK character as the signal).

np.dtype('NA[f8,NaN]') (for any NaN)
np.dtype('NA[f8,InfNaN]') (for any NaN or Inf)

When no parameter is specified a flexible NA dtype is created, which itself cannot hold values, but will conform to the input types in functions like ‘np.astype’. The dtype ‘f8’ maps to ‘NA[f8]’, and [(‘a’, ‘f4’), (‘b’, ‘i4’)] maps to [(‘a’, ‘NA[f4]’), (‘b’, ‘NA[i4]’)]. Thus, to view the memory of an ‘f8’ array ‘arr’ with ‘NA[f8]’, you can say arr.view(dtype=’NA’).

Future Expansion to multi-NA Payloads

The packages SAS and Stata both support multiple different “NA” values. This allows one to specify different reasons for why a value, for example homework that wasn’t done because the dog ate it or the student was sick. In these packages, the different NA values have a linear ordering which specifies how different NA values combine together.

In the sections on C implementation details, the mask has been designed so that a mask with a payload is a strict superset of the NumPy boolean type, and the boolean type has a payload of just zero. Different payloads combine with the ‘min’ operation.

The important part of future-proofing the design is making sure the C ABI-level choices and the Python API-level choices have a natural transition to multi-NA support. Here is one way multi-NA support could look:

>>> a = np.array([np.NA(1), 3, np.NA(2)], maskna='multi')
>>> np.sum(a)
NA(1, dtype='<i4')
>>> np.sum(a[1:])
NA(2, dtype='<i4')
>>> b = np.array([np.NA, 2, 5], maskna=True)
>>> a + b
array([NA(0), 5, NA(2)], maskna='multi')

The design of this NEP does not distinguish between NAs that come from an NA mask or NAs that come from an NA dtype. Both of these get treated equivalently in computations, with masks dominating over NA dtypes.:

>>> a = np.array([np.NA, 2, 5], maskna=True)
>>> b = np.array([1, np.NA, 7], dtype='NA')
>>> a + b
array([NA, NA, 12], maskna=True)

The multi-NA approach allows one to distinguish between these NAs, through assigning different payloads to the different types. If we extend the ‘skipna=’ parameter to accept a list of payloads in addition to True/False, one could do this:

>>> a = np.array([np.NA(1), 2, 5], maskna='multi')
>>> b = np.array([1, np.NA(0), 7], dtype='NA[f4,multi]')
>>> a + b
array([NA(1), NA(0), 12], maskna='multi')
>>> np.sum(a, skipna=0)
NA(1, dtype='<i4')
>>> np.sum(a, skipna=1)
7
>>> np.sum(b, skipna=0)
8
>>> np.sum(b, skipna=1)
NA(0, dtype='<f4')
>>> np.sum(a+b, skipna=(0,1))
12

Differences with numpy.ma

The computational model that numpy.ma uses does not strictly adhere to either the NA or the IGNORE model. This section exhibits some examples of how these differences affect simple computations. This information will be very important for helping users navigate between the systems, so a summary probably should be put in a table in the documentation.:

>>> a = np.random.random((3, 2))
>>> mask = [[False, True], [True, True], [False, False]]
>>> b1 = np.ma.masked_array(a, mask=mask)
>>> b2 = a.view(maskna=True)
>>> b2[mask] = np.NA

>>> b1
masked_array(data =
 [[0.110804969841 --]
 [-- --]
 [0.955128477746 0.440430735546]],
             mask =
 [[False  True]
 [ True  True]
 [False False]],
       fill_value = 1e+20)
>>> b2
array([[0.110804969841, NA],
       [NA, NA],
       [0.955128477746, 0.440430735546]],
       maskna=True)

>>> b1.mean(axis=0)
masked_array(data = [0.532966723794 0.440430735546],
             mask = [False False],
       fill_value = 1e+20)

>>> b2.mean(axis=0)
array([NA, NA], dtype='<f8', maskna=True)
>>> b2.mean(axis=0, skipna=True)
array([0.532966723794 0.440430735546], maskna=True)

For functions like np.mean, when ‘skipna=True’, the behavior for all NAs is consistent with an empty array:

>>> b1.mean(axis=1)
masked_array(data = [0.110804969841 -- 0.697779606646],
             mask = [False  True False],
       fill_value = 1e+20)

>>> b2.mean(axis=1)
array([NA, NA, 0.697779606646], maskna=True)
>>> b2.mean(axis=1, skipna=True)
RuntimeWarning: invalid value encountered in double_scalars
array([0.110804969841, nan, 0.697779606646], maskna=True)

>>> np.mean([])
RuntimeWarning: invalid value encountered in double_scalars
nan

In particular, note that numpy.ma generally skips masked values, except returns masked when all the values are masked, while the ‘skipna=’ parameter returns zero when all the values are NA, to be consistent with the result of np.sum([]):

>>> b1[1]
masked_array(data = [-- --],
             mask = [ True  True],
       fill_value = 1e+20)
>>> b2[1]
array([NA, NA], dtype='<f8', maskna=True)
>>> b1[1].sum()
masked
>>> b2[1].sum()
NA(dtype='<f8')
>>> b2[1].sum(skipna=True)
0.0

>>> np.sum([])
0.0

Boolean Indexing

Indexing using a boolean array containing NAs does not have a consistent interpretation according to the NA abstraction. For example:

>>> a = np.array([1, 2])
>>> mask = np.array([np.NA, True], maskna=True)
>>> a[mask]
What should happen here?

Since the NA represents a valid but unknown value, and it is a boolean, it has two possible underlying values:

>>> a[np.array([True, True])]
array([1, 2])
>>> a[np.array([False, True])]
array([2])

The thing which changes is the length of the output array, nothing which itself can be substituted for NA. For this reason, at least initially, NumPy will raise an exception for this case.

Another possibility is to add an inconsistency, and follow the approach R uses. That is, to produce the following:

>>> a[mask]
array([NA, 2], maskna=True)

If, in user testing, this is found necessary for pragmatic reasons, the feature should be added even though it is inconsistent.

PEP 3118

PEP 3118 doesn’t have any mask mechanism, so arrays with masks will not be accessible through this interface. Similarly, it doesn’t support the specification of dtypes with NA or IGNORE bitpatterns, so the parameterized NA dtypes will also not be accessible through this interface.

If NumPy did allow access through PEP 3118, this would circumvent the missing value abstraction in a very damaging way. Other libraries would try to use masked arrays, and silently get access to the data without also getting access to the mask or being aware of the missing value abstraction the mask and data together are following.

Cython

Cython uses PEP 3118 to work with NumPy arrays, so currently it will simply refuse to work with them as described in the “PEP 3118” section.

In order to properly support NumPy missing values, Cython will need to be modified in some fashion to add this support. Likely the best way to do this will be to include it with supporting np.nditer, which is most likely going to have an enhancement to make writing missing value algorithms easier.

Hard Masks

The numpy.ma implementation has a “hardmask” feature, which prevents values from ever being unmasked by assigning a value. This would be an internal array flag, named something like ‘arr.flags.hardmask’.

If the hardmask feature is implemented, boolean indexing could return a hardmasked array instead of a flattened array with the arbitrary choice of C-ordering as it currently does. While this improves the abstraction of the array significantly, it is not a compatible change.

Shared Masks

One feature of numpy.ma is called ‘shared masks’.

http://docs.scipy.org/doc/numpy/reference/maskedarray.baseclass.html#numpy.ma.MaskedArray.sharedmask

This feature cannot be supported by a masked implementation of missing values without directly violating the missing value abstraction. If the same mask memory is shared between two arrays ‘a’ and ‘b’, assigning a value to a masked element in ‘a’ will simultaneously unmask the element with matching index in ‘b’. Because this isn’t at the same time assigning a valid value to that element in ‘b’, this has violated the abstraction. For this reason, shared masks will not be supported by the mask-based missing value implementation.

This is slightly different from what happens when taking a view of an array with masked missing value support, where a view of both the mask and the data are taken simultaneously. The result is two views which share the same mask memory and the same data memory, which still preserves the missing value abstraction.

Interaction With Pre-existing C API Usage

Making sure existing code using the C API, whether it’s written in C, C++, or Cython, does something reasonable is an important goal of this implementation. The general strategy is to make existing code which does not explicitly tell numpy it supports NA masks fail with an exception saying so. There are a few different access patterns people use to get ahold of the numpy array data, here we examine a few of them to see what numpy can do. These examples are found from doing google searches of numpy C API array access.

Numpy Documentation - How to extend NumPy

http://docs.scipy.org/doc/numpy/user/c-info.how-to-extend.html#dealing-with-array-objects

This page has a section “Dealing with array objects” which has some advice for how to access numpy arrays from C. When accepting arrays, the first step it suggests is to use PyArray_FromAny or a macro built on that function, so code following this advice will properly fail when given an NA-masked array it doesn’t know how to handle.

The way this is handled is that PyArray_FromAny requires a special flag, NPY_ARRAY_ALLOWNA, before it will allow NA-masked arrays to flow through.

http://docs.scipy.org/doc/numpy/reference/c-api.array.html#NPY_ARRAY_ALLOWNA

Code which does not follow this advice, and instead just calls PyArray_Check() to verify its an ndarray and checks some flags, will silently produce incorrect results. This style of code does not provide any opportunity for numpy to say “hey, this array is special”, so also is not compatible with future ideas of lazy evaluation, derived dtypes, etc.

Tutorial From Cython Website

http://docs.cython.org/src/tutorial/numpy.html

This tutorial gives a convolution example, and all the examples fail with Python exceptions when given inputs that contain NA values.

Before any Cython type annotation is introduced, the code functions just as equivalent Python would in the interpreter.

When the type information is introduced, it is done via numpy.pxd which defines a mapping between an ndarray declaration and PyArrayObject *. Under the hood, this maps to __Pyx_ArgTypeTest, which does a direct comparison of Py_TYPE(obj) against the PyTypeObject for the ndarray.

Then the code does some dtype comparisons, and uses regular python indexing to access the array elements. This python indexing still goes through the Python API, so the NA handling and error checking in numpy still can work like normal and fail if the inputs have NAs which cannot fit in the output array. In this case it fails when trying to convert the NA into an integer to set in in the output.

The next version of the code introduces more efficient indexing. This operates based on Python’s buffer protocol. This causes Cython to call __Pyx_GetBufferAndValidate, which calls __Pyx_GetBuffer, which calls PyObject_GetBuffer. This call gives numpy the opportunity to raise an exception if the inputs are arrays with NA-masks, something not supported by the Python buffer protocol.

Numerical Python - JPL website

http://dsnra.jpl.nasa.gov/software/Python/numpydoc/numpy-13.html

This document is from 2001, so does not reflect recent numpy, but it is the second hit when searching for “numpy c api example” on google.

There first example, heading “A simple example”, is in fact already invalid for recent numpy even without the NA support. In particular, if the data is misaligned or in a different byteorder, it may crash or produce incorrect results.

The next thing the document does is introduce PyArray_ContiguousFromObject, which gives numpy an opportunity to raise an exception when NA-masked arrays are used, so the later code will raise exceptions as desired.

C Implementation Details

The first version to implement is the array masks, because it is the more general approach. The mask itself is an array, but since it is intended to never be directly accessible from Python, it won’t be a full ndarray itself. The mask always has the same shape as the array it’s attached to, so it doesn’t need its own shape. For an array with a struct dtype, however, the mask will have a different dtype than just a straight bool, so it does need its own dtype. This gives us the following additions to the PyArrayObject:

/*
 * Descriptor for the mask dtype.
 *   If no mask: NULL
 *   If mask   : bool/uint8/structured dtype of mask dtypes
 */
PyArray_Descr *maskna_dtype;
/*
 * Raw data buffer for mask. If the array has the flag
 * NPY_ARRAY_OWNMASKNA enabled, it owns this memory and
 * must call PyArray_free on it when destroyed.
 */
npy_mask *maskna_data;
/*
 * Just like dimensions and strides point into the same memory
 * buffer, we now just make the buffer 3x the nd instead of 2x
 * and use the same buffer.
 */
npy_intp *maskna_strides;

These fields can be accessed through the inline functions:

PyArray_Descr *
PyArray_MASKNA_DTYPE(PyArrayObject *arr);

npy_mask *
PyArray_MASKNA_DATA(PyArrayObject *arr);

npy_intp *
PyArray_MASKNA_STRIDES(PyArrayObject *arr);

npy_bool
PyArray_HASMASKNA(PyArrayObject *arr);

There are 2 or 3 flags which must be added to the array flags, both for requesting NA masks and for testing for them:

NPY_ARRAY_MASKNA
NPY_ARRAY_OWNMASKNA
/* To possibly add in a later revision */
NPY_ARRAY_HARDMASKNA

To allow the easy detection of NA support, and whether an array has any missing values, we add the following functions:

PyDataType_HasNASupport(PyArray_Descr* dtype)
Returns true if this is an NA dtype, or a struct dtype where every field has NA support.
PyArray_HasNASupport(PyArrayObject* obj)
Returns true if the array dtype has NA support, or the array has an NA mask.
PyArray_ContainsNA(PyArrayObject* obj)
Returns false if the array has no NA support. Returns true if the array has NA support AND there is an NA anywhere in the array.
int PyArray_AllocateMaskNA(PyArrayObject* arr, npy_bool ownmaskna, npy_bool multina)
Allocates an NA mask for the array, ensuring ownership if requested and using NPY_MASK instead of NPY_BOOL for the dtype if multina is True.

Mask Binary Format

The format of the mask itself is designed to indicate whether an element is masked or not, as well as contain a payload so that multiple different NAs with different payloads can be used in the future. Initially, we will simply use the payload 0.

The mask has type npy_uint8, and bit 0 is used to indicate whether a value is masked. If ((m&0x01) == 0), the element is masked, otherwise it is unmasked. The rest of the bits are the payload, which is (m>>1). The convention for combining masks with payloads is that smaller payloads propagate. This design gives 128 payload values to masked elements, and 128 payload values to unmasked elements.

The big benefit of this approach is that npy_bool also works as a mask, because it takes on the values 0 for False and 1 for True. Additionally, the payload for npy_bool, which is always zero, dominates over all the other possible payloads.

Since the design involves giving the mask its own dtype, we can distinguish between masking with a single NA value (npy_bool mask), and masking with multi-NA (npy_uint8 mask). Initial implementations will just support the npy_bool mask.

An idea that was discarded is to allow the combination of masks + payloads to be a simple ‘min’ operation. This can be done by putting the payload in bits 0 through 6, so that the payload is (m&0x7f), and using bit 7 for the masking flag, so ((m&0x80) == 0) means the element is masked. The fact that this makes masks completely different from booleans, instead of a strict superset, is the primary reason this choice was discarded.

C Iterator API Changes: Iteration With Masks

For iteration and computation with masks, both in the context of missing values and when the mask is used like the ‘where=’ parameter in ufuncs, extending the nditer is the most natural way to expose this functionality.

Masked operations need to work with casting, alignment, and anything else which causes values to be copied into a temporary buffer, something which is handled nicely by the nditer but difficult to do outside that context.

First we describe iteration designed for use of masks outside the context of missing values, then the features which include missing value support.

Iterator Mask Features

We add several new per-operand flags:

NPY_ITER_WRITEMASKED

Indicates that any copies done from a buffer to the array are masked. This is necessary because READWRITE mode could destroy data if a float array was being treated like an int array, so copying to the buffer and back would truncate to integers. No similar flag is provided for reading, because it may not be possible to know the mask ahead of time, and copying everything into the buffer will never destroy data.

The code using the iterator should only write to values which are not masked by the mask specified, otherwise the result will be different depending on whether buffering is enabled or not.

NPY_ITER_ARRAYMASK

Indicates that this array is a boolean mask to use when copying any WRITEMASKED argument from a buffer back to the array. There can be only one such mask, and there cannot also be a virtual mask.

As a special case, if the flag NPY_ITER_USE_MASKNA is specified at the same time, the mask for the operand is used instead of the operand itself. If the operand has no mask but is based on an NA dtype, that mask exposed by the iterator converts into the NA bitpattern when copying from the buffer to the array.

NPY_ITER_VIRTUAL
Indicates that this operand is not an array, but rather created on the fly for the inner iteration code. This allocates enough buffer space for the code to read/write data, but does not have an actual array backing the data. When combined with NPY_ITER_ARRAYMASK, allows for creating a “virtual mask”, specifying which values are unmasked without ever creating a full mask array.

Iterator NA-array Features

We add several new per-operand flags:

NPY_ITER_USE_MASKNA
If the operand has an NA dtype, an NA mask, or both, this adds a new virtual operand to the end of the operand list which iterates over the mask for the particular operand.
NPY_ITER_IGNORE_MASKNA

If an operand has an NA mask, by default the iterator will raise an exception unless NPY_ITER_USE_MASKNA is specified. This flag disables that check, and is intended for cases where one has first checked that all the elements in the array are not NA using the PyArray_ContainsNA function.

If the dtype is an NA dtype, this also strips the NA-ness from the dtype, showing a dtype that does not support NA.

Rejected Alternative

Parameterized Data Type Which Adds Additional Memory for the NA Flag

Another alternative to having a separate mask added to the array is to introduced a parameterized type, which takes a primitive dtype as an argument. The dtype “i8” would turn into “maybe[i8]”, and a byte flag would be appended to the dtype to indicate whether the value was NA or not.

This approach adds memory overhead greater or equal to keeping a separate mask, but has better locality. To keep the dtype aligned, an ‘i8’ would need to have 16 bytes to retain proper alignment, a 100% overhead compared to 12.5% overhead for a separately kept mask.

Acknowledgments

In addition to feedback from Travis Oliphant and others at Enthought, this NEP has been revised based on a great deal of feedback from the NumPy-Discussion mailing list. The people participating in the discussion are:

Nathaniel Smith
Robert Kern
Charles Harris
Gael Varoquaux
Eric Firing
Keith Goodman
Pierre GM
Christopher Barker
Josef Perktold
Ben Root
Laurent Gautier
Neal Becker
Bruce Southey
Matthew Brett
Wes McKinney
Lluís
Olivier Delalleau
Alan G Isaac
E. Antero Tammi
Jason Grout
Dag Sverre Seljebotn
Joe Harrington
Gary Strangman
Chris Jordan-Squire
Peter

I apologize if I missed anyone.


Cleaning the math configuration of numpy.core

  • Numpy Enhancement Proposals
  • next
  • previous

Table Of Contents

  • Cleaning the math configuration of numpy.core
    • Executive summary
    • Current problems
    • Requirements
    • Proposal
    • Issues
    • License

Previous topic

Missing Data Functionality in NumPy

Next topic

A proposal for adding groupby functionality to NumPy

Cleaning the math configuration of numpy.core

Author: | David Cournapeau
Contact: | david@ar.media.kyoto-u.ac.jp
Date: | 2008-09-04

Executive summary

Before building numpy.core, we use some configuration tests to gather some information about available math functions. Over the years, the configuration became convoluted, to the point it became difficult to support new platforms easily.

The goal of this proposal is to clean the configuration of the math capabilities for easier maintenance.

Current problems

Currently, the math configuration mainly test for some math functions, and configure numpy accordingly. But instead of testing each desired function independantly, the current system has been developed more as workarounds particular platform oddities, using platform implicit knowledge. This is against the normal philosophy of testing for capabilities only, which is the autoconf philosophy, which showed the path toward portability (on Unix at least) [1] This causes problems because modifying or adding configuration on existing platforms break the implicit assumption, without a clear solution.

For example, on windows, when numpy is built with mingw, it would be nice to enforce the configuration sizeof(long double) == sizeof(double) because mingw uses the MS runtime, and the MS runtime does not support long double. Unfortunately, doing so breaks the mingw math function detection, because of the implicit assumption that mingw has a configuration sizeof(long double) != sizeof(double).

Another example is the testing for set of functions using only one function: if expf is found, it is assumed that all basic float functions are available. Instead, each function should be tested independantly (expf, sinf, etc...).

Requirements

We have two strong requirements:
  • it should not break any currently supported platform
  • it should not make the configuration much slower (1-2 seconds are acceptable)

Proposal

We suggest to break any implicit assumption, and test each math function independantly from each other, as usually done by autoconf. Since testing for a vast set of functions can be time consuming, we will use a scheme similar to AC_CHECK_FUNCS_ONCE in autoconf, that is test for a set of function at once, and only in the case it breaks, do the per function check. When the first check works, it should be as fast as the current scheme, except that the assumptions are explicitely checked (all functions implied by HAVE_LONGDOUBLE_FUNCS would be checked together, for example).

Issues

Static vs non static ? For basic functions, shall we define them static or not ?

License

This document has been placed in the public domain.

[1]: Autobook here


A proposal for adding groupby functionality to NumPy

  • Numpy Enhancement Proposals
  • next
  • previous

Table Of Contents

  • A proposal for adding groupby functionality to NumPy
    • Executive summary
    • Example Use Case
    • Ufunc methods proposed
    • Functions proposed

Previous topic

Cleaning the math configuration of numpy.core

Next topic

A proposal to build numpy without warning with a big set of warning flags

A proposal for adding groupby functionality to NumPy

Author: | Travis Oliphant
Contact: | oliphant@enthought.com
Date: | 2010-04-27

Executive summary

NumPy provides tools for handling data and doing calculations in much the same way as relational algebra allows. However, the common group-by functionality is not easily handled. The reduce methods of NumPy’s ufuncs are a natural place to put this groupby behavior. This NEP describes two additional methods for ufuncs (reduceby and reducein) and two additional functions (segment and edges) which can help add this functionality.

Example Use Case

Suppose you have a NumPy structured array containing information about the number of purchases at several stores over multiple days. To be clear, the structured array data-type is:

dt = [(‘year’, i2), (‘month’, i1), (‘day’, i1), (‘time’, float),
(‘store’, i4), (‘SKU’, ‘S6’), (‘number’, i4)]

Suppose there is a 1-d NumPy array of this data-type and you would like to compute various statistics (max, min, mean, sum, etc.) on the number of products sold, by product, by month, by store, etc.

Currently, this could be done by using reduce methods on the number field of the array, coupled with in-place sorting, unique with return_inverse=True and bincount, etc. However, for such a common data-analysis need, it would be nice to have standard and more direct ways to get the results.

Ufunc methods proposed

It is proposed to add two new reduce-style methods to the ufuncs: reduceby and reducein. The reducein method is intended to be a simpler to use version of reduceat, while the reduceby method is intended to provide group-by capability on reductions.

reducein:

<ufunc>.reducein(arr, indices, axis=0, dtype=None, out=None)

Perform a local reduce with slices specified by pairs of indices.

The reduction occurs along the provided axis, using the provided
data-type to calculate intermediate results, storing the result into
the array out (if provided).

The indices array provides the start and end indices for the
reduction.  If the length of the indices array is odd, then the
final index provides the beginning point for the final reduction
and the ending point is the end of arr.

This generalizes along the given axis, the behavior:

[<ufunc>.reduce(arr[indices[2*i]:indices[2*i+1]])
        for i in range(len(indices)/2)]

This assumes indices is of even length

Example:
   >>> a = [0,1,2,4,5,6,9,10]
   >>> add.reducein(a,[0,3,2,5,-2])
   [3, 11, 19]

   Notice that sum(a[0:3]) = 3; sum(a[2:5]) = 11; and sum(a[-2:]) = 19

reduceby:

<ufunc>.reduceby(arr, by, dtype=None, out=None)

Perform a reduction in arr over unique non-negative integers in by.

Let N=arr.ndim and M=by.ndim.  Then, by.shape[:N] == arr.shape.
In addition, let I be an N-length index tuple, then by[I]
contains the location in the output array for the reduction to
be stored.  Notice that if N == M, then by[I] is a non-negative
integer, while if N < M, then by[I] is an array of indices into
the output array.

The reduction is computed on groups specified by unique indices
into the output array. The index is either the single
non-negative integer if N == M or if N < M, the entire
(M-N+1)-length index by[I] considered as a whole.

Functions proposed

segment:

edges:

.. Local Variables:
.. mode: rst
.. coding: utf-8
.. fill-column: 72
.. End:


A proposal to build numpy without warning with a big set of warning flags

  • Numpy Enhancement Proposals
  • next
  • previous

Table Of Contents

  • A proposal to build numpy without warning with a big set of warning flags
    • Executive summary
    • Warning flags
    • Kind of warnings
      • unused parameter
      • signed/unsigned comparison
      • half-initialized structures

Previous topic

A proposal for adding groupby functionality to NumPy

Next topic

Replacing Trac with a different bug tracker

A proposal to build numpy without warning with a big set of warning flags

Author: | David Cournapeau
Contact: | david@ar.media.kyoto-u.ac.jp
Date: | 2008-09-04

Executive summary

When building numpy and scipy, we are limited to a quite restricted set of warning compilers, thus missing a large class of potential bugs which could be detected with stronger warning flags. The goal of this NEP is present the various methods used to clean the code and implement some policy to make numpy buildable with a bigger set of warning flags, while keeping the build warnings free.

Warning flags

Each compiler detects a diffferent set of potential errors. The baseline will be gcc -Wall -W -Wextra. Ideally, a complete set would be nice:

-W -Wall -Wextra -Wstrict-prototypes -Wmissing-prototypes -Waggregate-return -Wcast-align -Wcast-qual -Wnested-externs -Wshadow -Wbad-function-cast -Wwrite-strings “

Intel compiler, VS with /W3 /Wall, Sun compilers have extra warnings too.

Kind of warnings

C Python extension code tends to naturally generate a lot of spurious warnings. The goal is to have some facilities to tag some typical C-Python code so that the compilers do not generate warnings in those cases; the tag process has to be clean, readable, and be robust. In particular, it should not make the code more obscure or worse, break working code.

unused parameter

This one appears often: any python-callable C function takes two arguments, of which the first is not used for functions (only for methods). One way to solve it is to tag the function argument with a macro NPY_UNUSED. This macro uses compiler specific code to tag the variable, and mangle it such as it is not possible to use it accidentally once it is tagged.

The code to apply compiler specific option could be:

#if defined(__GNUC__)
#define __COMP_NPY_UNUSED __attribute__ ((__unused__))
# elif defined(__ICC)
#define __COMP_NPY_UNUSED __attribute__ ((__unused__))
#else
#define __COMP_NPY_UNUSED

#endif

The variable mangling would be:

#define NPY_UNUSED(x) (__NPY_UNUSED_TAGGED ## x) __COMP_NPY_UNUSED

When applied to a variable, one would get:

int foo(int * NPY_UNUSED(dummy))

expanded to

int foo(int * __NPY_UNUSED_TAGGEDdummy __COMP_NPY_UNUSED)

Thus avoiding any accidental use of the variable. The mangling is pure C, and thuse portable. The per-variable warning disabling is compiler specific.

signed/unsigned comparison

More tricky: not always clear what to do

half-initialized structures

Just put the elements with NULL in it.


Replacing Trac with a different bug tracker

  • Numpy Enhancement Proposals
  • next
  • previous

Table Of Contents

  • Replacing Trac with a different bug tracker
    • Scenario
      • new release
      • subcomponent maintainer
      • Review, newcoming code
    • Current trac limitation
    • Possible candidates
      • Updated trac + plugins
      • Redmine
      • Roundup

Previous topic

A proposal to build numpy without warning with a big set of warning flags

Next topic

Deferred UFunc Evaluation

Replacing Trac with a different bug tracker

Author: David Cournapeau, Stefan van der Walt

Some release managers of both numpy and scipy are becoming more and more disatisfied with the current development workflow, in particular for bug tracking. This document is a tentative to explain some problematic scenario, current trac limitations, and what can be done about it.

Scenario

new release

The workflow for a release is roughly as follows:

  • find all known regressions from last release, and fix them
  • get an idea of all bugs reported since last release
  • triage bugs in regressions/blocker issues/etc..., and assign them in the according roadmap, subpackage and maintainers
  • pinging subpackage maintainers

Most of those tasks are quite inefficient in the current trac as used on scipy:

  • it is hard to keep track of issues. In particular, everytime one goes to trac, we don’t really know what’s new from what’s not. If you think of issues as emails, the current situation would be like not having read/unread feature.
  • Batch handling of issues: changing characteristics of several issues at the same time is difficult, because the only available UI is web-based. Command-line based UI are much more efficient for this kind of scenario

More generally, making useful reports is very awkward with the currently deployed trac. Trac 0.11 may solve of those problems, but it has to be much better than the actually deployed version on scipy website. Finding issues with patches, old patches, etc... and making reports has to be much more streamlined that it is now.

subcomponent maintainer

Say you are the maintainer of scipy.foo, then you are mostly interested in getting bugs concerning scipy.foo only. But it should be easy for the general team to follow your work - it should also be easy for casual users (e.g. not developers) to follow some new features development pace.

Review, newcoming code

The goal is simple: make the bar as low as possible, and make sure people know what to do at every step to contribute to numpy or scipy:

  • Right now, patches languish for too long in trac. Of course, lack of time is one big reason; but the process of following new contributes could be made much simpler
  • It should be possible to be pinged only for reviews one a subset of numpy/scipy.
  • It should be possible for people interested in the patches to follow its progression. Comments, but also ‘mini’ timelines could be useful, particularly for massive issues (massive from a coding POV).

Current trac limitation

Note: by trac, we mean the currently deployed one. Some more recent versions may solve some of the issues.

  • Multi-project support: we have three trac instances, one for scipy, one for numpy, one for scikits. Creating accounts, maintaining and updating each of them is a maintainance burden. Nobody likes to do this kind of work, so anything which can reduce the burden is a plus. Also, it happens quite frequently that a bug against numpy is filled on scipy trac and vice and versa. You have to handle this manually, currently.
  • Clients not based on the web-ui. This can be made through the xmlrpc plugin + some clients. In particular, something like http://tracexplorer.devjavu.com/ can be interesting for people who like IDE. At least one person expressed his desire to have as much integration as possible with Eclipse.
  • Powerful queries: it should be possible to quickly find issues between two releases, the new issues from a given date, issues with patch, issues waiting for reviews, etc... The issues data have to be customizable, because most bug-tracker do not support things like review, etc... so we need to handle this ourselves (through tags, etc...)
  • Marking issues as read/unread. It should also be possible for any user to ‘mask’ issues to ignore them.
  • ticket dependency. This is quite helpful in my experience for big features which can be split into several issues. Roadmap can only be created by trac admin, and they are kind of heavy-weight.

Possible candidates

Updated trac + plugins

Pros:

  • Same system
  • In python, so we can hack it if we want

Cons:

  • Trac is aimed at being basic, and extended with plugins. But most plugins are broken, or not up to date. The information on which plugins are mature is not easily available.
  • At least the scipy.org trac was slow, and needed to be restarted constantly. This is simply not acceptable.

Redmine

Pros:

  • Support most features (except xmlrpc ?). Multi-project, etc...
  • (subjective): I (cdavid) find the out-of-the-box experience with redmine much more enjoyable. More informations are available easily, less clicks, more streamlined. See http://www.redmine.org/wiki/redmine/TheyAreUsingRedmine for examples
  • Conversion scripts from trac (no experience with it yet for numpy/scipy).
  • Community seems friendly and gets a lof of features done

Cons:

  • new system, less mature ?
  • in Ruby: since we are a python project, most of dev are familiar with python.
  • Wiki integration, etc... ?

Unknown:

  • xmlrpc API
  • performances
  • maintenance cost

Roundup

TODO


Deferred UFunc Evaluation

  • Numpy Enhancement Proposals
  • next
  • previous

Table Of Contents

  • Deferred UFunc Evaluation
    • Abstract
    • Motivation
    • Example Python Code
    • Proposed Deferred Evaluation API
      • Error Handling
      • Interaction With UPDATEIFCOPY
      • Other Implementation Details
      • Further Optimization

Previous topic

Replacing Trac with a different bug tracker

Next topic

Structured array extensions

Deferred UFunc Evaluation

Author: | Mark Wiebe <mwwiebe@gmail.com>
Content-Type: | text/x-rst
Created: | 30-Nov-2010

Abstract

This NEP describes a proposal to add deferred evaluation to NumPy’s UFuncs. This will allow Python expressions like “a[:] = b + c + d + e” to be evaluated in a single pass through all the variables at once, with no temporary arrays. The resulting performance will likely be comparable to the numexpr library, but with a more natural syntax.

This idea has some interaction with UFunc error handling and the UPDATEIFCOPY flag, affecting the design and implementation, but the result allows for the usage of deferred evaluation with minimal effort from the Python user’s perspective.

Motivation

NumPy’s style of UFunc execution causes suboptimal performance for large expressions, because multiple temporaries are allocated and the inputs are swept through in multiple passes. The numexpr library can outperform NumPy for such large expressions, by doing the execution in small cache-friendly blocks, and evaluating the whole expression per element. This results in one sweep through each input, which is significantly better for the cache.

For an idea of how to get this kind of behavior in NumPy without changing the Python code, consider the C++ technique of expression templates. These can be used to quite arbitrarily rearrange expressions using vectors or other data structures, example,:

A = B + C + D;

can be transformed into something equivalent to:

for(i = 0; i < A.size; ++i) {
    A[i] = B[i] + C[i] + D[i];
}

This is done by returning a proxy object that knows how to calculate the result instead of returning the actual object. With modern C++ optimizing compilers, the resulting machine code is often the same as hand-written loops. For an example of this, see the Blitz++ Library. A more recently created library for helping write expression templates is Boost Proto.

By using the same idea of returning a proxy object in Python, we can accomplish the same thing dynamically. The return object is an ndarray without its buffer allocated, and with enough knowledge to calculate itself when needed. When a “deferred array” is finally evaluated, we can use the expression tree made up of all the operand deferred arrays, effectively creating a single new UFunc to evaluate on the fly.

Example Python Code

Here’s how it might be used in NumPy.:

# a, b, c are large ndarrays

with np.deferredstate(True):

    d = a + b + c
    # Now d is a 'deferred array,' a, b, and c are marked READONLY
    # similar to the existing UPDATEIFCOPY mechanism.

    print d
    # Since the value of d was required, it is evaluated so d becomes
    # a regular ndarray and gets printed.

    d[:] = a*b*c
    # Here, the automatically combined "ufunc" that computes
    # a*b*c effectively gets an out= parameter, so no temporary
    # arrays are needed whatsoever.

    e = a+b+c*d
    # Now e is a 'deferred array,' a, b, c, and d are marked READONLY

    d[:] = a
    # d was marked readonly, but the assignment could see that
    # this was due to it being a deferred expression operand.
    # This triggered the deferred evaluation so it could assign
    # the value of a to d.

There may be some surprising behavior, though.:

with np.deferredstate(True):

    d = a + b + c
    # d is deferred

    e[:] = d
    f[:] = d
    g[:] = d
    # d is still deferred, and its deferred expression
    # was evaluated three times, once for each assignment.
    # This could be detected, with d being converted to
    # a regular ndarray the second time it is evaluated.

I believe the usage that should be recommended in the documentation is to leave the deferred state at its default, except when evaluating a large expression that can benefit from it.:

# calculations

with np.deferredstate(True):
    x = <big expression>

# more calculations

This will avoid surprises which would be cause by always keeping deferred usage True, like floating point warnings or exceptions at surprising times when deferred expression are used later. User questions like “Why does my print statement throw a divide by zero error?” can hopefully be avoided by recommending this approach.

Proposed Deferred Evaluation API

For deferred evaluation to work, the C API needs to be aware of its existence, and be able to trigger evaluation when necessary. The ndarray would gain two new flag.

NPY_ISDEFERRED

Indicates the expression evaluation for this ndarray instance has been deferred.

NPY_DEFERRED_WASWRITEABLE

Can only be set when PyArray_GetDeferredUsageCount(arr) > 0. It indicates that when arr was first used in a deferred expression, it was a writeable array. If this flag is set, calling PyArray_CalculateAllDeferred() will make arr writeable again.

Note

QUESTION

Should NPY_DEFERRED and NPY_DEFERRED_WASWRITEABLE be visible to Python, or should accessing the flags from python trigger PyArray_CalculateAllDeferred if necessary?

The API would be expanded with a number of functions.

int PyArray_CalculateAllDeferred()

This function forces all currently deferred calculations to occur.

For example, if the error state is set to ignore all, and np.seterr({all=’raise’}), this would change what happens to already deferred expressions. Thus, all the existing deferred arrays should be evaluated before changing the error state.

int PyArray_CalculateDeferred(PyArrayObject* arr)

If ‘arr’ is a deferred array, allocates memory for it and evaluates the deferred expression. If ‘arr’ is not a deferred array, simply returns success. Returns NPY_SUCCESS or NPY_FAILURE.

int PyArray_CalculateDeferredAssignment(PyArrayObject* arr, PyArrayObject* out)

If ‘arr’ is a deferred array, evaluates the deferred expression into ‘out’, and ‘arr’ remains a deferred array. If ‘arr’ is not a deferred array, copies its value into out. Returns NPY_SUCCESS or NPY_FAILURE.

int PyArray_GetDeferredUsageCount(PyArrayObject* arr)

Returns a count of how many deferred expressions use this array as an operand.

The Python API would be expanded as follows.

numpy.setdeferred(state)

Enables or disables deferred evaluation. True means to always use deferred evaluation. False means to never use deferred evaluation. None means to use deferred evaluation if the error handling state is set to ignore everything. At NumPy initialization, the deferred state is None.

Returns the previous deferred state.

numpy.getdeferred()

Returns the current deferred state.

numpy.deferredstate(state)

A context manager for deferred state handling, similar to numpy.errstate.

Error Handling

Error handling is a thorny issue for deferred evaluation. If the NumPy error state is {all=’ignore’}, it might be reasonable to introduce deferred evaluation as the default, however if a UFunc can raise an error, it would be very strange for the later ‘print’ statement to throw the exception instead of the actual operation which caused the error.

What may be a good approach is to by default enable deferred evaluation only when the error state is set to ignore all, but allow user control with ‘setdeferred’ and ‘getdeferred’ functions. True would mean always use deferred evaluation, False would mean never use it, and None would mean use it only when safe (i.e. the error state is set to ignore all).

Interaction With UPDATEIFCOPY

The NPY_UPDATEIFCOPY documentation states:

The data area represents a (well-behaved) copy whose information should be transferred back to the original when this array is deleted.

This is a special flag that is set if this array represents a copy made because a user required certain flags in PyArray_FromAny and a copy had to be made of some other array (and the user asked for this flag to be set in such a situation). The base attribute then points to the “misbehaved” array (which is set read_only). When the array with this flag set is deallocated, it will copy its contents back to the “misbehaved” array (casting if necessary) and will reset the “misbehaved” array to NPY_WRITEABLE. If the “misbehaved” array was not NPY_WRITEABLE to begin with then PyArray_FromAny would have returned an error because NPY_UPDATEIFCOPY would not have been possible.

The current implementation of UPDATEIFCOPY assumes that it is the only mechanism mucking with the writeable flag in this manner. These mechanisms must be aware of each other to work correctly. Here’s an example of how they might go wrong:

  1. Make a temporary copy of ‘arr’ with UPDATEIFCOPY (‘arr’ becomes read only)
  2. Use ‘arr’ in a deferred expression (deferred usage count becomes one, NPY_DEFERRED_WASWRITEABLE is not set, since ‘arr’ is read only)
  3. Destroy the temporary copy, causing ‘arr’ to become writeable
  4. Writing to ‘arr’ destroys the value of the deferred expression

To deal with this issue, we make these two states mutually exclusive.

  • Usage of UPDATEIFCOPY checks the NPY_DEFERRED_WASWRITEABLE flag, and if it’s set, calls PyArray_CalculateAllDeferred to flush all deferred calculation before proceeding.
  • The ndarray gets a new flag NPY_UPDATEIFCOPY_TARGET indicating the array will be updated and made writeable at some point in the future. If the deferred evaluation mechanism sees this flag in any operand, it triggers immediate evaluation.

Other Implementation Details

When a deferred array is created, it gets references to all the operands of the UFunc, along with the UFunc itself. The ‘DeferredUsageCount’ is incremented for each operand, and later gets decremented when the deferred expression is calculated or the deferred array is destroyed.

A global list of weak references to all the deferred arrays is tracked, in order of creation. When PyArray_CalculateAllDeferred gets called, the newest deferred array is calculated first. This may release references to other deferred arrays contained in the deferred expression tree, which then never have to be calculated.

Further Optimization

Instead of conservatively disabling deferred evaluation when any errors are not set to ‘ignore’, each UFunc could give a set of possible errors it generates. Then, if all those errors are set to ‘ignore’, deferred evaluation could be used even if other errors are not set to ignore.

Once the expression tree is explicitly stored, it is possible to do transformations on it. For example add(add(a,b),c) could be transformed into add3(a,b,c), or add(multiply(a,b),c) could become fma(a,b,c) using the CPU fused multiply-add instruction where available.

While I’ve framed deferred evaluation as just for UFuncs, it could be extended to other functions, such as dot(). For example, chained matrix multiplications could be reordered to minimize the size of intermediates, or peep-hole style optimizer passes could search for patterns that match optimized BLAS/other high performance library calls.

For operations on really large arrays, integrating a JIT like LLVM into this system might be a big benefit. The UFuncs and other operations would provide bitcode, which could be inlined together and optimized by the LLVM optimizers, then executed. In fact, the iterator itself could also be represented in bitcode, allowing LLVM to consider the entire iteration while doing its optimization.


Structured array extensions

  • Numpy Enhancement Proposals
  • next
  • previous

Previous topic

Deferred UFunc Evaluation

Next topic

A proposal for implementing some date/time types in NumPy

Structured array extensions

  1. Create with-style context that makes “named-columns” available as names in the namespace.
with np.columns(array):
price = unit * quantityt
  2. Allow structured arrays to be sliced by their column (i.e. one additional indexing option for structured arrays) so that a[:4, ‘foo’:’bar’] would be allowed.


A proposal for implementing some date/time types in NumPy

  • Numpy Enhancement Proposals
  • next
  • previous

Table Of Contents

  • A proposal for implementing some date/time types in NumPy
    • Executive summary
    • Types proposed
    • Time units
    • datetime64
      • Building a datetime64 dtype
      • Setting and getting values
      • Comparisons
      • Compatibility issues
    • timedelta64
      • Building a timedelta64 dtype
      • Setting and getting values
      • Comparisons
      • Compatibility issues
    • Examples of use
    • Operating with date/time arrays
      • datetime64 vs datetime64
        • Casting rules
      • datetime64 vs timedelta64
        • Casting rules
      • timedelta64 vs timedelta64
        • Casting rules
    • dtype vs time units conversions
    • Necessary changes to NumPy
      • Addition of metadata to dtypes
      • Ufunc interface extension
      • Array Intervace Extensions
    • Final considerations
      • Why the fractional time and events: [3Y/12]//50
      • Why the origin metadata disappeared
      • Operations with mixed time units

Previous topic

Structured array extensions

Next topic

A (third) proposal for implementing some date/time types in NumPy

A proposal for implementing some date/time types in NumPy

Author: | Travis Oliphant
Contact: | oliphant@enthought.com
Date: | 2009-06-09

Revised only slightly from the third proposal by

Author: | Francesc Alted i Abad
Contact: | faltet@pytables.com
Author: | Ivan Vilata i Balaguer
Contact: | ivan@selidor.net
Date: | 2008-07-30

Executive summary

A date/time mark is something very handy to have in many fields where one has to deal with data sets. While Python has several modules that define a date/time type (like the integrated datetime [1] or mx.DateTime [2]), NumPy has a lack of them.

We are proposing the addition of date/time types to fill this gap. The requirements for the proposed types are two-fold: 1) they have to be fast to operate with and 2) they have to be as compatible as possible with the existing datetime module that comes with Python.

Types proposed

It is virtually impossible to come up with a single date/time type that fills the needs of every use case. As a result, we propose two general date-time types: 1) timedelta64 – a relative time and 2) datetime64 – an absolute time.

Each of these times are represented internally as 64-bit signed integers that refer to a particular unit (hour, minute, microsecond, etc.). There are several pre-defined units as well as the ability to create rational multiples of these units. A representation is also supported such that the stored date-time integer can encode both the number of a particular unit as well as a number of sequential events tracked for each unit.

The datetime64 represents an absolute time. Internally it is represented as the number of time units between the intended time and the epoch (12:00am on January 1, 1970 — POSIX time including its lack of leap seconds).

Time units

The 64-bit integer time can represent several different basic units as well as derived units. The basic units are listed in the following table:

Time unit |  | Time span | Time span (years)
Code | Meaning | Relative Time | Absolute Time
Y | year | +- 9.2e18 years | [9.2e18 BC, 9.2e18 AD]
M | month | +- 7.6e17 years | [7.6e17 BC, 7.6e17 AD]
W | week | +- 1.7e17 years | [1.7e17 BC, 1.7e17 AD]
B | business day | +- 3.5e16 years | [3.5e16 BC, 3.5e16 AD]
D | day | +- 2.5e16 years | [2.5e16 BC, 2.5e16 AD]
h | hour | +- 1.0e15 years | [1.0e15 BC, 1.0e15 AD]
m | minute | +- 1.7e13 years | [1.7e13 BC, 1.7e13 AD]
s | second | +- 2.9e12 years | [ 2.9e9 BC, 2.9e9 AD]
ms | millisecond | +- 2.9e9 years | [ 2.9e6 BC, 2.9e6 AD]
us | microsecond | +- 2.9e6 years | [290301 BC, 294241 AD]
ns | nanosecond | +- 292 years | [ 1678 AD, 2262 AD]
ps | picosecond | +- 106 days | [ 1969 AD, 1970 AD]
fs | femtosecond | +- 2.6 hours | [ 1969 AD, 1970 AD]
as | attosecond | +- 9.2 seconds | [ 1969 AD, 1970 AD]

A time unit is specified by a string consisting of a base-type given in the above table

Besides these basic code units, the user can create derived units consisting of multiples of any basic unit: 100ns, 3M, 15m, etc.

A limited number of divisions of any basic unit can be used to create multiples of a higher-resolution unit provided the divisor can be divided evenly into the number of higher-resolution units available. For example: Y/4 is just short-hand for -> (12M)/4 -> 3M and Y/4 will be represented after creation as 3M. The first lower unit found to have an even divisor will be chosen (up to 3 lower units). The following standardized definitions are used in this specific case to find acceptable divisors

Code | Interpreted as
Y | 12M, 52W, 365D
M | 4W, 30D, 720h
W | 5B, 7D, 168h, 10080m
B | 24h, 1440m, 86400s
D | 24h, 1440m, 86400s
h | 60m, 3600s
m | 60s, 60000ms

s, ms, us, ns, ps, fs (use 1000 and 1000000 of the next two available lower units respectively).

Finally, a date-time data-type can be created with support for tracking sequential events within a basic unit: [D]//100, [Y]//4 (notice the required brackets). These modulo event units provide the following interpretation to the date-time integer:

  • the divisor is the number of events in each period
  • the (integer) quotient is the integer number representing the base units
  • the remainder is the particular event in the period.

Modulo event-units can be combined with any derived units, but brackets are required. Thus [100ns]//50 which allows recording 50 events for every 100ns so that 0 represents the first event in the first 100ns tick, 1 represents the second event in the first 100ns tick, while 50 represents the first event in the second 100ns tick, and 51 represents the second event in the second 100ns tick.

To fully specify a date-time type, the time unit string must be combined with either the string for a datetime64 (‘M8’) or a timedelta64 (‘m8’) using brackets ‘[]’. Therefore, a fully-specified string representing a date-time dtype is ‘M8[Y]’ or (for a more complicated example) ‘M8[7s/9]//5’.

If a time unit is not specified, then it defaults to [us]. Thus ‘M8’ is equivalent to ‘M8[us]’ (except when modulo event-units are desired – i.e. you cannot specify ‘M8[us]//5’ as ‘M8//5’ or as ‘//5’

datetime64

This dtype represents a time that is absolute (i.e. not relative). It is implemented internally as an int64 type. The integer represents units from the internal POSIX epoch (see [3]). Like POSIX, the representation of a date doesn’t take leap seconds into account.

In time unit conversions and time representations (but not in other time computations), the value -2**63 (0x8000000000000000) is interpreted as an invalid or unknown date, Not a Time or NaT. See the section on time unit conversions for more information.

The value of an absolute date is thus an integer number of units of the chosen time unit passed since the epoch. If the integer is a negative number, then the magnitude of the integer represents the number of units prior to the epoch. When working with business days, Saturdays and Sundays are simply ignored from the count (i.e. day 3 in business days is not Saturday 1970-01-03, but Monday 1970-01-05).

Building a datetime64 dtype

The proposed ways to specify the time unit in the dtype constructor are:

Using the long string notation:

dtype('datetime64[us]')

Using the short string notation:

dtype('M8[us]')

If a time unit is not specified, then it defaults to [us]. Thus ‘M8’ is equivalent to ‘M8[us]’.

Setting and getting values

The objects with this dtype can be set in a series of ways:

t = numpy.ones(3, dtype='M8[s]')
t[0] = 1199164176    # assign to July 30th, 2008 at 17:31:00
t[1] = datetime.datetime(2008, 7, 30, 17, 31, 01) # with datetime module
t[2] = '2008-07-30T17:31:02'    # with ISO 8601

And can be get in different ways too:

str(t[0])  -->  2008-07-30T17:31:00
repr(t[1]) -->  datetime64(1199164177, 's')
str(t[0].item()) --> 2008-07-30 17:31:00  # datetime module object
repr(t[0].item()) --> datetime.datetime(2008, 7, 30, 17, 31)  # idem
str(t)  -->  [2008-07-30T17:31:00  2008-07-30T17:31:01  2008-07-30T17:31:02]
repr(t)  -->  array([1199164176, 1199164177, 1199164178],
                    dtype='datetime64[s]')

Comparisons

The comparisons will be supported too:

numpy.array(['1980'], 'M8[Y]') == numpy.array(['1979'], 'M8[Y]')
--> [False]

including applying broadcasting:

numpy.array(['1979', '1980'], 'M8[Y]') == numpy.datetime64('1980', 'Y')
--> [False, True]

The following should also work:

numpy.array(['1979', '1980'], 'M8[Y]') == '1980-01-01'
--> [False, True]

because the right hand expression can be broadcasted into an array of 2 elements of dtype ‘M8[Y]’.

Compatibility issues

This will be fully compatible with the datetime class of the datetime module of Python only when using a time unit of microseconds. For other time units, the conversion process will lose precision or will overflow as needed. The conversion from/to a datetime object doesn’t take leap seconds into account.

timedelta64

It represents a time that is relative (i.e. not absolute). It is implemented internally as an int64 type.

In time unit conversions and time representations (but not in other time computations), the value -2**63 (0x8000000000000000) is interpreted as an invalid or unknown time, Not a Time or NaT. See the section on time unit conversions for more information.

The value of a time delta is an integer number of units of the chosen time unit.

Building a timedelta64 dtype

The proposed ways to specify the time unit in the dtype constructor are:

Using the long string notation:

dtype('timedelta64[us]')

Using the short string notation:

dtype('m8[us]')

If a time unit is not specified, then a default of [us] is assumed. Thus ‘m8’ and ‘m8[us]’ are equivalent.

Setting and getting values

The objects with this dtype can be set in a series of ways:

t = numpy.ones(3, dtype='m8[ms]')
t[0] = 12    # assign to 12 ms
t[1] = datetime.timedelta(0, 0, 13000)   # 13 ms
t[2] = '0:00:00.014'    # 14 ms

And can be get in different ways too:

str(t[0])  -->  0:00:00.012
repr(t[1]) -->  timedelta64(13, 'ms')
str(t[0].item()) --> 0:00:00.012000   # datetime module object
repr(t[0].item()) --> datetime.timedelta(0, 0, 12000)  # idem
str(t)     -->  [0:00:00.012  0:00:00.014  0:00:00.014]
repr(t)    -->  array([12, 13, 14], dtype="timedelta64[ms]")

Comparisons

The comparisons will be supported too:

numpy.array([12, 13, 14], 'm8[ms]') == numpy.array([12, 13, 13], 'm8[ms]')
--> [True, True, False]

or by applying broadcasting:

numpy.array([12, 13, 14], 'm8[ms]') == numpy.timedelta64(13, 'ms')
--> [False, True, False]

The following should work too:

numpy.array([12, 13, 14], 'm8[ms]') == '0:00:00.012'
--> [True, False, False]

because the right hand expression can be broadcasted into an array of 3 elements of dtype ‘m8[ms]’.

Compatibility issues

This will be fully compatible with the timedelta class of the datetime module of Python only when using a time unit of microseconds. For other units, the conversion process will lose precision or will overflow as needed.

Examples of use

Here is an example of use for the datetime64:

In [5]: numpy.datetime64(42, 'us')
Out[5]: datetime64(42, 'us')

In [6]: print numpy.datetime64(42, 'us')
1970-01-01T00:00:00.000042  # representation in ISO 8601 format

In [7]: print numpy.datetime64(367.7, 'D')  # decimal part is lost
1971-01-02  # still ISO 8601 format

In [8]: numpy.datetime('2008-07-18T12:23:18', 'm')  # from ISO 8601
Out[8]: datetime64(20273063, 'm')

In [9]: print numpy.datetime('2008-07-18T12:23:18', 'm')
Out[9]: 2008-07-18T12:23

In [10]: t = numpy.zeros(5, dtype="datetime64[ms]")

In [11]: t[0] = datetime.datetime.now()  # setter in action

In [12]: print t
[2008-07-16T13:39:25.315  1970-01-01T00:00:00.000
 1970-01-01T00:00:00.000  1970-01-01T00:00:00.000
 1970-01-01T00:00:00.000]

In [13]: repr(t)
Out[13]: array([267859210457, 0, 0, 0, 0], dtype="datetime64[ms]")

In [14]: t[0].item()     # getter in action
Out[14]: datetime.datetime(2008, 7, 16, 13, 39, 25, 315000)

In [15]: print t.dtype
dtype('datetime64[ms]')

And here it goes an example of use for the timedelta64:

In [5]: numpy.timedelta64(10, 'us')
Out[5]: timedelta64(10, 'us')

In [6]: print numpy.timedelta64(10, 'us')
0:00:00.000010

In [7]: print numpy.timedelta64(3600.2, 'm')  # decimal part is lost
2 days, 12:00

In [8]: t1 = numpy.zeros(5, dtype="datetime64[ms]")

In [9]: t2 = numpy.ones(5, dtype="datetime64[ms]")

In [10]: t = t2 - t1

In [11]: t[0] = datetime.timedelta(0, 24)  # setter in action

In [12]: print t
[0:00:24.000  0:00:01.000  0:00:01.000  0:00:01.000  0:00:01.000]

In [13]: print repr(t)
Out[13]: array([24000, 1, 1, 1, 1], dtype="timedelta64[ms]")

In [14]: t[0].item()     # getter in action
Out[14]: datetime.timedelta(0, 24)

In [15]: print t.dtype
dtype('timedelta64[s]')

Operating with date/time arrays

datetime64 vs datetime64

The only arithmetic operation allowed between absolute dates is subtraction:

In [10]: numpy.ones(3, "M8[s]") - numpy.zeros(3, "M8[s]")
Out[10]: array([1, 1, 1], dtype=timedelta64[s])

But not other operations:

In [11]: numpy.ones(3, "M8[s]") + numpy.zeros(3, "M8[s]")
TypeError: unsupported operand type(s) for +: 'numpy.ndarray' and 'numpy.ndarray'

Comparisons between absolute dates are allowed.

Casting rules

When operating (basically, only the subtraction will be allowed) two absolute times with different unit times, the outcome would be to raise an exception. This is because the ranges and time-spans of the different time units can be very different, and it is not clear at all what time unit will be preferred for the user. For example, this should be allowed:

>>> numpy.ones(3, dtype="M8[Y]") - numpy.zeros(3, dtype="M8[Y]")
array([1, 1, 1], dtype="timedelta64[Y]")

But the next should not:

>>> numpy.ones(3, dtype="M8[Y]") - numpy.zeros(3, dtype="M8[ns]")
raise numpy.IncompatibleUnitError  # what unit to choose?

datetime64 vs timedelta64

It will be possible to add and subtract relative times from absolute dates:

In [10]: numpy.zeros(5, "M8[Y]") + numpy.ones(5, "m8[Y]")
Out[10]: array([1971, 1971, 1971, 1971, 1971], dtype=datetime64[Y])

In [11]: numpy.ones(5, "M8[Y]") - 2 * numpy.ones(5, "m8[Y]")
Out[11]: array([1969, 1969, 1969, 1969, 1969], dtype=datetime64[Y])

But not other operations:

In [12]: numpy.ones(5, "M8[Y]") * numpy.ones(5, "m8[Y]")
TypeError: unsupported operand type(s) for *: 'numpy.ndarray' and 'numpy.ndarray'

Casting rules

In this case the absolute time should have priority for determining the time unit of the outcome. That would represent what the people wants to do most of the times. For example, this would allow to do:

>>> series = numpy.array(['1970-01-01', '1970-02-01', '1970-09-01'],
dtype='datetime64[D]')
>>> series2 = series + numpy.timedelta(1, 'Y')  # Add 2 relative years
>>> series2
array(['1972-01-01', '1972-02-01', '1972-09-01'],
dtype='datetime64[D]')  # the 'D'ay time unit has been chosen

timedelta64 vs timedelta64

Finally, it will be possible to operate with relative times as if they were regular int64 dtypes as long as the result can be converted back into a timedelta64:

In [10]: numpy.ones(3, 'm8[us]')
Out[10]: array([1, 1, 1], dtype="timedelta64[us]")

In [11]: (numpy.ones(3, 'm8[M]') + 2) ** 3
Out[11]: array([27, 27, 27], dtype="timedelta64[M]")

But:

In [12]: numpy.ones(5, 'm8') + 1j
TypeError: the result cannot be converted into a ``timedelta64``

Casting rules

When combining two timedelta64 dtypes with different time units the outcome will be the shorter of both (“keep the precision” rule). For example:

In [10]: numpy.ones(3, 'm8[s]') + numpy.ones(3, 'm8[m]')
Out[10]: array([61, 61, 61],  dtype="timedelta64[s]")

However, due to the impossibility to know the exact duration of a relative year or a relative month, when these time units appear in one of the operands, the operation will not be allowed:

In [11]: numpy.ones(3, 'm8[Y]') + numpy.ones(3, 'm8[D]')
raise numpy.IncompatibleUnitError  # how to convert relative years to days?

In order to being able to perform the above operation a new NumPy function, called change_timeunit is proposed. Its signature will be:

change_timeunit(time_object, new_unit, reference)

where ‘time_object’ is the time object whose unit is to be changed, ‘new_unit’ is the desired new time unit, and ‘reference’ is an absolute date (NumPy datetime64 scalar) that will be used to allow the conversion of relative times in case of using time units with an uncertain number of smaller time units (relative years or months cannot be expressed in days).

With this, the above operation can be done as follows:

In [10]: t_years = numpy.ones(3, 'm8[Y]')

In [11]: t_days = numpy.change_timeunit(t_years, 'D', '2001-01-01')

In [12]: t_days + numpy.ones(3, 'm8[D]')
Out[12]: array([366, 366, 366],  dtype="timedelta64[D]")

dtype vs time units conversions

For changing the date/time dtype of an existing array, we propose to use the .astype() method. This will be mainly useful for changing time units.

For example, for absolute dates:

In[10]: t1 = numpy.zeros(5, dtype="datetime64[s]")

In[11]: print t1
[1970-01-01T00:00:00  1970-01-01T00:00:00  1970-01-01T00:00:00
 1970-01-01T00:00:00  1970-01-01T00:00:00]

In[12]: print t1.astype('datetime64[D]')
[1970-01-01  1970-01-01  1970-01-01  1970-01-01  1970-01-01]

For relative times:

In[10]: t1 = numpy.ones(5, dtype="timedelta64[s]")

In[11]: print t1
[1 1 1 1 1]

In[12]: print t1.astype('timedelta64[ms]')
[1000 1000 1000 1000 1000]

Changing directly from/to relative to/from absolute dtypes will not be supported:

In[13]: numpy.zeros(5, dtype="datetime64[s]").astype('timedelta64')
TypeError: data type cannot be converted to the desired type

Business days have the peculiarity that they do not cover a continuous line of time (they have gaps at weekends). Thus, when converting from any ordinary time to business days, it can happen that the original time is not representable. In that case, the result of the conversion is Not a Time (NaT):

In[10]: t1 = numpy.arange(5, dtype="datetime64[D]")

In[11]: print t1
[1970-01-01  1970-01-02  1970-01-03  1970-01-04  1970-01-05]

In[12]: t2 = t1.astype("datetime64[B]")

In[13]: print t2  # 1970 begins in a Thursday
[1970-01-01  1970-01-02  NaT  NaT  1970-01-05]

When converting back to ordinary days, NaT values are left untouched (this happens in all time unit conversions):

In[14]: t3 = t2.astype("datetime64[D]")

In[13]: print t3
[1970-01-01  1970-01-02  NaT  NaT  1970-01-05]

Necessary changes to NumPy

In order to facilitate the addition of the date-time data-types a few changes to NumPy were made:

Addition of metadata to dtypes

All data-types now have a metadata dictionary. It can be set using the metadata keyword during construction of the object.

Date-time data-types will place the word “__frequency__” in the meta-data dictionary containing a 4-tuple with the following parameters.

(basic unit string (str),
number of multiples (int), number of sub-divisions (int), number of events (int)).

Simple time units like ‘D’ for days will thus be specified by (‘D’, 1, 1, 1) in the “__frequency__” key of the metadata. More complicated time units (like ‘[2W/5]//50’) will be indicated by (‘D’, 2, 5, 50).

The “__frequency__” key is reserved for metadata and cannot be set with a dtype constructor.

Ufunc interface extension

ufuncs that have datetime and timedelta arguments can use the Python API during ufunc calls (to raise errors).

There is a new ufunc C-API call to set the data for a particular function pointer (for a particular set of data-types) to be the list of arrays passed in to the ufunc.

Array Intervace Extensions

The array interface is extended to both handle datetime and timedelta typestr (including extended notation).

In addition, the typestr element of the __array_interface__ can be a tuple as long as the version string is 4. The tuple is (‘typestr’, metadata dictionary).

This extension to the typestr concept extends to the descr portion of the __array_interface__. Thus, the second element in the tuple of a list of tuples describing a data-format can itself be a tuple of (‘typestr’, metadata dictionary).

Final considerations

Why the fractional time and events: [3Y/12]//50

It is difficult to come up with enough units to satisfy every need. For example, in C# on Windows the fundamental tick of time is 100ns. Multiple of basic units are simple to handle. Divisors of basic units are harder to handle arbitrarily, but it is common to mentally think of a month as 1/12 of a year, or a day as 1/7 of a week. Therefore, the ability to specify a unit in terms of a fraction of a “larger” unit was implemented.

The event notion (//50) was added to solve a use-case of a commercial sponsor of this NEP. The idea is to allow timestamp to carry both event number and timestamp information. The remainder carries the event number information, while the quotient carries the timestamp information.

Why the origin metadata disappeared

During the discussion of the date/time dtypes in the NumPy list, the idea of having an origin metadata that complemented the definition of the absolute datetime64 was initially found to be useful.

However, after thinking more about this, we found that the combination of an absolute datetime64 with a relative timedelta64 does offer the same functionality while removing the need for the additional origin metadata. This is why we have removed it from this proposal.

Operations with mixed time units

Whenever an operation between two time values of the same dtype with the same unit is accepted, the same operation with time values of different units should be possible (e.g. adding a time delta in seconds and one in microseconds), resulting in an adequate time unit. The exact semantics of this kind of operations is defined int the “Casting rules” subsections of the “Operating with date/time arrays” section.

Due to the peculiarities of business days, it is most probable that operations mixing business days with other time units will not be allowed.

[1] http://docs.python.org/lib/module-datetime.html
[2] http://www.egenix.com/products/python/mxBase/mxDateTime
[3] http://en.wikipedia.org/wiki/Unix_time


A (third) proposal for implementing some date/time types in NumPy

  • Numpy Enhancement Proposals
  • next
  • previous

Table Of Contents

  • A (third) proposal for implementing some date/time types in NumPy
    • Executive summary
    • Types proposed
      • datetime64
        • Time units
        • Building a datetime64 dtype
        • Setting and getting values
        • Comparisons
        • Compatibility issues
      • timedelta64
        • Time units
        • Building a timedelta64 dtype
        • Setting and getting values
        • Comparisons
        • Compatibility issues
    • Examples of use
    • Operating with date/time arrays
      • datetime64 vs datetime64
        • Casting rules
      • datetime64 vs timedelta64
        • Casting rules
      • timedelta64 vs timedelta64
        • Casting rules
    • dtype vs time units conversions
    • Final considerations
      • Why the origin metadata disappeared
      • Operations with mixed time units
      • Why there is not a quarter time unit?

Previous topic

A proposal for implementing some date/time types in NumPy

Next topic

Release Notes

A (third) proposal for implementing some date/time types in NumPy

Author: | Francesc Alted i Abad
Contact: | faltet@pytables.com
Author: | Ivan Vilata i Balaguer
Contact: | ivan@selidor.net
Date: | 2008-07-30

Executive summary

A date/time mark is something very handy to have in many fields where one has to deal with data sets. While Python has several modules that define a date/time type (like the integrated datetime [1] or mx.DateTime [2]), NumPy has a lack of them.

In this document, we are proposing the addition of a series of date/time types to fill this gap. The requirements for the proposed types are two-folded: 1) they have to be fast to operate with and 2) they have to be as compatible as possible with the existing datetime module that comes with Python.

Types proposed

To start with, it is virtually impossible to come up with a single date/time type that fills the needs of every case of use. So, after pondering about different possibilities, we have stuck with two different types, namely datetime64 and timedelta64 (these names are preliminary and can be changed), that can have different time units so as to cover different needs.

Important

the time unit is conceived here as metadata that complements a date/time dtype, without changing the base type. It provides information about the meaning of the stored numbers, not about their structure.

Now follows a detailed description of the proposed types.

datetime64

It represents a time that is absolute (i.e. not relative). It is implemented internally as an int64 type. The internal epoch is the POSIX epoch (see [3]). Like POSIX, the representation of a date doesn’t take leap seconds into account.

In time unit conversions and time representations (but not in other time computations), the value -2**63 (0x8000000000000000) is interpreted as an invalid or unknown date, Not a Time or NaT. See the section on time unit conversions for more information.

Time units

It accepts different time units, each of them implying a different time span. The table below describes the time units supported with their corresponding time spans.

Time unit |  | Time span (years)
Code | Meaning |
Y | year | [9.2e18 BC, 9.2e18 AD]
M | month | [7.6e17 BC, 7.6e17 AD]
W | week | [1.7e17 BC, 1.7e17 AD]
B | business day | [3.5e16 BC, 3.5e16 AD]
D | day | [2.5e16 BC, 2.5e16 AD]
h | hour | [1.0e15 BC, 1.0e15 AD]
m | minute | [1.7e13 BC, 1.7e13 AD]
s | second | [ 2.9e9 BC, 2.9e9 AD]
ms | millisecond | [ 2.9e6 BC, 2.9e6 AD]
us | microsecond | [290301 BC, 294241 AD]
c# | ticks (100ns) | [ 2757 BC, 31197 AD]
ns | nanosecond | [ 1678 AD, 2262 AD]

The value of an absolute date is thus an integer number of units of the chosen time unit passed since the internal epoch. When working with business days, Saturdays and Sundays are simply ignored from the count (i.e. day 3 in business days is not Saturday 1970-01-03, but Monday 1970-01-05).

Building a datetime64 dtype

The proposed ways to specify the time unit in the dtype constructor are:

Using the long string notation:

dtype('datetime64[us]')

Using the short string notation:

dtype('M8[us]')

The default is microseconds if no time unit is specified. Thus, ‘M8’ is equivalent to ‘M8[us]’

Setting and getting values

The objects with this dtype can be set in a series of ways:

t = numpy.ones(3, dtype='M8[s]')
t[0] = 1199164176    # assign to July 30th, 2008 at 17:31:00
t[1] = datetime.datetime(2008, 7, 30, 17, 31, 01) # with datetime module
t[2] = '2008-07-30T17:31:02'    # with ISO 8601

And can be get in different ways too:

str(t[0])  -->  2008-07-30T17:31:00
repr(t[1]) -->  datetime64(1199164177, 's')
str(t[0].item()) --> 2008-07-30 17:31:00  # datetime module object
repr(t[0].item()) --> datetime.datetime(2008, 7, 30, 17, 31)  # idem
str(t)  -->  [2008-07-30T17:31:00  2008-07-30T17:31:01  2008-07-30T17:31:02]
repr(t)  -->  array([1199164176, 1199164177, 1199164178],
                    dtype='datetime64[s]')

Comparisons

The comparisons will be supported too:

numpy.array(['1980'], 'M8[Y]') == numpy.array(['1979'], 'M8[Y]')
--> [False]

or by applying broadcasting:

numpy.array(['1979', '1980'], 'M8[Y]') == numpy.datetime64('1980', 'Y')
--> [False, True]

The next should work too:

numpy.array(['1979', '1980'], 'M8[Y]') == '1980-01-01'
--> [False, True]

because the right hand expression can be broadcasted into an array of 2 elements of dtype ‘M8[Y]’.

Compatibility issues

This will be fully compatible with the datetime class of the datetime module of Python only when using a time unit of microseconds. For other time units, the conversion process will lose precision or will overflow as needed. The conversion from/to a datetime object doesn’t take leap seconds into account.

timedelta64

It represents a time that is relative (i.e. not absolute). It is implemented internally as an int64 type.

In time unit conversions and time representations (but not in other time computations), the value -2**63 (0x8000000000000000) is interpreted as an invalid or unknown time, Not a Time or NaT. See the section on time unit conversions for more information.

Time units

It accepts different time units, each of them implying a different time span. The table below describes the time units supported with their corresponding time spans.

Time unit |  | Time span
Code | Meaning |
Y | year | +- 9.2e18 years
M | month | +- 7.6e17 years
W | week | +- 1.7e17 years
B | business day | +- 3.5e16 years
D | day | +- 2.5e16 years
h | hour | +- 1.0e15 years
m | minute | +- 1.7e13 years
s | second | +- 2.9e12 years
ms | millisecond | +- 2.9e9 years
us | microsecond | +- 2.9e6 years
c# | ticks (100ns) | +- 2.9e4 years
ns | nanosecond | +- 292 years
ps | picosecond | +- 106 days
fs | femtosecond | +- 2.6 hours
as | attosecond | +- 9.2 seconds

The value of a time delta is thus an integer number of units of the chosen time unit.

Building a timedelta64 dtype

The proposed ways to specify the time unit in the dtype constructor are:

Using the long string notation:

dtype('timedelta64[us]')

Using the short string notation:

dtype('m8[us]')

The default is micro-seconds if no default is specified: ‘m8’ is equivalent to ‘m8[us]’

Setting and getting values

The objects with this dtype can be set in a series of ways:

t = numpy.ones(3, dtype='m8[ms]')
t[0] = 12    # assign to 12 ms
t[1] = datetime.timedelta(0, 0, 13000)   # 13 ms
t[2] = '0:00:00.014'    # 14 ms

And can be get in different ways too:

str(t[0])  -->  0:00:00.012
repr(t[1]) -->  timedelta64(13, 'ms')
str(t[0].item()) --> 0:00:00.012000   # datetime module object
repr(t[0].item()) --> datetime.timedelta(0, 0, 12000)  # idem
str(t)     -->  [0:00:00.012  0:00:00.014  0:00:00.014]
repr(t)    -->  array([12, 13, 14], dtype="timedelta64[ms]")

Comparisons

The comparisons will be supported too:

numpy.array([12, 13, 14], 'm8[ms]') == numpy.array([12, 13, 13], 'm8[ms]')
--> [True, True, False]

or by applying broadcasting:

numpy.array([12, 13, 14], 'm8[ms]') == numpy.timedelta64(13, 'ms')
--> [False, True, False]

The next should work too:

numpy.array([12, 13, 14], 'm8[ms]') == '0:00:00.012'
--> [True, False, False]

because the right hand expression can be broadcasted into an array of 3 elements of dtype ‘m8[ms]’.

Compatibility issues

This will be fully compatible with the timedelta class of the datetime module of Python only when using a time unit of microseconds. For other units, the conversion process will lose precision or will overflow as needed.

Examples of use

Here it is an example of use for the datetime64:

In [5]: numpy.datetime64(42, 'us')
Out[5]: datetime64(42, 'us')

In [6]: print numpy.datetime64(42, 'us')
1970-01-01T00:00:00.000042  # representation in ISO 8601 format

In [7]: print numpy.datetime64(367.7, 'D')  # decimal part is lost
1971-01-02  # still ISO 8601 format

In [8]: numpy.datetime('2008-07-18T12:23:18', 'm')  # from ISO 8601
Out[8]: datetime64(20273063, 'm')

In [9]: print numpy.datetime('2008-07-18T12:23:18', 'm')
Out[9]: 2008-07-18T12:23

In [10]: t = numpy.zeros(5, dtype="datetime64[ms]")

In [11]: t[0] = datetime.datetime.now()  # setter in action

In [12]: print t
[2008-07-16T13:39:25.315  1970-01-01T00:00:00.000
 1970-01-01T00:00:00.000  1970-01-01T00:00:00.000
 1970-01-01T00:00:00.000]

In [13]: repr(t)
Out[13]: array([267859210457, 0, 0, 0, 0], dtype="datetime64[ms]")

In [14]: t[0].item()     # getter in action
Out[14]: datetime.datetime(2008, 7, 16, 13, 39, 25, 315000)

In [15]: print t.dtype
dtype('datetime64[ms]')

And here it goes an example of use for the timedelta64:

In [5]: numpy.timedelta64(10, 'us')
Out[5]: timedelta64(10, 'us')

In [6]: print numpy.timedelta64(10, 'us')
0:00:00.000010

In [7]: print numpy.timedelta64(3600.2, 'm')  # decimal part is lost
2 days, 12:00

In [8]: t1 = numpy.zeros(5, dtype="datetime64[ms]")

In [9]: t2 = numpy.ones(5, dtype="datetime64[ms]")

In [10]: t = t2 - t1

In [11]: t[0] = datetime.timedelta(0, 24)  # setter in action

In [12]: print t
[0:00:24.000  0:00:01.000  0:00:01.000  0:00:01.000  0:00:01.000]

In [13]: print repr(t)
Out[13]: array([24000, 1, 1, 1, 1], dtype="timedelta64[ms]")

In [14]: t[0].item()     # getter in action
Out[14]: datetime.timedelta(0, 24)

In [15]: print t.dtype
dtype('timedelta64[s]')

Operating with date/time arrays

datetime64 vs datetime64

The only arithmetic operation allowed between absolute dates is the subtraction:

In [10]: numpy.ones(3, "M8[s]") - numpy.zeros(3, "M8[s]")
Out[10]: array([1, 1, 1], dtype=timedelta64[s])

But not other operations:

In [11]: numpy.ones(3, "M8[s]") + numpy.zeros(3, "M8[s]")
TypeError: unsupported operand type(s) for +: 'numpy.ndarray' and 'numpy.ndarray'

Comparisons between absolute dates are allowed.

Casting rules

When operating (basically, only the subtraction will be allowed) two absolute times with different unit times, the outcome would be to raise an exception. This is because the ranges and time-spans of the different time units can be very different, and it is not clear at all what time unit will be preferred for the user. For example, this should be allowed:

>>> numpy.ones(3, dtype="M8[Y]") - numpy.zeros(3, dtype="M8[Y]")
array([1, 1, 1], dtype="timedelta64[Y]")

But the next should not:

>>> numpy.ones(3, dtype="M8[Y]") - numpy.zeros(3, dtype="M8[ns]")
raise numpy.IncompatibleUnitError  # what unit to choose?

datetime64 vs timedelta64

It will be possible to add and subtract relative times from absolute dates:

In [10]: numpy.zeros(5, "M8[Y]") + numpy.ones(5, "m8[Y]")
Out[10]: array([1971, 1971, 1971, 1971, 1971], dtype=datetime64[Y])

In [11]: numpy.ones(5, "M8[Y]") - 2 * numpy.ones(5, "m8[Y]")
Out[11]: array([1969, 1969, 1969, 1969, 1969], dtype=datetime64[Y])

But not other operations:

In [12]: numpy.ones(5, "M8[Y]") * numpy.ones(5, "m8[Y]")
TypeError: unsupported operand type(s) for *: 'numpy.ndarray' and 'numpy.ndarray'

Casting rules

In this case the absolute time should have priority for determining the time unit of the outcome. That would represent what the people wants to do most of the times. For example, this would allow to do:

>>> series = numpy.array(['1970-01-01', '1970-02-01', '1970-09-01'],
dtype='datetime64[D]')
>>> series2 = series + numpy.timedelta(1, 'Y')  # Add 2 relative years
>>> series2
array(['1972-01-01', '1972-02-01', '1972-09-01'],
dtype='datetime64[D]')  # the 'D'ay time unit has been chosen

timedelta64 vs timedelta64

Finally, it will be possible to operate with relative times as if they were regular int64 dtypes as long as the result can be converted back into a timedelta64:

In [10]: numpy.ones(3, 'm8[us]')
Out[10]: array([1, 1, 1], dtype="timedelta64[us]")

In [11]: (numpy.ones(3, 'm8[M]') + 2) ** 3
Out[11]: array([27, 27, 27], dtype="timedelta64[M]")

But:

In [12]: numpy.ones(5, 'm8') + 1j
TypeError: the result cannot be converted into a ``timedelta64``

Casting rules

When combining two timedelta64 dtypes with different time units the outcome will be the shorter of both (“keep the precision” rule). For example:

In [10]: numpy.ones(3, 'm8[s]') + numpy.ones(3, 'm8[m]')
Out[10]: array([61, 61, 61],  dtype="timedelta64[s]")

However, due to the impossibility to know the exact duration of a relative year or a relative month, when these time units appear in one of the operands, the operation will not be allowed:

In [11]: numpy.ones(3, 'm8[Y]') + numpy.ones(3, 'm8[D]')
raise numpy.IncompatibleUnitError  # how to convert relative years to days?

In order to being able to perform the above operation a new NumPy function, called change_timeunit is proposed. Its signature will be:

change_timeunit(time_object, new_unit, reference)

where ‘time_object’ is the time object whose unit is to be changed, ‘new_unit’ is the desired new time unit, and ‘reference’ is an absolute date (NumPy datetime64 scalar) that will be used to allow the conversion of relative times in case of using time units with an uncertain number of smaller time units (relative years or months cannot be expressed in days).

With this, the above operation can be done as follows:

In [10]: t_years = numpy.ones(3, 'm8[Y]')

In [11]: t_days = numpy.change_timeunit(t_years, 'D', '2001-01-01')

In [12]: t_days + numpy.ones(3, 'm8[D]')
Out[12]: array([366, 366, 366],  dtype="timedelta64[D]")

dtype vs time units conversions

For changing the date/time dtype of an existing array, we propose to use the .astype() method. This will be mainly useful for changing time units.

For example, for absolute dates:

In[10]: t1 = numpy.zeros(5, dtype="datetime64[s]")

In[11]: print t1
[1970-01-01T00:00:00  1970-01-01T00:00:00  1970-01-01T00:00:00
 1970-01-01T00:00:00  1970-01-01T00:00:00]

In[12]: print t1.astype('datetime64[D]')
[1970-01-01  1970-01-01  1970-01-01  1970-01-01  1970-01-01]

For relative times:

In[10]: t1 = numpy.ones(5, dtype="timedelta64[s]")

In[11]: print t1
[1 1 1 1 1]

In[12]: print t1.astype('timedelta64[ms]')
[1000 1000 1000 1000 1000]

Changing directly from/to relative to/from absolute dtypes will not be supported:

In[13]: numpy.zeros(5, dtype="datetime64[s]").astype('timedelta64')
TypeError: data type cannot be converted to the desired type

Business days have the peculiarity that they do not cover a continuous line of time (they have gaps at weekends). Thus, when converting from any ordinary time to business days, it can happen that the original time is not representable. In that case, the result of the conversion is Not a Time (NaT):

In[10]: t1 = numpy.arange(5, dtype="datetime64[D]")

In[11]: print t1
[1970-01-01  1970-01-02  1970-01-03  1970-01-04  1970-01-05]

In[12]: t2 = t1.astype("datetime64[B]")

In[13]: print t2  # 1970 begins in a Thursday
[1970-01-01  1970-01-02  NaT  NaT  1970-01-05]

When converting back to ordinary days, NaT values are left untouched (this happens in all time unit conversions):

In[14]: t3 = t2.astype("datetime64[D]")

In[13]: print t3
[1970-01-01  1970-01-02  NaT  NaT  1970-01-05]

Final considerations

Why the origin metadata disappeared

During the discussion of the date/time dtypes in the NumPy list, the idea of having an origin metadata that complemented the definition of the absolute datetime64 was initially found to be useful.

However, after thinking more about this, we found that the combination of an absolute datetime64 with a relative timedelta64 does offer the same functionality while removing the need for the additional origin metadata. This is why we have removed it from this proposal.

Operations with mixed time units

Whenever an operation between two time values of the same dtype with the same unit is accepted, the same operation with time values of different units should be possible (e.g. adding a time delta in seconds and one in microseconds), resulting in an adequate time unit. The exact semantics of this kind of operations is defined int the “Casting rules” subsections of the “Operating with date/time arrays” section.

Due to the peculiarities of business days, it is most probable that operations mixing business days with other time units will not be allowed.

Why there is not a quarter time unit?

This proposal tries to focus on the most common used set of time units to operate with, and the quarter can be considered more of a derived unit. Besides, the use of a quarter normally requires that it can start at whatever month of the year, and as we are not including support for a time origin metadata, this is not a viable venue here. Finally, if we were to add the quarter then people should expect to find a biweekly, semester or biyearly just to put some examples of other derived units, and we find this a bit too overwhelming for this proposal purposes.

[1] http://docs.python.org/lib/module-datetime.html
[2] http://www.egenix.com/products/python/mxBase/mxDateTime
[3] http://en.wikipedia.org/wiki/Unix_time


Release Notes

  • next
  • previous

Table Of Contents

  • Release Notes
    • NumPy 1.10.0 Release Notes
      • Highlights
      • Dropped Support
      • Future Changes
      • Compatibility notes
      • New Features
        • np.cbrt to compute cube root for real floats
        • numpy.distutils now allows parallel compilation
      • Improvements
        • np.digitize using binary search
        • np.poly now casts integer inputs to float
        • np.interp can now be used with periodic functions
      • Changes
        • dotblas functionality moved to multiarray
        • stricter check of gufunc signature compliance
      • Deprecations
        • SafeEval
        • alterdot, restoredot
        • pkgload, PackageLoader
    • NumPy 1.9.1 Release Notes
      • Issues fixed
    • NumPy 1.9.0 Release Notes
      • Highlights
      • Dropped Support
      • Future Changes
      • Compatibility notes
        • The diagonal and diag functions return readonly views.
        • Special scalar float values don’t cause upcast to double anymore
        • Percentile output changes
        • ndarray.tofile exception type
        • Invalid fill value exceptions
        • Polynomial Classes no longer derived from PolyBase
        • Using numpy.random.binomial may change the RNG state vs. numpy < 1.9
        • Random seed enforced to be a 32 bit unsigned integer
        • Argmin and argmax out argument
        • Einsum
        • Indexing
        • Non-integer reduction axis indexes are deprecated
        • promote_types and string dtype
        • can_cast and string dtype
        • astype and string dtype
        • npyio.recfromcsv keyword arguments change
        • The doc/swig directory moved
        • The npy_3kcompat.h header changed
        • Negative indices in C-Api sq_item and sq_ass_item sequence methods
        • NDIter
        • zeros_like for string dtypes now returns empty strings
      • New Features
        • Percentile supports more interpolation options
        • Generalized axis support for median and percentile
        • Dtype parameter added to np.linspace and np.logspace
        • More general np.triu and np.tril broadcasting
        • tobytes alias for tostring method
        • Build system
        • Compatibility to python numbers module
        • increasing parameter added to np.vander
        • unique_counts parameter added to np.unique
        • Support for median and percentile in nanfunctions
        • NumpyVersion class added
        • Allow saving arrays with large number of named columns
        • Full broadcasting support for np.cross
      • Improvements
        • Better numerical stability for sum in some cases
        • Percentile implemented in terms of np.partition
        • Performance improvement for np.array
        • Performance improvement for np.searchsorted
        • Optional reduced verbosity for np.distutils
        • Covariance check in np.random.multivariate_normal
        • Polynomial Classes no longer template based
        • More GIL releases
        • MaskedArray support for more complicated base classes
        • C-API
      • Deprecations
        • Non-integer scalars for sequence repetition
        • select input deprecations
        • rank function
        • Object array equality comparisons
        • C-API
    • NumPy 1.8.2 Release Notes
      • Issues fixed
    • NumPy 1.8.1 Release Notes
      • Issues fixed
      • Changes
        • NDIter
        • Optional reduced verbosity for np.distutils
      • Deprecations
        • C-API
    • NumPy 1.8.0 Release Notes
      • Highlights
      • Dropped Support
      • Future Changes
      • Compatibility notes
        • NPY_RELAXED_STRIDES_CHECKING
        • Binary operations with non-arrays as second argument
        • Function median used with overwrite_input only partially sorts array
        • Fix to financial.npv
        • Runtime warnings when comparing NaN numbers
      • New Features
        • Support for linear algebra on stacked arrays
        • In place fancy indexing for ufuncs
        • New functions partition and argpartition
        • New functions nanmean, nanvar and nanstd
        • New functions full and full_like
        • IO compatibility with large files
        • Building against OpenBLAS
        • New constant
        • New modes for qr
        • New invert argument to in1d
        • Advanced indexing using np.newaxis
        • C-API
        • runtests.py
      • Improvements
        • IO performance improvements
        • Performance improvements to pad
        • Performance improvements to isnan, isinf, isfinite and byteswap
        • Performance improvements via SSE2 vectorization
        • Performance improvements to median
        • Overrideable operand flags in ufunc C-API
      • Changes
        • General
        • C-API Array Additions
        • C-API Ufunc Additions
        • C-API Developer Improvements
      • Deprecations
        • General
      • Authors
    • NumPy 1.7.2 Release Notes
      • Issues fixed
    • NumPy 1.7.1 Release Notes
      • Issues fixed
    • NumPy 1.7.0 Release Notes
      • Highlights
      • Compatibility notes
      • New features
        • Reduction UFuncs Generalize axis= Parameter
        • Reduction UFuncs New keepdims= Parameter
        • Datetime support
        • Custom formatter for printing arrays
        • New function numpy.random.choice
        • New function isclose
        • Preliminary multi-dimensional support in the polynomial package
        • Ability to pad rank-n arrays
        • New argument to searchsorted
        • Build system
        • C API
      • Changes
        • General
        • Casting Rules
      • Deprecations
        • General
        • C-API
    • NumPy 1.6.2 Release Notes
      • Issues fixed
        • numpy.core
        • numpy.lib
        • numpy.distutils
        • numpy.random
      • Changes
        • numpy.f2py
        • numpy.poly
    • NumPy 1.6.1 Release Notes
      • Issues Fixed
    • NumPy 1.6.0 Release Notes
      • Highlights
      • New features
        • New 16-bit floating point type
        • New iterator
        • Legendre, Laguerre, Hermite, HermiteE polynomials in numpy.polynomial
        • Fortran assumed shape array and size function support in numpy.f2py
        • Other new functions
      • Changes
        • default error handling
        • numpy.distutils
        • numpy.testing
        • C API
      • Deprecated features
      • Removed features
        • numpy.fft
        • numpy.memmap
        • numpy.lib
        • numpy.ma
        • numpy.distutils
    • NumPy 1.5.0 Release Notes
      • Highlights
        • Python 3 compatibility
        • PEP 3118 compatibility
      • New features
        • Warning on casting complex to real
        • Dot method for ndarrays
        • linalg.slogdet function
        • new header
      • Changes
        • polynomial.polynomial
        • polynomial.chebyshev
        • histogram
        • correlate
    • NumPy 1.4.0 Release Notes
      • Highlights
      • New features
        • Extended array wrapping mechanism for ufuncs
        • Automatic detection of forward incompatibilities
        • New iterators
        • New polynomial support
        • New C API
        • New ufuncs
        • New defines
        • Testing
        • Reusing npymath
        • Improved set operations
      • Improvements
      • Deprecations
      • Internal changes
        • Use C99 complex functions when available
        • split multiarray and umath source code
        • Separate compilation
        • Separate core math library
    • NumPy 1.3.0 Release Notes
      • Highlights
        • Python 2.6 support
        • Generalized ufuncs
        • Experimental Windows 64 bits support
      • New features
        • Formatting issues
        • Nan handling in max/min
        • Nan handling in sign
        • New ufuncs
        • Masked arrays
        • gfortran support on windows
        • Arch option for windows binary
      • Deprecated features
        • Histogram
      • Documentation changes
      • New C API
        • Multiarray API
        • Ufunc API
        • New defines
        • Portable NAN, INFINITY, etc...
      • Internal changes
        • numpy.core math configuration revamp
        • umath refactor
        • Improvements to build warnings
        • Separate core math library
        • CPU arch detection

Previous topic

A (third) proposal for implementing some date/time types in NumPy

Next topic

About NumPy

Release Notes

NumPy 1.10.0 Release Notes

This release supports Python 2.6 - 2.7 and 3.2 - 3.4.

Highlights

  • numpy.distutils now supports parallel compilation via the –jobs/-j argument passed to setup.py build
  • Addition of np.linalg.multi_dot: compute the dot product of two or more arrays in a single function call, while automatically selecting the fastest evaluation order.

Dropped Support

  • The polytemplate.py file has been removed.
  • The _dotblas module is no longer available.
  • The testcalcs.py file has been removed.

Future Changes

  • The SafeEval class will be removed.
  • The alterdot and restoredot functions will be removed.

Compatibility notes

NPY_RELAXED_STRIDE_CHECKING is now true by default.

New Features

np.cbrt to compute cube root for real floats

np.cbrt wraps the C99 cube root function cbrt. Compared to np.power(x, 1./3.) it is well defined for negative real floats and a bit faster.

numpy.distutils now allows parallel compilation

By passing –jobs=n or -j n to setup.py build the compilation of extensions is now performed in n parallel processes. The parallelization is limited to files within one extension so projects using Cython will not profit because it builds extensions from single files.

Improvements

np.digitize using binary search

np.digitize is now implemented in terms of np.searchsorted. This means that a binary search is used to bin the values, which scales much better for larger number of bins than the previous linear search. It also removes the requirement for the input array to be 1-dimensional.

np.poly now casts integer inputs to float

np.poly will now cast 1-dimensional input arrays of integer type to double precision floating point, to prevent integer overflow when computing the monic polynomial. It is still possible to obtain higher precision results by passing in an array of object type, filled e.g. with Python ints.

np.interp can now be used with periodic functions

np.interp now has a new parameter period that supplies the period of the input data xp. In such case, the input data is properly normalized to the given period and one end point is added to each extremity of xp in order to close the previous and the next period cycles, resulting in the correct interpolation behavior.

Changes

dotblas functionality moved to multiarray

The cblas versions of dot, inner, and vdot have been integrated into the multiarray module. In particular, vdot is now a multiarray function, which it was not before.

stricter check of gufunc signature compliance

Inputs to generalized universal functions are now more strictly checked against the function’s signature: all core dimensions are now required to be present in input arrays; core dimensions with the same label must have the exact same size; and output core dimension’s must be specified, either by a same label input core dimension or by a passed-in output array.

Deprecations

SafeEval

The SafeEval class in numpy/lib/utils.py is deprecated and will be removed in the next release.

alterdot, restoredot

The alterdot and restoredot functions no longer do anything, and are deprecated.

pkgload, PackageLoader

These ways of loading packages are now deprecated.

NumPy 1.9.1 Release Notes

This is a bugfix only release in the 1.9.x series.

Issues fixed

  • gh-5184: restore linear edge behaviour of gradient to as it was in < 1.9. The second order behaviour is available via the edge_order keyword
  • gh-4007: workaround Accelerate sgemv crash on OSX 10.9
  • gh-5100: restore object dtype inference from iterable objects without len()
  • gh-5163: avoid gcc-4.1.2 (red hat 5) miscompilation causing a crash
  • gh-5138: fix nanmedian on arrays containing inf
  • gh-5240: fix not returning out array from ufuncs with subok=False set
  • gh-5203: copy inherited masks in MaskedArray.__array_finalize__
  • gh-2317: genfromtxt did not handle filling_values=0 correctly
  • gh-5067: restore api of npy_PyFile_DupClose in python2
  • gh-5063: cannot convert invalid sequence index to tuple
  • gh-5082: Segmentation fault with argmin() on unicode arrays
  • gh-5095: don’t propagate subtypes from np.where
  • gh-5104: np.inner segfaults with SciPy’s sparse matrices
  • gh-5251: Issue with fromarrays not using correct format for unicode arrays
  • gh-5136: Import dummy_threading if importing threading fails
  • gh-5148: Make numpy import when run with Python flag ‘-OO’
  • gh-5147: Einsum double contraction in particular order causes ValueError
  • gh-479: Make f2py work with intent(in out)
  • gh-5170: Make python2 .npy files readable in python3
  • gh-5027: Use ‘ll’ as the default length specifier for long long
  • gh-4896: fix build error with MSVC 2013 caused by C99 complex support
  • gh-4465: Make PyArray_PutTo respect writeable flag
  • gh-5225: fix crash when using arange on datetime without dtype set
  • gh-5231: fix build in c99 mode

NumPy 1.9.0 Release Notes

This release supports Python 2.6 - 2.7 and 3.2 - 3.4.

Highlights

  • Numerous performance improvements in various areas, most notably indexing and operations on small arrays are significantly faster. Indexing operations now also release the GIL.
  • Addition of nanmedian and nanpercentile rounds out the nanfunction set.

Dropped Support

  • The oldnumeric and numarray modules have been removed.
  • The doc/pyrex and doc/cython directories have been removed.
  • The doc/numpybook directory has been removed.
  • The numpy/testing/numpytest.py file has been removed together with the importall function it contained.

Future Changes

  • The numpy/polynomial/polytemplate.py file will be removed in NumPy 1.10.0.
  • Default casting for inplace operations will change to ‘same_kind’ in Numpy 1.10.0. This will certainly break some code that is currently ignoring the warning.
  • Relaxed stride checking will be the default in 1.10.0
  • String version checks will break because, e.g., ‘1.9’ > ‘1.10’ is True. A NumpyVersion class has been added that can be used for such comparisons.
  • The diagonal and diag functions will return writeable views in 1.10.0
  • The S and/or a dtypes may be changed to represent Python strings instead of bytes, in Python 3 these two types are very different.

Compatibility notes

The diagonal and diag functions return readonly views.

In NumPy 1.8, the diagonal and diag functions returned readonly copies, in NumPy 1.9 they return readonly views, and in 1.10 they will return writeable views.

Special scalar float values don’t cause upcast to double anymore

In previous numpy versions operations involving floating point scalars containing special values NaN, Inf and -Inf caused the result type to be at least float64. As the special values can be represented in the smallest available floating point type, the upcast is not performed anymore.

For example the dtype of:

np.array([1.], dtype=np.float32) * float('nan')

now remains float32 instead of being cast to float64. Operations involving non-special values have not been changed.

Percentile output changes

If given more than one percentile to compute numpy.percentile returns an array instead of a list. A single percentile still returns a scalar. The array is equivalent to converting the list returned in older versions to an array via np.array.

If the overwrite_input option is used the input is only partially instead of fully sorted.

ndarray.tofile exception type

All tofile exceptions are now IOError, some were previously ValueError.

Invalid fill value exceptions

Two changes to numpy.ma.core._check_fill_value:

  • When the fill value is a string and the array type is not one of ‘OSUV’, TypeError is raised instead of the default fill value being used.
  • When the fill value overflows the array type, TypeError is raised instead of OverflowError.

Polynomial Classes no longer derived from PolyBase

This may cause problems with folks who depended on the polynomial classes being derived from PolyBase. They are now all derived from the abstract base class ABCPolyBase. Strictly speaking, there should be a deprecation involved, but no external code making use of the old baseclass could be found.

Using numpy.random.binomial may change the RNG state vs. numpy < 1.9

A bug in one of the algorithms to generate a binomial random variate has been fixed. This change will likely alter the number of random draws performed, and hence the sequence location will be different after a call to distribution.c::rk_binomial_btpe. Any tests which rely on the RNG being in a known state should be checked and/or updated as a result.

Random seed enforced to be a 32 bit unsigned integer

np.random.seed and np.random.RandomState now throw a ValueError if the seed cannot safely be converted to 32 bit unsigned integers. Applications that now fail can be fixed by masking the higher 32 bit values to zero: seed = seed & 0xFFFFFFFF. This is what is done silently in older versions so the random stream remains the same.

Argmin and argmax out argument

The out argument to np.argmin and np.argmax and their equivalent C-API functions is now checked to match the desired output shape exactly. If the check fails a ValueError instead of TypeError is raised.

Einsum

Remove unnecessary broadcasting notation restrictions. np.einsum('ijk,j->ijk', A, B) can also be written as np.einsum('ij...,j->ij...', A, B) (ellipsis is no longer required on ‘j’)

Indexing

The NumPy indexing has seen a complete rewrite in this version. This makes most advanced integer indexing operations much faster and should have no other implications. However some subtle changes and deprecations were introduced in advanced indexing operations:

  • Boolean indexing into scalar arrays will always return a new 1-d array. This means that array(1)[array(True)] gives array([1]) and not the original array.
  • Advanced indexing into one dimensional arrays used to have (undocumented) special handling regarding repeating the value array in assignments when the shape of the value array was too small or did not match. Code using this will raise an error. For compatibility you can use arr.flat[index] = values, which uses the old code branch. (for example a = np.ones(10); a[np.arange(10)] = [1, 2, 3])
  • The iteration order over advanced indexes used to be always C-order. In NumPy 1.9. the iteration order adapts to the inputs and is not guaranteed (with the exception of a single advanced index which is never reversed for compatibility reasons). This means that the result is undefined if multiple values are assigned to the same element. An example for this is arr[[0, 0], [1, 1]] = [1, 2], which may set arr[0, 1] to either 1 or 2.
  • Equivalent to the iteration order, the memory layout of the advanced indexing result is adapted for faster indexing and cannot be predicted.
  • All indexing operations return a view or a copy. No indexing operation will return the original array object. (For example arr[...])
  • In the future Boolean array-likes (such as lists of python bools) will always be treated as Boolean indexes and Boolean scalars (including python True) will be a legal boolean index. At this time, this is already the case for scalar arrays to allow the general positive = a[a > 0] to work when a is zero dimensional.
  • In NumPy 1.8 it was possible to use array(True) and array(False) equivalent to 1 and 0 if the result of the operation was a scalar. This will raise an error in NumPy 1.9 and, as noted above, treated as a boolean index in the future.
  • All non-integer array-likes are deprecated, object arrays of custom integer like objects may have to be cast explicitly.
  • The error reporting for advanced indexing is more informative, however the error type has changed in some cases. (Broadcasting errors of indexing arrays are reported as IndexError)
  • Indexing with more then one ellipsis (...) is deprecated.

Non-integer reduction axis indexes are deprecated

Non-integer axis indexes to reduction ufuncs like add.reduce or sum are deprecated.

promote_types and string dtype

promote_types function now returns a valid string length when given an integer or float dtype as one argument and a string dtype as another argument. Previously it always returned the input string dtype, even if it wasn’t long enough to store the max integer/float value converted to a string.

can_cast and string dtype

can_cast function now returns False in “safe” casting mode for integer/float dtype and string dtype if the string dtype length is not long enough to store the max integer/float value converted to a string. Previously can_cast in “safe” mode returned True for integer/float dtype and a string dtype of any length.

astype and string dtype

The astype method now returns an error if the string dtype to cast to is not long enough in “safe” casting mode to hold the max value of integer/float array that is being casted. Previously the casting was allowed even if the result was truncated.

npyio.recfromcsv keyword arguments change

npyio.recfromcsv no longer accepts the undocumented update keyword, which used to override the dtype keyword.

The doc/swig directory moved

The doc/swig directory has been moved to tools/swig.

The npy_3kcompat.h header changed

The unused simple_capsule_dtor function has been removed from npy_3kcompat.h. Note that this header is not meant to be used outside of numpy; other projects should be using their own copy of this file when needed.

Negative indices in C-Api sq_item and sq_ass_item sequence methods

When directly accessing the sq_item or sq_ass_item PyObject slots for item getting, negative indices will not be supported anymore. PySequence_GetItem and PySequence_SetItem however fix negative indices so that they can be used there.

NDIter

When NpyIter_RemoveAxis is now called, the iterator range will be reset.

When a multi index is being tracked and an iterator is not buffered, it is possible to use NpyIter_RemoveAxis. In this case an iterator can shrink in size. Because the total size of an iterator is limited, the iterator may be too large before these calls. In this case its size will be set to -1 and an error issued not at construction time but when removing the multi index, setting the iterator range, or getting the next function.

This has no effect on currently working code, but highlights the necessity of checking for an error return if these conditions can occur. In most cases the arrays being iterated are as large as the iterator so that such a problem cannot occur.

This change was already applied to the 1.8.1 release.

zeros_like for string dtypes now returns empty strings

To match the zeros function zeros_like now returns an array initialized with empty strings instead of an array filled with ‘0’.

New Features

Percentile supports more interpolation options

np.percentile now has the interpolation keyword argument to specify in which way points should be interpolated if the percentiles fall between two values. See the documentation for the available options.

Generalized axis support for median and percentile

np.median and np.percentile now support generalized axis arguments like ufunc reductions do since 1.7. One can now say axis=(index, index) to pick a list of axes for the reduction. The keepdims keyword argument was also added to allow convenient broadcasting to arrays of the original shape.

Dtype parameter added to np.linspace and np.logspace

The returned data type from the linspace and logspace functions can now be specified using the dtype parameter.

More general np.triu and np.tril broadcasting

For arrays with ndim exceeding 2, these functions will now apply to the final two axes instead of raising an exception.

tobytes alias for tostring method

ndarray.tobytes and MaskedArray.tobytes have been added as aliases for tostring which exports arrays as bytes. This is more consistent in Python 3 where str and bytes are not the same.

Build system

Added experimental support for the ppc64le and OpenRISC architecture.

Compatibility to python numbers module

All numerical numpy types are now registered with the type hierarchy in the python numbers module.

increasing parameter added to np.vander

The ordering of the columns of the Vandermonde matrix can be specified with this new boolean argument.

unique_counts parameter added to np.unique

The number of times each unique item comes up in the input can now be obtained as an optional return value.

Support for median and percentile in nanfunctions

The np.nanmedian and np.nanpercentile functions behave like the median and percentile functions except that NaNs are ignored.

NumpyVersion class added

The class may be imported from numpy.lib and can be used for version comparison when the numpy version goes to 1.10.devel. For example:

>>> from numpy.lib import NumpyVersion
>>> if NumpyVersion(np.__version__) < '1.10.0'):
...     print('Wow, that is an old NumPy version!')

Allow saving arrays with large number of named columns

The numpy storage format 1.0 only allowed the array header to have a total size of 65535 bytes. This can be exceeded by structured arrays with a large number of columns. A new format 2.0 has been added which extends the header size to 4 GiB. np.save will automatically save in 2.0 format if the data requires it, else it will always use the more compatible 1.0 format.

Full broadcasting support for np.cross

np.cross now properly broadcasts its two input arrays, even if they have different number of dimensions. In earlier versions this would result in either an error being raised, or wrong results computed.

Improvements

Better numerical stability for sum in some cases

Pairwise summation is now used in the sum method, but only along the fast axis and for groups of the values <= 8192 in length. This should also improve the accuracy of var and std in some common cases.

Percentile implemented in terms of np.partition

np.percentile has been implemented in terms of np.partition which only partially sorts the data via a selection algorithm. This improves the time complexity from O(nlog(n)) to O(n).

Performance improvement for np.array

The performance of converting lists containing arrays to arrays using np.array has been improved. It is now equivalent in speed to np.vstack(list).

Performance improvement for np.searchsorted

For the built-in numeric types, np.searchsorted no longer relies on the data type’s compare function to perform the search, but is now implemented by type specific functions. Depending on the size of the inputs, this can result in performance improvements over 2x.

Optional reduced verbosity for np.distutils

Set numpy.distutils.system_info.system_info.verbosity = 0 and then calls to numpy.distutils.system_info.get_info('blas_opt') will not print anything on the output. This is mostly for other packages using numpy.distutils.

Covariance check in np.random.multivariate_normal

A RuntimeWarning warning is raised when the covariance matrix is not positive-semidefinite.

Polynomial Classes no longer template based

The polynomial classes have been refactored to use an abstract base class rather than a template in order to implement a common interface. This makes importing the polynomial package faster as the classes do not need to be compiled on import.

More GIL releases

Several more functions now release the Global Interpreter Lock allowing more efficient parallization using the threading module. Most notably the GIL is now released for fancy indexing, np.where and the random module now uses a per-state lock instead of the GIL.

MaskedArray support for more complicated base classes

Built-in assumptions that the baseclass behaved like a plain array are being removed. In particalur, repr and str should now work more reliably.

C-API

Deprecations

Non-integer scalars for sequence repetition

Using non-integer numpy scalars to repeat python sequences is deprecated. For example np.float_(2) * [1] will be an error in the future.

select input deprecations

The integer and empty input to select is deprecated. In the future only boolean arrays will be valid conditions and an empty condlist will be considered an input error instead of returning the default.

rank function

The rank function has been deprecated to avoid confusion with numpy.linalg.matrix_rank.

Object array equality comparisons

In the future object array comparisons both == and np.equal will not make use of identity checks anymore. For example:

>>> a = np.array([np.array([1, 2, 3]), 1])
>>> b = np.array([np.array([1, 2, 3]), 1])
>>> a == b

will consistently return False (and in the future an error) even if the array in a and b was the same object.

The equality operator == will in the future raise errors like np.equal if broadcasting or element comparisons, etc. fails.

Comparison with arr == None will in the future do an elementwise comparison instead of just returning False. Code should be using arr is None.

All of these changes will give Deprecation- or FutureWarnings at this time.

C-API

The utility function npy_PyFile_Dup and npy_PyFile_DupClose are broken by the internal buffering python 3 applies to its file objects. To fix this two new functions npy_PyFile_Dup2 and npy_PyFile_DupClose2 are declared in npy_3kcompat.h and the old functions are deprecated. Due to the fragile nature of these functions it is recommended to instead use the python API when possible.

This change was already applied to the 1.8.1 release.

NumPy 1.8.2 Release Notes

This is a bugfix only release in the 1.8.x series.

Issues fixed

  • gh-4836: partition produces wrong results for multiple selections in equal ranges
  • gh-4656: Make fftpack._raw_fft threadsafe
  • gh-4628: incorrect argument order to _copyto in in np.nanmax, np.nanmin
  • gh-4642: Hold GIL for converting dtypes types with fields
  • gh-4733: fix np.linalg.svd(b, compute_uv=False)
  • gh-4853: avoid unaligned simd load on reductions on i386
  • gh-4722: Fix seg fault converting empty string to object
  • gh-4613: Fix lack of NULL check in array_richcompare
  • gh-4774: avoid unaligned access for strided byteswap
  • gh-650: Prevent division by zero when creating arrays from some buffers
  • gh-4602: ifort has issues with optimization flag O2, use O1

NumPy 1.8.1 Release Notes

This is a bugfix only release in the 1.8.x series.

Issues fixed

  • gh-4276: Fix mean, var, std methods for object arrays
  • gh-4262: remove insecure mktemp usage
  • gh-2385: absolute(complex(inf)) raises invalid warning in python3
  • gh-4024: Sequence assignment doesn’t raise exception on shape mismatch
  • gh-4027: Fix chunked reading of strings longer than BUFFERSIZE
  • gh-4109: Fix object scalar return type of 0-d array indices
  • gh-4018: fix missing check for memory allocation failure in ufuncs
  • gh-4156: high order linalg.norm discards imaginary elements of complex arrays
  • gh-4144: linalg: norm fails on longdouble, signed int
  • gh-4094: fix NaT handling in _strided_to_strided_string_to_datetime
  • gh-4051: fix uninitialized use in _strided_to_strided_string_to_datetime
  • gh-4093: Loading compressed .npz file fails under Python 2.6.6
  • gh-4138: segfault with non-native endian memoryview in python 3.4
  • gh-4123: Fix missing NULL check in lexsort
  • gh-4170: fix native-only long long check in memoryviews
  • gh-4187: Fix large file support on 32 bit
  • gh-4152: fromfile: ensure file handle positions are in sync in python3
  • gh-4176: clang compatibility: Typos in conversion_utils
  • gh-4223: Fetching a non-integer item caused array return
  • gh-4197: fix minor memory leak in memoryview failure case
  • gh-4206: fix build with single-threaded python
  • gh-4220: add versionadded:: 1.8.0 to ufunc.at docstring
  • gh-4267: improve handling of memory allocation failure
  • gh-4267: fix use of capi without gil in ufunc.at
  • gh-4261: Detect vendor versions of GNU Compilers
  • gh-4253: IRR was returning nan instead of valid negative answer
  • gh-4254: fix unnecessary byte order flag change for byte arrays
  • gh-3263: numpy.random.shuffle clobbers mask of a MaskedArray
  • gh-4270: np.random.shuffle not work with flexible dtypes
  • gh-3173: Segmentation fault when ‘size’ argument to random.multinomial
  • gh-2799: allow using unique with lists of complex
  • gh-3504: fix linspace truncation for integer array scalar
  • gh-4191: get_info(‘openblas’) does not read libraries key
  • gh-3348: Access violation in _descriptor_from_pep3118_format
  • gh-3175: segmentation fault with numpy.array() from bytearray
  • gh-4266: histogramdd - wrong result for entries very close to last boundary
  • gh-4408: Fix stride_stricks.as_strided function for object arrays
  • gh-4225: fix log1p and exmp1 return for np.inf on windows compiler builds
  • gh-4359: Fix infinite recursion in str.format of flex arrays
  • gh-4145: Incorrect shape of broadcast result with the exponent operator
  • gh-4483: Fix commutativity of {dot,multiply,inner}(scalar, matrix_of_objs)
  • gh-4466: Delay npyiter size check when size may change
  • gh-4485: Buffered stride was erroneously marked fixed
  • gh-4354: byte_bounds fails with datetime dtypes
  • gh-4486: segfault/error converting from/to high-precision datetime64 objects
  • gh-4428: einsum(None, None, None, None) causes segfault
  • gh-4134: uninitialized use for for size 1 object reductions

Changes

NDIter

When NpyIter_RemoveAxis is now called, the iterator range will be reset.

When a multi index is being tracked and an iterator is not buffered, it is possible to use NpyIter_RemoveAxis. In this case an iterator can shrink in size. Because the total size of an iterator is limited, the iterator may be too large before these calls. In this case its size will be set to -1 and an error issued not at construction time but when removing the multi index, setting the iterator range, or getting the next function.

This has no effect on currently working code, but highlights the necessity of checking for an error return if these conditions can occur. In most cases the arrays being iterated are as large as the iterator so that such a problem cannot occur.

Optional reduced verbosity for np.distutils

Set numpy.distutils.system_info.system_info.verbosity = 0 and then calls to numpy.distutils.system_info.get_info('blas_opt') will not print anything on the output. This is mostly for other packages using numpy.distutils.

Deprecations

C-API

The utility function npy_PyFile_Dup and npy_PyFile_DupClose are broken by the internal buffering python 3 applies to its file objects. To fix this two new functions npy_PyFile_Dup2 and npy_PyFile_DupClose2 are declared in npy_3kcompat.h and the old functions are deprecated. Due to the fragile nature of these functions it is recommended to instead use the python API when possible.

NumPy 1.8.0 Release Notes

This release supports Python 2.6 -2.7 and 3.2 - 3.3.

Highlights

  • New, no 2to3, Python 2 and Python 3 are supported by a common code base.
  • New, gufuncs for linear algebra, enabling operations on stacked arrays.
  • New, inplace fancy indexing for ufuncs with the .at method.
  • New, partition function, partial sorting via selection for fast median.
  • New, nanmean, nanvar, and nanstd functions skipping NaNs.
  • New, full and full_like functions to create value initialized arrays.
  • New, PyUFunc_RegisterLoopForDescr, better ufunc support for user dtypes.
  • Numerous performance improvements in many areas.

Dropped Support

Support for Python versions 2.4 and 2.5 has been dropped,

Support for SCons has been removed.

Future Changes

The Datetime64 type remains experimental in this release. In 1.9 there will probably be some changes to make it more useable.

The diagonal method currently returns a new array and raises a FutureWarning. In 1.9 it will return a readonly view.

Multiple field selection from a array of structured type currently returns a new array and raises a FutureWarning. In 1.9 it will return a readonly view.

The numpy/oldnumeric and numpy/numarray compatibility modules will be removed in 1.9.

Compatibility notes

The doc/sphinxext content has been moved into its own github repository, and is included in numpy as a submodule. See the instructions in doc/HOWTO_BUILD_DOCS.rst.txt for how to access the content.

The hash function of numpy.void scalars has been changed. Previously the pointer to the data was hashed as an integer. Now, the hash function uses the tuple-hash algorithm to combine the hash functions of the elements of the scalar, but only if the scalar is read-only.

Numpy has switched its build system to using ‘separate compilation’ by default. In previous releases this was supported, but not default. This should produce the same results as the old system, but if you’re trying to do something complicated like link numpy statically or using an unusual compiler, then it’s possible you will encounter problems. If so, please file a bug and as a temporary workaround you can re-enable the old build system by exporting the shell variable NPY_SEPARATE_COMPILATION=0.

For the AdvancedNew iterator the oa_ndim flag should now be -1 to indicate that no op_axes and itershape are passed in. The oa_ndim == 0 case, now indicates a 0-D iteration and op_axes being NULL and the old usage is deprecated. This does not effect the NpyIter_New or NpyIter_MultiNew functions.

The functions nanargmin and nanargmax now return np.iinfo[‘intp’].min for the index in all-NaN slices. Previously the functions would raise a ValueError for array returns and NaN for scalar returns.

NPY_RELAXED_STRIDES_CHECKING

There is a new compile time environment variable NPY_RELAXED_STRIDES_CHECKING. If this variable is set to 1, then numpy will consider more arrays to be C- or F-contiguous – for example, it becomes possible to have a column vector which is considered both C- and F-contiguous simultaneously. The new definition is more accurate, allows for faster code that makes fewer unnecessary copies, and simplifies numpy’s code internally. However, it may also break third-party libraries that make too-strong assumptions about the stride values of C- and F-contiguous arrays. (It is also currently known that this breaks Cython code using memoryviews, which will be fixed in Cython.) THIS WILL BECOME THE DEFAULT IN A FUTURE RELEASE, SO PLEASE TEST YOUR CODE NOW AGAINST NUMPY BUILT WITH:

NPY_RELAXED_STRIDES_CHECKING=1 python setup.py install

You can check whether NPY_RELAXED_STRIDES_CHECKING is in effect by running:

np.ones((10, 1), order="C").flags.f_contiguous

This will be True if relaxed strides checking is enabled, and False otherwise. The typical problem we’ve seen so far is C code that works with C-contiguous arrays, and assumes that the itemsize can be accessed by looking at the last element in the PyArray_STRIDES(arr) array. When relaxed strides are in effect, this is not true (and in fact, it never was true in some corner cases). Instead, use PyArray_ITEMSIZE(arr).

For more information check the “Internal memory layout of an ndarray” section in the documentation.

Binary operations with non-arrays as second argument

Binary operations of the form <array-or-subclass> * <non-array-subclass> where <non-array-subclass> declares an __array_priority__ higher than that of <array-or-subclass> will now unconditionally return NotImplemented, giving <non-array-subclass> a chance to handle the operation. Previously, NotImplemented would only be returned if <non-array-subclass> actually implemented the reversed operation, and after a (potentially expensive) array conversion of <non-array-subclass> had been attempted. (bug, pull request)

Function median used with overwrite_input only partially sorts array

If median is used with overwrite_input option the input array will now only be partially sorted instead of fully sorted.

Fix to financial.npv

The npv function had a bug. Contrary to what the documentation stated, it summed from indexes 1 to M instead of from 0 to M - 1. The fix changes the returned value. The mirr function called the npv function, but worked around the problem, so that was also fixed and the return value of the mirr function remains unchanged.

Runtime warnings when comparing NaN numbers

Comparing NaN floating point numbers now raises the invalid runtime warning. If a NaN is expected the warning can be ignored using np.errstate. E.g.:

with np.errstate(invalid='ignore'):
    operation()

New Features

Support for linear algebra on stacked arrays

The gufunc machinery is now used for np.linalg, allowing operations on stacked arrays and vectors. For example:

>>> a
array([[[ 1.,  1.],
        [ 0.,  1.]],

       [[ 1.,  1.],
        [ 0.,  1.]]])

>>> np.linalg.inv(a)
array([[[ 1., -1.],
        [ 0.,  1.]],

       [[ 1., -1.],
        [ 0.,  1.]]])

In place fancy indexing for ufuncs

The function at has been added to ufunc objects to allow in place ufuncs with no buffering when fancy indexing is used. For example, the following will increment the first and second items in the array, and will increment the third item twice: numpy.add.at(arr, [0, 1, 2, 2], 1)

This is what many have mistakenly thought arr[[0, 1, 2, 2]] += 1 would do, but that does not work as the incremented value of arr[2] is simply copied into the third slot in arr twice, not incremented twice.

New functions partition and argpartition

New functions to partially sort arrays via a selection algorithm.

A partition by index k moves the k smallest element to the front of an array. All elements before k are then smaller or equal than the value in position k and all elements following k are then greater or equal than the value in position k. The ordering of the values within these bounds is undefined. A sequence of indices can be provided to sort all of them into their sorted position at once iterative partitioning. This can be used to efficiently obtain order statistics like median or percentiles of samples. partition has a linear time complexity of O(n) while a full sort has O(n log(n)).

New functions nanmean, nanvar and nanstd

New nan aware statistical functions are added. In these functions the results are what would be obtained if nan values were ommited from all computations.

New functions full and full_like

New convenience functions to create arrays filled with a specific value; complementary to the existing zeros and zeros_like functions.

IO compatibility with large files

Large NPZ files >2GB can be loaded on 64-bit systems.

Building against OpenBLAS

It is now possible to build numpy against OpenBLAS by editing site.cfg.

New constant

Euler’s constant is now exposed in numpy as euler_gamma.

New modes for qr

New modes ‘complete’, ‘reduced’, and ‘raw’ have been added to the qr factorization and the old ‘full’ and ‘economic’ modes are deprecated. The ‘reduced’ mode replaces the old ‘full’ mode and is the default as was the ‘full’ mode, so backward compatibility can be maintained by not specifying the mode.

The ‘complete’ mode returns a full dimensional factorization, which can be useful for obtaining a basis for the orthogonal complement of the range space. The ‘raw’ mode returns arrays that contain the Householder reflectors and scaling factors that can be used in the future to apply q without needing to convert to a matrix. The ‘economic’ mode is simply deprecated, there isn’t much use for it and it isn’t any more efficient than the ‘raw’ mode.

New invert argument to in1d

The function in1d now accepts a invert argument which, when True, causes the returned array to be inverted.

Advanced indexing using np.newaxis

It is now possible to use np.newaxis/None together with index arrays instead of only in simple indices. This means that array[np.newaxis, [0, 1]] will now work as expected and select the first two rows while prepending a new axis to the array.

C-API

New ufuncs can now be registered with builtin input types and a custom output type. Before this change, NumPy wouldn’t be able to find the right ufunc loop function when the ufunc was called from Python, because the ufunc loop signature matching logic wasn’t looking at the output operand type. Now the correct ufunc loop is found, as long as the user provides an output argument with the correct output type.

runtests.py

A simple test runner script runtests.py was added. It also builds Numpy via setup.py build and can be used to run tests easily during development.

Improvements

IO performance improvements

Performance in reading large files was improved by chunking (see also IO compatibility).

Performance improvements to pad

The pad function has a new implementation, greatly improving performance for all inputs except mode= (retained for backwards compatibility). Scaling with dimensionality is dramatically improved for rank >= 4.

Performance improvements to isnan, isinf, isfinite and byteswap

isnan, isinf, isfinite and byteswap have been improved to take advantage of compiler builtins to avoid expensive calls to libc. This improves performance of these operations by about a factor of two on gnu libc systems.

Performance improvements via SSE2 vectorization

Several functions have been optimized to make use of SSE2 CPU SIMD instructions.

  • Float32 and float64:
    • base math (add, subtract, divide, multiply)
    • sqrt
    • minimum/maximum
    • absolute
  • Bool:
    • logical_or
    • logical_and
    • logical_not

This improves performance of these operations up to 4x/2x for float32/float64 and up to 10x for bool depending on the location of the data in the CPU caches. The performance gain is greatest for in-place operations.

In order to use the improved functions the SSE2 instruction set must be enabled at compile time. It is enabled by default on x86_64 systems. On x86_32 with a capable CPU it must be enabled by passing the appropriate flag to the CFLAGS build variable (-msse2 with gcc).

Performance improvements to median

median is now implemented in terms of partition instead of sort which reduces its time complexity from O(n log(n)) to O(n). If used with the overwrite_input option the array will now only be partially sorted instead of fully sorted.

Overrideable operand flags in ufunc C-API

When creating a ufunc, the default ufunc operand flags can be overridden via the new op_flags attribute of the ufunc object. For example, to set the operand flag for the first input to read/write:

PyObject *ufunc = PyUFunc_FromFuncAndData(...); ufunc->op_flags[0] = NPY_ITER_READWRITE;

This allows a ufunc to perform an operation in place. Also, global nditer flags can be overridden via the new iter_flags attribute of the ufunc object. For example, to set the reduce flag for a ufunc:

ufunc->iter_flags = NPY_ITER_REDUCE_OK;

Changes

General

The function np.take now allows 0-d arrays as indices.

The separate compilation mode is now enabled by default.

Several changes to np.insert and np.delete:

  • Previously, negative indices and indices that pointed past the end of the array were simply ignored. Now, this will raise a Future or Deprecation Warning. In the future they will be treated like normal indexing treats them – negative indices will wrap around, and out-of-bound indices will generate an error.
  • Previously, boolean indices were treated as if they were integers (always referring to either the 0th or 1st item in the array). In the future, they will be treated as masks. In this release, they raise a FutureWarning warning of this coming change.
  • In Numpy 1.7. np.insert already allowed the syntax np.insert(arr, 3, [1,2,3]) to insert multiple items at a single position. In Numpy 1.8. this is also possible for np.insert(arr, [3], [1, 2, 3]).

Padded regions from np.pad are now correctly rounded, not truncated.

C-API Array Additions

Four new functions have been added to the array C-API.

  • PyArray_Partition
  • PyArray_ArgPartition
  • PyArray_SelectkindConverter
  • PyDataMem_NEW_ZEROED

C-API Ufunc Additions

One new function has been added to the ufunc C-API that allows to register an inner loop for user types using the descr.

  • PyUFunc_RegisterLoopForDescr

C-API Developer Improvements

The PyArray_Type instance creation function tp_new now uses tp_basicsize to determine how much memory to allocate. In previous releases only sizeof(PyArrayObject) bytes of memory were allocated, often requiring C-API subtypes to reimplement tp_new.

Deprecations

The ‘full’ and ‘economic’ modes of qr factorization are deprecated.

General

The use of non-integer for indices and most integer arguments has been deprecated. Previously float indices and function arguments such as axes or shapes were truncated to integers without warning. For example arr.reshape(3., -1) or arr[0.] will trigger a deprecation warning in NumPy 1.8., and in some future version of NumPy they will raise an error.

Authors

This release contains work by the following people who contributed at least one patch to this release. The names are in alphabetical order by first name:

  • 87
  • Adam Ginsburg +
  • Adam Griffiths +
  • Alexander Belopolsky +
  • Alex Barth +
  • Alex Ford +
  • Andreas Hilboll +
  • Andreas Kloeckner +
  • Andreas Schwab +
  • Andrew Horton +
  • argriffing +
  • Arink Verma +
  • Bago Amirbekian +
  • Bartosz Telenczuk +
  • bebert218 +
  • Benjamin Root +
  • Bill Spotz +
  • Bradley M. Froehle
  • Carwyn Pelley +
  • Charles Harris
  • Chris
  • Christian Brueffer +
  • Christoph Dann +
  • Christoph Gohlke
  • Dan Hipschman +
  • Daniel +
  • Dan Miller +
  • daveydave400 +
  • David Cournapeau
  • David Warde-Farley
  • Denis Laxalde
  • dmuellner +
  • Edward Catmur +
  • Egor Zindy +
  • endolith
  • Eric Firing
  • Eric Fode
  • Eric Moore +
  • Eric Price +
  • Fazlul Shahriar +
  • Félix Hartmann +
  • Fernando Perez
  • Frank B +
  • Frank Breitling +
  • Frederic
  • Gabriel
  • GaelVaroquaux
  • Guillaume Gay +
  • Han Genuit
  • HaroldMills +
  • hklemm +
  • jamestwebber +
  • Jason Madden +
  • Jay Bourque
  • jeromekelleher +
  • Jesús Gómez +
  • jmozmoz +
  • jnothman +
  • Johannes Schönberger +
  • John Benediktsson +
  • John Salvatier +
  • John Stechschulte +
  • Jonathan Waltman +
  • Joon Ro +
  • Jos de Kloe +
  • Joseph Martinot-Lagarde +
  • Josh Warner (Mac) +
  • Jostein Bø Fløystad +
  • Juan Luis Cano Rodríguez +
  • Julian Taylor +
  • Julien Phalip +
  • K.-Michael Aye +
  • Kumar Appaiah +
  • Lars Buitinck
  • Leon Weber +
  • Luis Pedro Coelho
  • Marcin Juszkiewicz
  • Mark Wiebe
  • Marten van Kerkwijk +
  • Martin Baeuml +
  • Martin Spacek
  • Martin Teichmann +
  • Matt Davis +
  • Matthew Brett
  • Maximilian Albert +
  • m-d-w +
  • Michael Droettboom
  • mwtoews +
  • Nathaniel J. Smith
  • Nicolas Scheffer +
  • Nils Werner +
  • ochoadavid +
  • Ondřej Čertík
  • ovillellas +
  • Paul Ivanov
  • Pauli Virtanen
  • peterjc
  • Ralf Gommers
  • Raul Cota +
  • Richard Hattersley +
  • Robert Costa +
  • Robert Kern
  • Rob Ruana +
  • Ronan Lamy
  • Sandro Tosi
  • Sascha Peilicke +
  • Sebastian Berg
  • Skipper Seabold
  • Stefan van der Walt
  • Steve +
  • Takafumi Arakaki +
  • Thomas Robitaille +
  • Tomas Tomecek +
  • Travis E. Oliphant
  • Valentin Haenel
  • Vladimir Rutsky +
  • Warren Weckesser
  • Yaroslav Halchenko
  • Yury V. Zaytsev +

A total of 119 people contributed to this release. People with a “+” by their names contributed a patch for the first time.

NumPy 1.7.2 Release Notes

This is a bugfix only release in the 1.7.x series. It supports Python 2.4 - 2.7 and 3.1 - 3.3 and is the last series that supports Python 2.4 - 2.5.

Issues fixed

  • gh-3153: Do not reuse nditer buffers when not filled enough
  • gh-3192: f2py crashes with UnboundLocalError exception
  • gh-442: Concatenate with axis=None now requires equal number of array elements
  • gh-2485: Fix for astype(‘S’) string truncate issue
  • gh-3312: bug in count_nonzero
  • gh-2684: numpy.ma.average casts complex to float under certain conditions
  • gh-2403: masked array with named components does not behave as expected
  • gh-2495: np.ma.compress treated inputs in wrong order
  • gh-576: add __len__ method to ma.mvoid
  • gh-3364: reduce performance regression of mmap slicing
  • gh-3421: fix non-swapping strided copies in GetStridedCopySwap
  • gh-3373: fix small leak in datetime metadata initialization
  • gh-2791: add platform specific python include directories to search paths
  • gh-3168: fix undefined function and add integer divisions
  • gh-3301: memmap does not work with TemporaryFile in python3
  • gh-3057: distutils.misc_util.get_shared_lib_extension returns wrong debug extension
  • gh-3472: add module extensions to load_library search list
  • gh-3324: Make comparison function (gt, ge, ...) respect __array_priority__
  • gh-3497: np.insert behaves incorrectly with argument ‘axis=-1’
  • gh-3541: make preprocessor tests consistent in halffloat.c
  • gh-3458: array_ass_boolean_subscript() writes ‘non-existent’ data to array
  • gh-2892: Regression in ufunc.reduceat with zero-sized index array
  • gh-3608: Regression when filling struct from tuple
  • gh-3701: add support for Python 3.4 ast.NameConstant
  • gh-3712: do not assume that GIL is enabled in xerbla
  • gh-3712: fix LAPACK error handling in lapack_litemodule
  • gh-3728: f2py fix decref on wrong object
  • gh-3743: Hash changed signature in Python 3.3
  • gh-3793: scalar int hashing broken on 64 bit python3
  • gh-3160: SandboxViolation easyinstalling 1.7.0 on Mac OS X 10.8.3
  • gh-3871: npy_math.h has invalid isinf for Solaris with SUNWspro12.2
  • gh-2561: Disable check for oldstyle classes in python3
  • gh-3900: Ensure NotImplemented is passed on in MaskedArray ufunc’s
  • gh-2052: del scalar subscript causes segfault
  • gh-3832: fix a few uninitialized uses and memleaks
  • gh-3971: f2py changed string.lowercase to string.ascii_lowercase for python3
  • gh-3480: numpy.random.binomial raised ValueError for n == 0
  • gh-3992: hypot(inf, 0) shouldn’t raise a warning, hypot(inf, inf) wrong result
  • gh-4018: Segmentation fault dealing with very large arrays
  • gh-4094: fix NaT handling in _strided_to_strided_string_to_datetime
  • gh-4051: fix uninitialized use in _strided_to_strided_string_to_datetime
  • gh-4123: lexsort segfault
  • gh-4141: Fix a few issues that show up with python 3.4b1

NumPy 1.7.1 Release Notes

This is a bugfix only release in the 1.7.x series. It supports Python 2.4 - 2.7 and 3.1 - 3.3 and is the last series that supports Python 2.4 - 2.5.

Issues fixed

  • gh-2973: Fix 1 is printed during numpy.test()
  • gh-2983: BUG: gh-2969: Backport memory leak fix 80b3a34.
  • gh-3007: Backport gh-3006
  • gh-2984: Backport fix complex polynomial fit
  • gh-2982: BUG: Make nansum work with booleans.
  • gh-2985: Backport large sort fixes
  • gh-3039: Backport object take
  • gh-3105: Backport nditer fix op axes initialization
  • gh-3108: BUG: npy-pkg-config ini files were missing after Bento build.
  • gh-3124: BUG: PyArray_LexSort allocates too much temporary memory.
  • gh-3131: BUG: Exported f2py_size symbol prevents linking multiple f2py modules.
  • gh-3117: Backport gh-2992
  • gh-3135: DOC: Add mention of PyArray_SetBaseObject stealing a reference
  • gh-3134: DOC: Fix typo in fft docs (the indexing variable is ‘m’, not ‘n’).
  • gh-3136: Backport #3128

NumPy 1.7.0 Release Notes

This release includes several new features as well as numerous bug fixes and refactorings. It supports Python 2.4 - 2.7 and 3.1 - 3.3 and is the last release that supports Python 2.4 - 2.5.

Highlights

  • where= parameter to ufuncs (allows the use of boolean arrays to choose where a computation should be done)
  • vectorize improvements (added ‘excluded’ and ‘cache’ keyword, general cleanup and bug fixes)
  • numpy.random.choice (random sample generating function)

Compatibility notes

In a future version of numpy, the functions np.diag, np.diagonal, and the diagonal method of ndarrays will return a view onto the original array, instead of producing a copy as they do now. This makes a difference if you write to the array returned by any of these functions. To facilitate this transition, numpy 1.7 produces a FutureWarning if it detects that you may be attempting to write to such an array. See the documentation for np.diagonal for details.

Similar to np.diagonal above, in a future version of numpy, indexing a record array by a list of field names will return a view onto the original array, instead of producing a copy as they do now. As with np.diagonal, numpy 1.7 produces a FutureWarning if it detects that you may be attempting to write to such an array. See the documentation for array indexing for details.

In a future version of numpy, the default casting rule for UFunc out= parameters will be changed from ‘unsafe’ to ‘same_kind’. (This also applies to in-place operations like a += b, which is equivalent to np.add(a, b, out=a).) Most usages which violate the ‘same_kind’ rule are likely bugs, so this change may expose previously undetected errors in projects that depend on NumPy. In this version of numpy, such usages will continue to succeed, but will raise a DeprecationWarning.

Full-array boolean indexing has been optimized to use a different, optimized code path. This code path should produce the same results, but any feedback about changes to your code would be appreciated.

Attempting to write to a read-only array (one with arr.flags.writeable set to False) used to raise either a RuntimeError, ValueError, or TypeError inconsistently, depending on which code path was taken. It now consistently raises a ValueError.

The <ufunc>.reduce functions evaluate some reductions in a different order than in previous versions of NumPy, generally providing higher performance. Because of the nature of floating-point arithmetic, this may subtly change some results, just as linking NumPy to a different BLAS implementations such as MKL can.

If upgrading from 1.5, then generally in 1.6 and 1.7 there have been substantial code added and some code paths altered, particularly in the areas of type resolution and buffered iteration over universal functions. This might have an impact on your code particularly if you relied on accidental behavior in the past.

New features

Reduction UFuncs Generalize axis= Parameter

Any ufunc.reduce function call, as well as other reductions like sum, prod, any, all, max and min support the ability to choose a subset of the axes to reduce over. Previously, one could say axis=None to mean all the axes or axis=# to pick a single axis. Now, one can also say axis=(#,#) to pick a list of axes for reduction.

Reduction UFuncs New keepdims= Parameter

There is a new keepdims= parameter, which if set to True, doesn’t throw away the reduction axes but instead sets them to have size one. When this option is set, the reduction result will broadcast correctly to the original operand which was reduced.

Datetime support

Note

The datetime API is experimental in 1.7.0, and may undergo changes in future versions of NumPy.

There have been a lot of fixes and enhancements to datetime64 compared to NumPy 1.6:

  • the parser is quite strict about only accepting ISO 8601 dates, with a few convenience extensions
  • converts between units correctly
  • datetime arithmetic works correctly
  • business day functionality (allows the datetime to be used in contexts where only certain days of the week are valid)

The notes in doc/source/reference/arrays.datetime.rst (also available in the online docs at arrays.datetime.html) should be consulted for more details.

Custom formatter for printing arrays

See the new formatter parameter of the numpy.set_printoptions function.

New function numpy.random.choice

A generic sampling function has been added which will generate samples from a given array-like. The samples can be with or without replacement, and with uniform or given non-uniform probabilities.

New function isclose

Returns a boolean array where two arrays are element-wise equal within a tolerance. Both relative and absolute tolerance can be specified.

Preliminary multi-dimensional support in the polynomial package

Axis keywords have been added to the integration and differentiation functions and a tensor keyword was added to the evaluation functions. These additions allow multi-dimensional coefficient arrays to be used in those functions. New functions for evaluating 2-D and 3-D coefficient arrays on grids or sets of points were added together with 2-D and 3-D pseudo-Vandermonde matrices that can be used for fitting.

Ability to pad rank-n arrays

A pad module containing functions for padding n-dimensional arrays has been added. The various private padding functions are exposed as options to a public ‘pad’ function. Example:

pad(a, 5, mode='mean')

Current modes are constant, edge, linear_ramp, maximum, mean, median, minimum, reflect, symmetric, wrap, and <function>.

New argument to searchsorted

The function searchsorted now accepts a ‘sorter’ argument that is a permutation array that sorts the array to search.

Build system

Added experimental support for the AArch64 architecture.

C API

New function PyArray_RequireWriteable provides a consistent interface for checking array writeability – any C code which works with arrays whose WRITEABLE flag is not known to be True a priori, should make sure to call this function before writing.

NumPy C Style Guide added (doc/C_STYLE_GUIDE.rst.txt).

Changes

General

The function np.concatenate tries to match the layout of its input arrays. Previously, the layout did not follow any particular reason, and depended in an undesirable way on the particular axis chosen for concatenation. A bug was also fixed which silently allowed out of bounds axis arguments.

The ufuncs logical_or, logical_and, and logical_not now follow Python’s behavior with object arrays, instead of trying to call methods on the objects. For example the expression (3 and ‘test’) produces the string ‘test’, and now np.logical_and(np.array(3, ‘O’), np.array(‘test’, ‘O’)) produces ‘test’ as well.

The .base attribute on ndarrays, which is used on views to ensure that the underlying array owning the memory is not deallocated prematurely, now collapses out references when you have a view-of-a-view. For example:

a = np.arange(10)
b = a[1:]
c = b[1:]

In numpy 1.6, c.base is b, and c.base.base is a. In numpy 1.7, c.base is a.

To increase backwards compatibility for software which relies on the old behaviour of .base, we only ‘skip over’ objects which have exactly the same type as the newly created view. This makes a difference if you use ndarray subclasses. For example, if we have a mix of ndarray and matrix objects which are all views on the same original ndarray:

a = np.arange(10)
b = np.asmatrix(a)
c = b[0, 1:]
d = c[0, 1:]

then d.base will be b. This is because d is a matrix object, and so the collapsing process only continues so long as it encounters other matrix objects. It considers c, b, and a in that order, and b is the last entry in that list which is a matrix object.

Casting Rules

Casting rules have undergone some changes in corner cases, due to the NA-related work. In particular for combinations of scalar+scalar:

  • the longlong type (q) now stays longlong for operations with any other number (? b h i l q p B H I), previously it was cast as int_ (l). The ulonglong type (Q) now stays as ulonglong instead of uint (L).
  • the timedelta64 type (m) can now be mixed with any integer type (b h i l q p B H I L Q P), previously it raised TypeError.

For array + scalar, the above rules just broadcast except the case when the array and scalars are unsigned/signed integers, then the result gets converted to the array type (of possibly larger size) as illustrated by the following examples:

>>> (np.zeros((2,), dtype=np.uint8) + np.int16(257)).dtype
dtype('uint16')
>>> (np.zeros((2,), dtype=np.int8) + np.uint16(257)).dtype
dtype('int16')
>>> (np.zeros((2,), dtype=np.int16) + np.uint32(2**17)).dtype
dtype('int32')

Whether the size gets increased depends on the size of the scalar, for example:

>>> (np.zeros((2,), dtype=np.uint8) + np.int16(255)).dtype
dtype('uint8')
>>> (np.zeros((2,), dtype=np.uint8) + np.int16(256)).dtype
dtype('uint16')

Also a complex128 scalar + float32 array is cast to complex64.

In NumPy 1.7 the datetime64 type (M) must be constructed by explicitly specifying the type as the second argument (e.g. np.datetime64(2000, 'Y')).

Deprecations

General

Specifying a custom string formatter with a _format array attribute is deprecated. The new formatter keyword in numpy.set_printoptions or numpy.array2string can be used instead.

The deprecated imports in the polynomial package have been removed.

concatenate now raises DepractionWarning for 1D arrays if axis != 0. Versions of numpy < 1.7.0 ignored axis argument value for 1D arrays. We allow this for now, but in due course we will raise an error.

C-API

Direct access to the fields of PyArrayObject* has been deprecated. Direct access has been recommended against for many releases. Expect similar deprecations for PyArray_Descr* and other core objects in the future as preparation for NumPy 2.0.

The macros in old_defines.h are deprecated and will be removed in the next major release (>= 2.0). The sed script tools/replace_old_macros.sed can be used to replace these macros with the newer versions.

You can test your code against the deprecated C API by #defining NPY_NO_DEPRECATED_API to the target version number, for example NPY_1_7_API_VERSION, before including any NumPy headers.

The NPY_CHAR member of the NPY_TYPES enum is deprecated and will be removed in NumPy 1.8. See the discussion at gh-2801 for more details.

NumPy 1.6.2 Release Notes

This is a bugfix release in the 1.6.x series. Due to the delay of the NumPy 1.7.0 release, this release contains far more fixes than a regular NumPy bugfix release. It also includes a number of documentation and build improvements.

Issues fixed

numpy.core

  • #2063: make unique() return consistent index
  • #1138: allow creating arrays from empty buffers or empty slices
  • #1446: correct note about correspondence vstack and concatenate
  • #1149: make argmin() work for datetime
  • #1672: fix allclose() to work for scalar inf
  • #1747: make np.median() work for 0-D arrays
  • #1776: make complex division by zero to yield inf properly
  • #1675: add scalar support for the format() function
  • #1905: explicitly check for NaNs in allclose()
  • #1952: allow floating ddof in std() and var()
  • #1948: fix regression for indexing chararrays with empty list
  • #2017: fix type hashing
  • #2046: deleting array attributes causes segfault
  • #2033: a**2.0 has incorrect type
  • #2045: make attribute/iterator_element deletions not segfault
  • #2021: fix segfault in searchsorted()
  • #2073: fix float16 __array_interface__ bug

numpy.lib

  • #2048: break reference cycle in NpzFile
  • #1573: savetxt() now handles complex arrays
  • #1387: allow bincount() to accept empty arrays
  • #1899: fixed histogramdd() bug with empty inputs
  • #1793: fix failing npyio test under py3k
  • #1936: fix extra nesting for subarray dtypes
  • #1848: make tril/triu return the same dtype as the original array
  • #1918: use Py_TYPE to access ob_type, so it works also on Py3

numpy.distutils

  • #1261: change compile flag on AIX from -O5 to -O3
  • #1377: update HP compiler flags
  • #1383: provide better support for C++ code on HPUX
  • #1857: fix build for py3k + pip
  • BLD: raise a clearer warning in case of building without cleaning up first
  • BLD: follow build_ext coding convention in build_clib
  • BLD: fix up detection of Intel CPU on OS X in system_info.py
  • BLD: add support for the new X11 directory structure on Ubuntu & co.
  • BLD: add ufsparse to the libraries search path.
  • BLD: add ‘pgfortran’ as a valid compiler in the Portland Group
  • BLD: update version match regexp for IBM AIX Fortran compilers.

numpy.random

  • BUG: Use npy_intp instead of long in mtrand

Changes

numpy.f2py

  • ENH: Introduce new options extra_f77_compiler_args and extra_f90_compiler_args
  • BLD: Improve reporting of fcompiler value
  • BUG: Fix f2py test_kind.py test

numpy.poly

  • ENH: Add some tests for polynomial printing
  • ENH: Add companion matrix functions
  • DOC: Rearrange the polynomial documents
  • BUG: Fix up links to classes
  • DOC: Add version added to some of the polynomial package modules
  • DOC: Document xxxfit functions in the polynomial package modules
  • BUG: The polynomial convenience classes let different types interact
  • DOC: Document the use of the polynomial convenience classes
  • DOC: Improve numpy reference documentation of polynomial classes
  • ENH: Improve the computation of polynomials from roots
  • STY: Code cleanup in polynomial [*]fromroots functions
  • DOC: Remove references to cast and NA, which were added in 1.7

NumPy 1.6.1 Release Notes

This is a bugfix only release in the 1.6.x series.

Issues Fixed

  • #1834: einsum fails for specific shapes
  • #1837: einsum throws nan or freezes python for specific array shapes
  • #1838: object <-> structured type arrays regression
  • #1851: regression for SWIG based code in 1.6.0
  • #1863: Buggy results when operating on array copied with astype()
  • #1870: Fix corner case of object array assignment
  • #1843: Py3k: fix error with recarray
  • #1885: nditer: Error in detecting double reduction loop
  • #1874: f2py: fix –include_paths bug
  • #1749: Fix ctypes.load_library()
  • #1895/1896: iter: writeonly operands weren’t always being buffered correctly

NumPy 1.6.0 Release Notes

This release includes several new features as well as numerous bug fixes and improved documentation. It is backward compatible with the 1.5.0 release, and supports Python 2.4 - 2.7 and 3.1 - 3.2.

Highlights

  • Re-introduction of datetime dtype support to deal with dates in arrays.
  • A new 16-bit floating point type.
  • A new iterator, which improves performance of many functions.

New features

New 16-bit floating point type

This release adds support for the IEEE 754-2008 binary16 format, available as the data type numpy.half. Within Python, the type behaves similarly to float or double, and C extensions can add support for it with the exposed half-float API.

New iterator

A new iterator has been added, replacing the functionality of the existing iterator and multi-iterator with a single object and API. This iterator works well with general memory layouts different from C or Fortran contiguous, and handles both standard NumPy and customized broadcasting. The buffering, automatic data type conversion, and optional output parameters, offered by ufuncs but difficult to replicate elsewhere, are now exposed by this iterator.

Legendre, Laguerre, Hermite, HermiteE polynomials in numpy.polynomial

Extend the number of polynomials available in the polynomial package. In addition, a new window attribute has been added to the classes in order to specify the range the domain maps to. This is mostly useful for the Laguerre, Hermite, and HermiteE polynomials whose natural domains are infinite and provides a more intuitive way to get the correct mapping of values without playing unnatural tricks with the domain.

Fortran assumed shape array and size function support in numpy.f2py

F2py now supports wrapping Fortran 90 routines that use assumed shape arrays. Before such routines could be called from Python but the corresponding Fortran routines received assumed shape arrays as zero length arrays which caused unpredicted results. Thanks to Lorenz Hüdepohl for pointing out the correct way to interface routines with assumed shape arrays.

In addition, f2py supports now automatic wrapping of Fortran routines that use two argument size function in dimension specifications.

Other new functions

numpy.ravel_multi_index : Converts a multi-index tuple into an array of flat indices, applying boundary modes to the indices.

numpy.einsum : Evaluate the Einstein summation convention. Using the Einstein summation convention, many common multi-dimensional array operations can be represented in a simple fashion. This function provides a way compute such summations.

numpy.count_nonzero : Counts the number of non-zero elements in an array.

numpy.result_type and numpy.min_scalar_type : These functions expose the underlying type promotion used by the ufuncs and other operations to determine the types of outputs. These improve upon the numpy.common_type and numpy.mintypecode which provide similar functionality but do not match the ufunc implementation.

Changes

default error handling

The default error handling has been change from print to warn for all except for underflow, which remains as ignore.

numpy.distutils

Several new compilers are supported for building Numpy: the Portland Group Fortran compiler on OS X, the PathScale compiler suite and the 64-bit Intel C compiler on Linux.

numpy.testing

The testing framework gained numpy.testing.assert_allclose, which provides a more convenient way to compare floating point arrays than assert_almost_equal, assert_approx_equal and assert_array_almost_equal.

C API

In addition to the APIs for the new iterator and half data type, a number of other additions have been made to the C API. The type promotion mechanism used by ufuncs is exposed via PyArray_PromoteTypes, PyArray_ResultType, and PyArray_MinScalarType. A new enumeration NPY_CASTING has been added which controls what types of casts are permitted. This is used by the new functions PyArray_CanCastArrayTo and PyArray_CanCastTypeTo. A more flexible way to handle conversion of arbitrary python objects into arrays is exposed by PyArray_GetArrayParamsFromObject.

Deprecated features

The “normed” keyword in numpy.histogram is deprecated. Its functionality will be replaced by the new “density” keyword.

Removed features

numpy.fft

The functions refft, refft2, refftn, irefft, irefft2, irefftn, which were aliases for the same functions without the ‘e’ in the name, were removed.

numpy.memmap

The sync() and close() methods of memmap were removed. Use flush() and “del memmap” instead.

numpy.lib

The deprecated functions numpy.unique1d, numpy.setmember1d, numpy.intersect1d_nu and numpy.lib.ufunclike.log2 were removed.

numpy.ma

Several deprecated items were removed from the numpy.ma module:

* ``numpy.ma.MaskedArray`` "raw_data" method
* ``numpy.ma.MaskedArray`` constructor "flag" keyword
* ``numpy.ma.make_mask`` "flag" keyword
* ``numpy.ma.allclose`` "fill_value" keyword

numpy.distutils

The numpy.get_numpy_include function was removed, use numpy.get_include instead.

NumPy 1.5.0 Release Notes

Highlights

Python 3 compatibility

This is the first NumPy release which is compatible with Python 3. Support for Python 3 and Python 2 is done from a single code base. Extensive notes on changes can be found at http://projects.scipy.org/numpy/browser/trunk/doc/Py3K.txt.

Note that the Numpy testing framework relies on nose, which does not have a Python 3 compatible release yet. A working Python 3 branch of nose can be found at http://bitbucket.org/jpellerin/nose3/ however.

Porting of SciPy to Python 3 is expected to be completed soon.

PEP 3118 compatibility

The new buffer protocol described by PEP 3118 is fully supported in this version of Numpy. On Python versions >= 2.6 Numpy arrays expose the buffer interface, and array(), asarray() and other functions accept new-style buffers as input.

New features

Warning on casting complex to real

Numpy now emits a numpy.ComplexWarning when a complex number is cast into a real number. For example:

>>> x = np.array([1,2,3])
>>> x[:2] = np.array([1+2j, 1-2j])
ComplexWarning: Casting complex values to real discards the imaginary part

The cast indeed discards the imaginary part, and this may not be the intended behavior in all cases, hence the warning. This warning can be turned off in the standard way:

>>> import warnings
>>> warnings.simplefilter("ignore", np.ComplexWarning)

Dot method for ndarrays

Ndarrays now have the dot product also as a method, which allows writing chains of matrix products as

>>> a.dot(b).dot(c)

instead of the longer alternative

>>> np.dot(a, np.dot(b, c))

linalg.slogdet function

The slogdet function returns the sign and logarithm of the determinant of a matrix. Because the determinant may involve the product of many small/large values, the result is often more accurate than that obtained by simple multiplication.

new header

The new header file ndarraytypes.h contains the symbols from ndarrayobject.h that do not depend on the PY_ARRAY_UNIQUE_SYMBOL and NO_IMPORT/_ARRAY macros. Broadly, these symbols are types, typedefs, and enumerations; the array function calls are left in ndarrayobject.h. This allows users to include array-related types and enumerations without needing to concern themselves with the macro expansions and their side- effects.

Changes

polynomial.polynomial

  • The polyint and polyder functions now check that the specified number integrations or derivations is a non-negative integer. The number 0 is a valid value for both functions.
  • A degree method has been added to the Polynomial class.
  • A trimdeg method has been added to the Polynomial class. It operates like truncate except that the argument is the desired degree of the result, not the number of coefficients.
  • Polynomial.fit now uses None as the default domain for the fit. The default Polynomial domain can be specified by using [] as the domain value.
  • Weights can be used in both polyfit and Polynomial.fit
  • A linspace method has been added to the Polynomial class to ease plotting.
  • The polymulx function was added.

polynomial.chebyshev

  • The chebint and chebder functions now check that the specified number integrations or derivations is a non-negative integer. The number 0 is a valid value for both functions.
  • A degree method has been added to the Chebyshev class.
  • A trimdeg method has been added to the Chebyshev class. It operates like truncate except that the argument is the desired degree of the result, not the number of coefficients.
  • Chebyshev.fit now uses None as the default domain for the fit. The default Chebyshev domain can be specified by using [] as the domain value.
  • Weights can be used in both chebfit and Chebyshev.fit
  • A linspace method has been added to the Chebyshev class to ease plotting.
  • The chebmulx function was added.
  • Added functions for the Chebyshev points of the first and second kind.

histogram

After a two years transition period, the old behavior of the histogram function has been phased out, and the “new” keyword has been removed.

correlate

The old behavior of correlate was deprecated in 1.4.0, the new behavior (the usual definition for cross-correlation) is now the default.

NumPy 1.4.0 Release Notes

This minor includes numerous bug fixes, as well as a few new features. It is backward compatible with 1.3.0 release.

Highlights

  • New datetime dtype support to deal with dates in arrays
  • Faster import time
  • Extended array wrapping mechanism for ufuncs
  • New Neighborhood iterator (C-level only)
  • C99-like complex functions in npymath

New features

Extended array wrapping mechanism for ufuncs

An __array_prepare__ method has been added to ndarray to provide subclasses greater flexibility to interact with ufuncs and ufunc-like functions. ndarray already provided __array_wrap__, which allowed subclasses to set the array type for the result and populate metadata on the way out of the ufunc (as seen in the implementation of MaskedArray). For some applications it is necessary to provide checks and populate metadata on the way in. __array_prepare__ is therefore called just after the ufunc has initialized the output array but before computing the results and populating it. This way, checks can be made and errors raised before operations which may modify data in place.

Automatic detection of forward incompatibilities

Previously, if an extension was built against a version N of NumPy, and used on a system with NumPy M < N, the import_array was successfull, which could cause crashes because the version M does not have a function in N. Starting from NumPy 1.4.0, this will cause a failure in import_array, so the error will be catched early on.

New iterators

A new neighborhood iterator has been added to the C API. It can be used to iterate over the items in a neighborhood of an array, and can handle boundaries conditions automatically. Zero and one padding are available, as well as arbitrary constant value, mirror and circular padding.

New polynomial support

New modules chebyshev and polynomial have been added. The new polynomial module is not compatible with the current polynomial support in numpy, but is much like the new chebyshev module. The most noticeable difference to most will be that coefficients are specified from low to high power, that the low level functions do not work with the Chebyshev and Polynomial classes as arguements, and that the Chebyshev and Polynomial classes include a domain. Mapping between domains is a linear substitution and the two classes can be converted one to the other, allowing, for instance, a Chebyshev series in one domain to be expanded as a polynomial in another domain. The new classes should generally be used instead of the low level functions, the latter are provided for those who wish to build their own classes.

The new modules are not automatically imported into the numpy namespace, they must be explicitly brought in with an “import numpy.polynomial” statement.

New C API

The following C functions have been added to the C API:

  1. PyArray_GetNDArrayCFeatureVersion: return the API version of the loaded numpy.
  2. PyArray_Correlate2 - like PyArray_Correlate, but implements the usual definition of correlation. Inputs are not swapped, and conjugate is taken for complex arrays.
  3. PyArray_NeighborhoodIterNew - a new iterator to iterate over a neighborhood of a point, with automatic boundaries handling. It is documented in the iterators section of the C-API reference, and you can find some examples in the multiarray_test.c.src file in numpy.core.

New ufuncs

The following ufuncs have been added to the C API:

  1. copysign - return the value of the first argument with the sign copied from the second argument.
  2. nextafter - return the next representable floating point value of the first argument toward the second argument.

New defines

The alpha processor is now defined and available in numpy/npy_cpu.h. The failed detection of the PARISC processor has been fixed. The defines are:

  1. NPY_CPU_HPPA: PARISC
  2. NPY_CPU_ALPHA: Alpha

Testing

  1. deprecated decorator: this decorator may be used to avoid cluttering testing output while testing DeprecationWarning is effectively raised by the decorated test.
  2. assert_array_almost_equal_nulps: new method to compare two arrays of floating point values. With this function, two values are considered close if there are not many representable floating point values in between, thus being more robust than assert_array_almost_equal when the values fluctuate a lot.
  3. assert_array_max_ulp: raise an assertion if there are more than N representable numbers between two floating point values.
  4. assert_warns: raise an AssertionError if a callable does not generate a warning of the appropriate class, without altering the warning state.

Reusing npymath

In 1.3.0, we started putting portable C math routines in npymath library, so that people can use those to write portable extensions. Unfortunately, it was not possible to easily link against this library: in 1.4.0, support has been added to numpy.distutils so that 3rd party can reuse this library. See coremath documentation for more information.

Improved set operations

In previous versions of NumPy some set functions (intersect1d, setxor1d, setdiff1d and setmember1d) could return incorrect results if the input arrays contained duplicate items. These now work correctly for input arrays with duplicates. setmember1d has been renamed to in1d, as with the change to accept arrays with duplicates it is no longer a set operation, and is conceptually similar to an elementwise version of the Python operator ‘in’. All of these functions now accept the boolean keyword assume_unique. This is False by default, but can be set True if the input arrays are known not to contain duplicates, which can increase the functions’ execution speed.

Improvements

  1. numpy import is noticeably faster (from 20 to 30 % depending on the platform and computer)

  2. The sort functions now sort nans to the end.

    • Real sort order is [R, nan]
    • Complex sort order is [R + Rj, R + nanj, nan + Rj, nan + nanj]

    Complex numbers with the same nan placements are sorted according to the non-nan part if it exists.

  3. The type comparison functions have been made consistent with the new sort order of nans. Searchsorted now works with sorted arrays containing nan values.

  4. Complex division has been made more resistent to overflow.

  5. Complex floor division has been made more resistent to overflow.

Deprecations

The following functions are deprecated:

  1. correlate: it takes a new keyword argument old_behavior. When True (the default), it returns the same result as before. When False, compute the conventional correlation, and take the conjugate for complex arrays. The old behavior will be removed in NumPy 1.5, and raises a DeprecationWarning in 1.4.
  2. unique1d: use unique instead. unique1d raises a deprecation warning in 1.4, and will be removed in 1.5.
  3. intersect1d_nu: use intersect1d instead. intersect1d_nu raises a deprecation warning in 1.4, and will be removed in 1.5.
  4. setmember1d: use in1d instead. setmember1d raises a deprecation warning in 1.4, and will be removed in 1.5.

The following raise errors:

  1. When operating on 0-d arrays, numpy.max and other functions accept only axis=0, axis=-1 and axis=None. Using an out-of-bounds axes is an indication of a bug, so Numpy raises an error for these cases now.
  2. Specifying axis > MAX_DIMS is no longer allowed; Numpy raises now an error instead of behaving similarly as for axis=None.

Internal changes

Use C99 complex functions when available

The numpy complex types are now guaranteed to be ABI compatible with C99 complex type, if availble on the platform. Moreoever, the complex ufunc now use the platform C99 functions intead of our own.

split multiarray and umath source code

The source code of multiarray and umath has been split into separate logic compilation units. This should make the source code more amenable for newcomers.

Separate compilation

By default, every file of multiarray (and umath) is merged into one for compilation as was the case before, but if NPY_SEPARATE_COMPILATION env variable is set to a non-negative value, experimental individual compilation of each file is enabled. This makes the compile/debug cycle much faster when working on core numpy.

Separate core math library

New functions which have been added:

  • npy_copysign
  • npy_nextafter
  • npy_cpack
  • npy_creal
  • npy_cimag
  • npy_cabs
  • npy_cexp
  • npy_clog
  • npy_cpow
  • npy_csqr
  • npy_ccos
  • npy_csin

NumPy 1.3.0 Release Notes

This minor includes numerous bug fixes, official python 2.6 support, and several new features such as generalized ufuncs.

Highlights

Python 2.6 support

Python 2.6 is now supported on all previously supported platforms, including windows.

http://www.python.org/dev/peps/pep-0361/

Generalized ufuncs

There is a general need for looping over not only functions on scalars but also over functions on vectors (or arrays), as explained on http://scipy.org/scipy/numpy/wiki/GeneralLoopingFunctions. We propose to realize this concept by generalizing the universal functions (ufuncs), and provide a C implementation that adds ~500 lines to the numpy code base. In current (specialized) ufuncs, the elementary function is limited to element-by-element operations, whereas the generalized version supports “sub-array” by “sub-array” operations. The Perl vector library PDL provides a similar functionality and its terms are re-used in the following.

Each generalized ufunc has information associated with it that states what the “core” dimensionality of the inputs is, as well as the corresponding dimensionality of the outputs (the element-wise ufuncs have zero core dimensions). The list of the core dimensions for all arguments is called the “signature” of a ufunc. For example, the ufunc numpy.add has signature “(),()->()” defining two scalar inputs and one scalar output.

Another example is (see the GeneralLoopingFunctions page) the function inner1d(a,b) with a signature of “(i),(i)->()”. This applies the inner product along the last axis of each input, but keeps the remaining indices intact. For example, where a is of shape (3,5,N) and b is of shape (5,N), this will return an output of shape (3,5). The underlying elementary function is called 3*5 times. In the signature, we specify one core dimension “(i)” for each input and zero core dimensions “()” for the output, since it takes two 1-d arrays and returns a scalar. By using the same name “i”, we specify that the two corresponding dimensions should be of the same size (or one of them is of size 1 and will be broadcasted).

The dimensions beyond the core dimensions are called “loop” dimensions. In the above example, this corresponds to (3,5).

The usual numpy “broadcasting” rules apply, where the signature determines how the dimensions of each input/output object are split into core and loop dimensions:

While an input array has a smaller dimensionality than the corresponding number of core dimensions, 1’s are pre-pended to its shape. The core dimensions are removed from all inputs and the remaining dimensions are broadcasted; defining the loop dimensions. The output is given by the loop dimensions plus the output core dimensions.

Experimental Windows 64 bits support

Numpy can now be built on windows 64 bits (amd64 only, not IA64), with both MS compilers and mingw-w64 compilers:

This is highly experimental: DO NOT USE FOR PRODUCTION USE. See INSTALL.txt, Windows 64 bits section for more information on limitations and how to build it by yourself.

New features

Formatting issues

Float formatting is now handled by numpy instead of the C runtime: this enables locale independent formatting, more robust fromstring and related methods. Special values (inf and nan) are also more consistent across platforms (nan vs IND/NaN, etc...), and more consistent with recent python formatting work (in 2.6 and later).

Nan handling in max/min

The maximum/minimum ufuncs now reliably propagate nans. If one of the arguments is a nan, then nan is retured. This affects np.min/np.max, amin/amax and the array methods max/min. New ufuncs fmax and fmin have been added to deal with non-propagating nans.

Nan handling in sign

The ufunc sign now returns nan for the sign of anan.

New ufuncs

  1. fmax - same as maximum for integer types and non-nan floats. Returns the non-nan argument if one argument is nan and returns nan if both arguments are nan.
  2. fmin - same as minimum for integer types and non-nan floats. Returns the non-nan argument if one argument is nan and returns nan if both arguments are nan.
  3. deg2rad - converts degrees to radians, same as the radians ufunc.
  4. rad2deg - converts radians to degrees, same as the degrees ufunc.
  5. log2 - base 2 logarithm.
  6. exp2 - base 2 exponential.
  7. trunc - truncate floats to nearest integer towards zero.
  8. logaddexp - add numbers stored as logarithms and return the logarithm of the result.
  9. logaddexp2 - add numbers stored as base 2 logarithms and return the base 2 logarithm of the result result.

Masked arrays

Several new features and bug fixes, including:

  • structured arrays should now be fully supported by MaskedArray (r6463, r6324, r6305, r6300, r6294...)
  • Minor bug fixes (r6356, r6352, r6335, r6299, r6298)
  • Improved support for __iter__ (r6326)
  • made baseclass, sharedmask and hardmask accesible to the user (but read-only)
  • doc update

gfortran support on windows

Gfortran can now be used as a fortran compiler for numpy on windows, even when the C compiler is Visual Studio (VS 2005 and above; VS 2003 will NOT work). Gfortran + Visual studio does not work on windows 64 bits (but gcc + gfortran does). It is unclear whether it will be possible to use gfortran and visual studio at all on x64.

Arch option for windows binary

Automatic arch detection can now be bypassed from the command line for the superpack installed:

numpy-1.3.0-superpack-win32.exe /arch=nosse

will install a numpy which works on any x86, even if the running computer supports SSE set.

Deprecated features

Histogram

The semantics of histogram has been modified to fix long-standing issues with outliers handling. The main changes concern

  1. the definition of the bin edges, now including the rightmost edge, and
  2. the handling of upper outliers, now ignored rather than tallied in the rightmost bin.

The previous behavior is still accessible using new=False, but this is deprecated, and will be removed entirely in 1.4.0.

Documentation changes

A lot of documentation has been added. Both user guide and references can be built from sphinx.

New C API

Multiarray API

The following functions have been added to the multiarray C API:

  • PyArray_GetEndianness: to get runtime endianness

Ufunc API

The following functions have been added to the ufunc API:

  • PyUFunc_FromFuncAndDataAndSignature: to declare a more general ufunc (generalized ufunc).

New defines

New public C defines are available for ARCH specific code through numpy/npy_cpu.h:

  • NPY_CPU_X86: x86 arch (32 bits)
  • NPY_CPU_AMD64: amd64 arch (x86_64, NOT Itanium)
  • NPY_CPU_PPC: 32 bits ppc
  • NPY_CPU_PPC64: 64 bits ppc
  • NPY_CPU_SPARC: 32 bits sparc
  • NPY_CPU_SPARC64: 64 bits sparc
  • NPY_CPU_S390: S390
  • NPY_CPU_IA64: ia64
  • NPY_CPU_PARISC: PARISC

New macros for CPU endianness has been added as well (see internal changes below for details):

  • NPY_BYTE_ORDER: integer
  • NPY_LITTLE_ENDIAN/NPY_BIG_ENDIAN defines

Those provide portable alternatives to glibc endian.h macros for platforms without it.

Portable NAN, INFINITY, etc...

npy_math.h now makes available several portable macro to get NAN, INFINITY:

  • NPY_NAN: equivalent to NAN, which is a GNU extension
  • NPY_INFINITY: equivalent to C99 INFINITY
  • NPY_PZERO, NPY_NZERO: positive and negative zero respectively

Corresponding single and extended precision macros are available as well. All references to NAN, or home-grown computation of NAN on the fly have been removed for consistency.

Internal changes

numpy.core math configuration revamp

This should make the porting to new platforms easier, and more robust. In particular, the configuration stage does not need to execute any code on the target platform, which is a first step toward cross-compilation.

http://projects.scipy.org/numpy/browser/trunk/doc/neps/math_config_clean.txt

umath refactor

A lot of code cleanup for umath/ufunc code (charris).

Improvements to build warnings

Numpy can now build with -W -Wall without warnings

http://projects.scipy.org/numpy/browser/trunk/doc/neps/warnfix.txt

Separate core math library

The core math functions (sin, cos, etc... for basic C types) have been put into a separate library; it acts as a compatibility layer, to support most C99 maths functions (real only for now). The library includes platform-specific fixes for various maths functions, such as using those versions should be more robust than using your platform functions directly. The API for existing functions is exactly the same as the C99 math functions API; the only difference is the npy prefix (npy_cos vs cos).

The core library will be made available to any extension in 1.4.0.

CPU arch detection

npy_cpu.h defines numpy specific CPU defines, such as NPY_CPU_X86, etc... Those are portable across OS and toolchains, and set up when the header is parsed, so that they can be safely used even in the case of cross-compilation (the values is not set when numpy is built), or for multi-arch binaries (e.g. fat binaries on Max OS X).

npy_endian.h defines numpy specific endianness defines, modeled on the glibc endian.h. NPY_BYTE_ORDER is equivalent to BYTE_ORDER, and one of NPY_LITTLE_ENDIAN or NPY_BIG_ENDIAN is defined. As for CPU archs, those are set when the header is parsed by the compiler, and as such can be used for cross-compilation and multi-arch binaries.


About NumPy

  • next
  • previous

Table Of Contents

  • About NumPy
    • NumPy community
  • About this documentation
    • Conventions

Previous topic

Release Notes

Next topic

Reporting bugs

About NumPy

NumPy is the fundamental package needed for scientific computing with Python. This package contains:

  • a powerful N-dimensional array object
  • sophisticated (broadcasting) functions
  • basic linear algebra functions
  • basic Fourier transforms
  • sophisticated random number capabilities
  • tools for integrating Fortran code
  • tools for integrating C/C++ code

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.

NumPy is a successor for two earlier scientific Python libraries: NumPy derives from the old Numeric code base and can be used as a replacement for Numeric. It also adds the features introduced by Numarray and can also be used to replace Numarray.

NumPy community

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.

Our main means of communication are:

  • scipy.org website
  • Mailing lists
  • Numpy Issues (bug reports go here)
  • Old Numpy Trac (no longer used)

More information about the development of Numpy can be found at http://scipy.org/Developer_Zone

If you want to fix issues in this documentation, the easiest way is to participate in our ongoing documentation marathon.

About this documentation

Conventions

Names of classes, objects, constants, etc. are given in boldface font. Often they are also links to a more detailed documentation of the referred object.

This manual contains many examples of use, usually prefixed with the Python prompt >>> (which is not a part of the example code). The examples assume that you have first entered:

>>> import numpy as np

before running the examples.


Reporting bugs

  • next
  • previous

Previous topic

About NumPy

Next topic

Numpy License

Reporting bugs

File bug reports or feature requests, and make contributions (e.g. code patches), by opening a “new issue” on GitHub:

  • Numpy Issues: http://github.com/numpy/numpy/issues

Please give as much information as you can in the ticket. It is extremely useful if you can supply a small self-contained code snippet that reproduces the problem. Also specify the component, the version you are referring to and the milestone.

Report bugs to the appropriate GitHub project (there is one for NumPy and a different one for SciPy).

More information can be found on the http://scipy.org/Developer_Zone website.


Numpy License

  • next
  • previous

Previous topic

Reporting bugs

Next topic

Glossary

Numpy License

Copyright (c) 2005, NumPy Developers

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of the NumPy Developers nor the names of any contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


Glossary

  • previous

Table Of Contents

  • Glossary
    • Jargon

Previous topic

Numpy License

Glossary

along an axis

Axes are defined for arrays with more than one dimension. A 2-dimensional array has two corresponding axes: the first running vertically downwards across rows (axis 0), and the second running horizontally across columns (axis 1).

Many operation can take place along one of these axes. For example, we can sum each row of an array, in which case we operate along columns, or axis 1:

>>> x = np.arange(12).reshape((3,4))

>>> x
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]])

>>> x.sum(axis=1)
array([ 6, 22, 38])
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 or complex) or a combination (such as (float, int, float)). Each array has an associated data-type (or dtype), which describes the numerical type of its elements:

>>> x = np.array([1, 2, 3], float)

>>> x
array([ 1.,  2.,  3.])

>>> x.dtype # floating point number, 64 bits of memory per element
dtype('float64')

# More complicated data type: each array element is a combination of
# and integer and a floating point number
>>> np.array([(1, 2.0), (3, 4.0)], dtype=[('x', int), ('y', float)])
array([(1, 2.0), (3, 4.0)],
      dtype=[('x', '<i4'), ('y', '<f8')])

Fast element-wise operations, called `ufuncs`_, operate on arrays.

array_like
Any sequence that can be interpreted as an ndarray. This includes nested lists, tuples, scalars and existing arrays.
attribute

A property of an object that can be accessed using obj.attribute, e.g., shape is an attribute of an array:

>>> x = np.array([1, 2, 3])
>>> x.shape
(3,)
BLAS
Basic Linear Algebra Subprograms
broadcast

NumPy can do operations on arrays whose shapes are mismatched:

>>> x = np.array([1, 2])
>>> y = np.array([[3], [4]])

>>> x
array([1, 2])

>>> y
array([[3],
       [4]])

>>> x + y
array([[4, 5],
       [5, 6]])

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 function execution:

>>> def log(f):
...     def new_logging_func(*args, **kwargs):
...         print "Logging call with parameters:", args, kwargs
...         return f(*args, **kwargs)
...
...     return new_logging_func

Now, when we define a function, we can “decorate” it using log:

>>> @log
... def add(a, b):
...     return a + b

Calling add then yields:

>>> add(1, 2)
Logging call with parameters: (1, 2) {}
3
dictionary

Resembling a language dictionary, which provides a mapping between words and descriptions thereof, a Python dictionary is a mapping between two objects:

>>> x = {1: 'one', 'two': [1, 2]}

Here, x is a dictionary mapping keys to values, in this case the integer 1 to the string “one”, and the string “two” to the list [1, 2]. The values may be accessed using their corresponding keys:

>>> x[1]
'one'

>>> x['two']
[1, 2]

Note that dictionaries are not stored in any specific order. Also, most mutable (see immutable below) objects, such as lists, may not be used as keys.

For more information on dictionaries, read the Python tutorial.

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.
instance

A class definition gives the blueprint for constructing an object:

>>> class House(object):
...     wall_colour = 'white'

Yet, we have to build a house before it exists:

>>> h = House() # build a house

Now, h is called a House instance. An instance is therefore a specific realisation of a class.

iterable

A sequence that allows “walking” (iterating) over items, typically using a loop such as:

>>> x = [1, 2, 3]
>>> [item**2 for item in x]
[1, 4, 9]
It is often used in combintion with enumerate::
>>> keys = ['a','b','c']
>>> for n, k in enumerate(keys):
...     print "Key %d: %s" % (n, k)
...
Key 0: a
Key 1: b
Key 2: c
list

A Python container that can hold any number of objects or items. The items do not have to be of the same type, and can even be lists themselves:

>>> x = [2, 2.0, "two", [2, 2.0]]

The list x contains 4 items, each which can be accessed individually:

>>> x[2] # the string 'two'
'two'

>>> x[3] # a list, containing an integer 2 and a float 2.0
[2, 2.0]

It is also possible to select more than one item at a time, using slicing:

>>> x[0:2] # or, equivalently, x[:2]
[2, 2.0]

In code, arrays are often conveniently expressed as nested lists:

>>> np.array([[1, 2], [3, 4]])
array([[1, 2],
       [3, 4]])

For more information, read the section on lists in the Python tutorial. For a mapping type (key-value), see dictionary.

mask

A boolean array, used to select only certain elements for an operation:

>>> x = np.arange(5)
>>> x
array([0, 1, 2, 3, 4])

>>> mask = (x > 2)
>>> mask
array([False, False, False, True,  True], dtype=bool)

>>> x[mask] = -1
>>> x
array([ 0,  1,  2,  -1, -1])
masked array

Array that suppressed values indicated by a mask:

>>> x = np.ma.masked_array([np.nan, 2, np.nan], [True, False, True])
>>> x
masked_array(data = [-- 2.0 --],
             mask = [ True False  True],
       fill_value = 1e+20)

>>> x + [1, 2, 3]
masked_array(data = [-- 4.0 --],
             mask = [ True False  True],
       fill_value = 1e+20)

Masked arrays are often used when operating on arrays containing missing or invalid entries.

matrix

A 2-dimensional ndarray that preserves its two-dimensional nature throughout operations. It has certain special operations, such as * (matrix multiplication) and ** (matrix power), defined:

>>> x = np.mat([[1, 2], [3, 4]])

>>> x
matrix([[1, 2],
        [3, 4]])

>>> x**2
matrix([[ 7, 10],
      [15, 22]])
method

A function associated with an object. For example, each ndarray has a method called repeat:

>>> x = np.array([1, 2, 3])

>>> 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:

>>> class Paintbrush(object):
...     color = 'blue'
...
...     def paint(self):
...         print "Painting the city %s!" % self.color
...
>>> p = Paintbrush()
>>> p.color = 'red'
>>> p.paint() # self refers to 'p'
Painting the city red!
slice

Used to select only certain elements from a sequence:

>>> x = range(5)
>>> x
[0, 1, 2, 3, 4]

>>> x[1:3] # slice from 1 to 3 (excluding 3 itself)
[1, 2]

>>> x[1:5:2] # slice from 1 to 5, but skipping every second element
[1, 3]

>>> x[::-1] # slice a sequence in reverse
[4, 3, 2, 1, 0]

Arrays may have more than one dimension, each which can be sliced individually:

>>> x = np.array([[1, 2], [3, 4]])
>>> x
array([[1, 2],
       [3, 4]])

>>> x[:, 1]
array([2, 4])
tuple

A sequence that may contain a variable number of types of any kind. A tuple is immutable, i.e., once constructed it cannot be changed. Similar to a list, it can be indexed and sliced:

>>> x = (1, 'one', [1, 2])

>>> x
(1, 'one', [1, 2])

>>> x[0]
1

>>> x[:2]
(1, 'one')

A useful concept is “tuple unpacking”, which allows variables to be assigned to the contents of a tuple:

>>> x, y = (1, 2)
>>> x, y = 1, 2

This is often used when a function returns multiple values:

>>> def return_many():
...     return 1, 'alpha', None

>>> a, b, c = return_many()
>>> a, b, c
(1, 'alpha', None)

>>> a
1
>>> b
'alpha'
ufunc
Universal function. A fast element-wise array operation. Examples include add, sin and logical_or.
view

An array that does not own its data, but refers to another array’s data instead. For example, we may create a view that only shows every second element of another array:

>>> x = np.arange(5)
>>> x
array([0, 1, 2, 3, 4])

>>> y = x[::2]
>>> y
array([0, 2, 4])

>>> x[0] = 3 # changing x changes y as well, since y is a view on x
>>> y
array([3, 2, 4])
wrapper

Python is a high-level (highly abstracted, or English-like) language. This abstraction comes at a price in execution speed, and sometimes it becomes necessary to use lower level languages to do fast computations. A wrapper is code that provides a bridge between high and the low level languages, allowing, e.g., Python to execute code written in C or Fortran.

Examples include ctypes, SWIG and Cython (which wraps C and C++) and f2py (which wraps Fortran).

Jargon

Placeholder for computer science, engineering and other jargon.


  • next

Next topic

NumPy User Guide

Numpy manual contents

  • NumPy User Guide
    • Introduction
      • What is NumPy?
      • Building and installing NumPy
        • Binary installers
          • Windows
          • Linux
          • Mac OS X
        • Building from source
          • Prerequisites
          • FORTRAN ABI mismatch
            • Choosing the fortran compiler
            • How to check the ABI of blas/lapack/atlas
          • Disabling ATLAS and other accelerated libraries
          • Supplying additional compiler flags
          • Building with ATLAS support
            • Ubuntu 8.10 (Intrepid) and 9.04 (Jaunty)
            • Ubuntu 8.04 and lower
      • How to find documentation
    • Numpy basics
      • Data types
        • Array types and conversions between types
        • Array Scalars
      • Array creation
        • Introduction
        • Converting Python array_like Objects to Numpy Arrays
        • Intrinsic Numpy Array Creation
        • Reading Arrays From Disk
          • Standard Binary Formats
          • Common ASCII Formats
          • Custom Binary Formats
          • Use of Special Libraries
      • I/O with Numpy
        • Importing data with genfromtxt
          • Defining the input
          • Splitting the lines into columns
            • The delimiter argument
            • The autostrip argument
            • The comments argument
          • Skipping lines and choosing columns
            • The skip_header and skip_footer arguments
            • The usecols argument
          • Choosing the data type
          • Setting the names
            • The names argument
            • The defaultfmt argument
            • Validating names
          • Tweaking the conversion
            • The converters argument
            • Using missing and filling values
            • missing_values
            • filling_values
            • usemask
          • Shortcut functions
      • Indexing
        • Assignment vs referencing
        • Single element indexing
        • Other indexing options
        • Index arrays
        • Indexing Multi-dimensional arrays
        • Boolean or “mask” index arrays
        • Combining index arrays with slices
        • Structural indexing tools
        • Assigning values to indexed arrays
        • Dealing with variable numbers of indices within programs
      • Broadcasting
        • General Broadcasting Rules
      • Byte-swapping
        • Introduction to byte ordering and ndarrays
        • Changing byte ordering
          • Data and dtype endianness don’t match, change dtype to match data
          • Data and type endianness don’t match, change data to match dtype
          • Data and dtype endianness match, swap data and dtype
      • Structured arrays (aka “Record arrays”)
        • Structured Arrays (and Record Arrays)
          • Introduction
          • Defining Structured Arrays
          • Accessing and modifying field names
          • Accessing field titles
          • Accessing multiple fields at once
          • Filling structured arrays
          • More information
      • Subclassing ndarray
        • Credits
        • Introduction
          • ndarrays and object creation
        • View casting
        • Creating new from template
        • Relationship of view casting and new-from-template
        • Implications for subclassing
          • A brief Python primer on __new__ and __init__
          • The role of __array_finalize__
        • Simple example - adding an extra attribute to ndarray
        • Slightly more realistic example - attribute added to existing array
        • __array_wrap__ for ufuncs
        • Extra gotchas - custom __del__ methods and ndarray.base
    • Performance
    • Miscellaneous
      • IEEE 754 Floating Point Special Values
      • How numpy handles numerical exceptions
      • Examples
      • Interfacing to C
      • Interfacing to Fortran:
      • Interfacing to C++:
      • Methods vs. Functions
    • Using Numpy C-API
      • How to extend NumPy
        • Writing an extension module
        • Required subroutine
        • Defining functions
          • Functions without keyword arguments
          • Functions with keyword arguments
          • Reference counting
        • Dealing with array objects
          • Converting an arbitrary sequence object
          • Creating a brand-new ndarray
          • Getting at ndarray memory and accessing elements of the ndarray
        • Example
      • Using Python as glue
        • Calling other compiled libraries from Python
        • Hand-generated wrappers
        • f2py
          • Creating source for a basic extension module
          • Creating a compiled extension module
          • Improving the basic interface
          • Inserting directives in Fortran source
          • A filtering example
          • Calling f2py from Python
          • Automatic extension module generation
          • Conclusion
        • Cython
          • Complex addition in Cython
          • Image filter in Cython
          • Conclusion
        • ctypes
          • Having a shared library
          • Loading the shared library
          • Converting arguments
          • Calling the function
          • Complete example
          • Conclusion
        • Additional tools you may find useful
          • SWIG
          • SIP
          • Boost Python
          • PyFort
      • Writing your own ufunc
        • Creating a new universal function
        • Example Non-ufunc extension
        • Example Numpy ufunc for one dtype
        • Example Numpy ufunc with multiple dtypes
        • Example Numpy ufunc with multiple arguments/return values
        • Example Numpy ufunc with structured array dtype arguments
        • PyUFunc_FromFuncAndData Specification
      • Beyond the Basics
        • Iterating over elements in the array
          • Basic Iteration
          • Iterating over all but one axis
          • Iterating over multiple arrays
          • Broadcasting over multiple arrays
        • User-defined data-types
          • Adding the new data-type
          • Registering a casting function
          • Registering coercion rules
          • Registering a ufunc loop
        • Subtyping the ndarray in C
          • Creating sub-types
          • Specific features of ndarray sub-typing
            • The __array_finalize__ method
            • The __array_priority__ attribute
            • The __array_wrap__ method
  • NumPy Reference
    • Array objects
      • The N-dimensional array (ndarray)
        • Constructing arrays
          • numpy.ndarray
            • numpy.ndarray.T
            • numpy.ndarray.data
            • numpy.ndarray.dtype
            • numpy.ndarray.flags
            • numpy.ndarray.flat
            • numpy.ndarray.imag
            • numpy.ndarray.real
            • numpy.ndarray.size
            • numpy.ndarray.itemsize
            • numpy.ndarray.nbytes
            • numpy.ndarray.ndim
            • numpy.ndarray.shape
            • numpy.ndarray.strides
            • numpy.ndarray.ctypes
            • numpy.ndarray.base
            • numpy.ndarray.all
            • numpy.ndarray.any
            • numpy.ndarray.argmax
            • numpy.ndarray.argmin
            • numpy.ndarray.argpartition
            • numpy.ndarray.argsort
            • numpy.ndarray.astype
            • numpy.ndarray.byteswap
            • numpy.ndarray.choose
            • numpy.ndarray.clip
            • numpy.ndarray.compress
            • numpy.ndarray.conj
            • numpy.ndarray.conjugate
            • numpy.ndarray.copy
            • numpy.ndarray.cumprod
            • numpy.ndarray.cumsum
            • numpy.ndarray.diagonal
            • numpy.ndarray.dot
            • numpy.ndarray.dump
            • numpy.ndarray.dumps
            • numpy.ndarray.fill
            • numpy.ndarray.flatten
            • numpy.ndarray.getfield
            • numpy.ndarray.item
            • numpy.ndarray.itemset
            • numpy.ndarray.max
            • numpy.ndarray.mean
            • numpy.ndarray.min
            • numpy.ndarray.newbyteorder
            • numpy.ndarray.nonzero
            • numpy.ndarray.partition
            • numpy.ndarray.prod
            • numpy.ndarray.ptp
            • numpy.ndarray.put
            • numpy.ndarray.ravel
            • numpy.ndarray.repeat
            • numpy.ndarray.reshape
            • numpy.ndarray.resize
            • numpy.ndarray.round
            • numpy.ndarray.searchsorted
            • numpy.ndarray.setfield
            • numpy.ndarray.setflags
            • numpy.ndarray.sort
            • numpy.ndarray.squeeze
            • numpy.ndarray.std
            • numpy.ndarray.sum
            • numpy.ndarray.swapaxes
            • numpy.ndarray.take
            • numpy.ndarray.tobytes
            • numpy.ndarray.tofile
            • numpy.ndarray.tolist
            • numpy.ndarray.tostring
            • numpy.ndarray.trace
            • numpy.ndarray.transpose
            • numpy.ndarray.var
            • numpy.ndarray.view
        • Indexing arrays
        • Internal memory layout of an ndarray
        • Array attributes
          • Memory layout
            • numpy.ndarray.flags
            • numpy.ndarray.shape
            • numpy.ndarray.strides
            • numpy.ndarray.ndim
            • numpy.ndarray.data
            • numpy.ndarray.size
            • numpy.ndarray.itemsize
            • numpy.ndarray.nbytes
            • numpy.ndarray.base
          • Data type
            • numpy.ndarray.dtype
          • Other attributes
            • numpy.ndarray.T
            • numpy.ndarray.real
            • numpy.ndarray.imag
            • numpy.ndarray.flat
            • numpy.ndarray.ctypes
          • Array interface
          • ctypes foreign function interface
            • numpy.ndarray.ctypes
        • Array methods
          • Array conversion
            • numpy.ndarray.item
            • numpy.ndarray.tolist
            • numpy.ndarray.itemset
            • numpy.ndarray.tostring
            • numpy.ndarray.tobytes
            • numpy.ndarray.tofile
            • numpy.ndarray.dump
            • numpy.ndarray.dumps
            • numpy.ndarray.astype
            • numpy.ndarray.byteswap
            • numpy.ndarray.copy
            • numpy.ndarray.view
            • numpy.ndarray.getfield
            • numpy.ndarray.setflags
            • numpy.ndarray.fill
          • Shape manipulation
            • numpy.ndarray.reshape
            • numpy.ndarray.resize
            • numpy.ndarray.transpose
            • numpy.ndarray.swapaxes
            • numpy.ndarray.flatten
            • numpy.ndarray.ravel
            • numpy.ndarray.squeeze
          • Item selection and manipulation
            • numpy.ndarray.take
            • numpy.ndarray.put
            • numpy.ndarray.repeat
            • numpy.ndarray.choose
            • numpy.ndarray.sort
            • numpy.ndarray.argsort
            • numpy.ndarray.partition
            • numpy.ndarray.argpartition
            • numpy.ndarray.searchsorted
            • numpy.ndarray.nonzero
            • numpy.ndarray.compress
            • numpy.ndarray.diagonal
          • Calculation
            • numpy.ndarray.argmax
            • numpy.ndarray.min
            • numpy.ndarray.argmin
            • numpy.ndarray.ptp
            • numpy.ndarray.clip
            • numpy.ndarray.conj
            • numpy.ndarray.round
            • numpy.ndarray.trace
            • numpy.ndarray.sum
            • numpy.ndarray.cumsum
            • numpy.ndarray.mean
            • numpy.ndarray.var
            • numpy.ndarray.std
            • numpy.ndarray.prod
            • numpy.ndarray.cumprod
            • numpy.ndarray.all
            • numpy.ndarray.any
        • Arithmetic and comparison operations
          • numpy.ndarray.__lt__
          • numpy.ndarray.__le__
          • numpy.ndarray.__gt__
          • numpy.ndarray.__ge__
          • numpy.ndarray.__eq__
          • numpy.ndarray.__ne__
          • numpy.ndarray.__nonzero__
          • numpy.ndarray.__neg__
          • numpy.ndarray.__pos__
          • numpy.ndarray.__abs__
          • numpy.ndarray.__invert__
          • numpy.ndarray.__add__
          • numpy.ndarray.__sub__
          • numpy.ndarray.__mul__
          • numpy.ndarray.__div__
          • numpy.ndarray.__truediv__
          • numpy.ndarray.__floordiv__
          • numpy.ndarray.__mod__
          • numpy.ndarray.__divmod__
          • numpy.ndarray.__pow__
          • numpy.ndarray.__lshift__
          • numpy.ndarray.__rshift__
          • numpy.ndarray.__and__
          • numpy.ndarray.__or__
          • numpy.ndarray.__xor__
          • numpy.ndarray.__iadd__
          • numpy.ndarray.__isub__
          • numpy.ndarray.__imul__
          • numpy.ndarray.__idiv__
          • numpy.ndarray.__itruediv__
          • numpy.ndarray.__ifloordiv__
          • numpy.ndarray.__imod__
          • numpy.ndarray.__ipow__
          • numpy.ndarray.__ilshift__
          • numpy.ndarray.__irshift__
          • numpy.ndarray.__iand__
          • numpy.ndarray.__ior__
          • numpy.ndarray.__ixor__
        • Special methods
          • numpy.ndarray.__copy__
          • numpy.ndarray.__deepcopy__
          • numpy.ndarray.__reduce__
          • numpy.ndarray.__setstate__
          • numpy.ndarray.__new__
          • numpy.ndarray.__array__
          • numpy.ndarray.__array_wrap__
          • numpy.ndarray.__len__
          • numpy.ndarray.__getitem__
          • numpy.ndarray.__setitem__
          • numpy.ndarray.__getslice__
          • numpy.ndarray.__setslice__
          • numpy.ndarray.__contains__
          • numpy.ndarray.__int__
          • numpy.ndarray.__long__
          • numpy.ndarray.__float__
          • numpy.ndarray.__oct__
          • numpy.ndarray.__hex__
          • numpy.ndarray.__str__
          • numpy.ndarray.__repr__
      • Scalars
        • Built-in scalar types
        • Attributes
          • numpy.generic.flags
          • numpy.generic.shape
          • numpy.generic.strides
          • numpy.generic.ndim
          • numpy.generic.data
          • numpy.generic.size
          • numpy.generic.itemsize
          • numpy.generic.base
          • numpy.generic.dtype
          • numpy.generic.real
          • numpy.generic.imag
          • numpy.generic.flat
          • numpy.generic.T
          • numpy.generic.__array_interface__
          • numpy.generic.__array_struct__
          • numpy.generic.__array_priority__
          • numpy.generic.__array_wrap__
        • Indexing
        • Methods
          • numpy.generic
            • numpy.generic.T
            • numpy.generic.base
            • numpy.generic.data
            • numpy.generic.dtype
            • numpy.generic.flags
            • numpy.generic.flat
            • numpy.generic.imag
            • numpy.generic.itemsize
            • numpy.generic.nbytes
            • numpy.generic.ndim
            • numpy.generic.real
            • numpy.generic.shape
            • numpy.generic.size
            • numpy.generic.strides
            • numpy.generic.all
            • numpy.generic.any
            • numpy.generic.argmax
            • numpy.generic.argmin
            • numpy.generic.argsort
            • numpy.generic.astype
            • numpy.generic.byteswap
            • numpy.generic.choose
            • numpy.generic.clip
            • numpy.generic.compress
            • numpy.generic.conj
            • numpy.generic.conjugate
            • numpy.generic.copy
            • numpy.generic.cumprod
            • numpy.generic.cumsum
            • numpy.generic.diagonal
            • numpy.generic.dump
            • numpy.generic.dumps
            • numpy.generic.fill
            • numpy.generic.flatten
            • numpy.generic.getfield
            • numpy.generic.item
            • numpy.generic.itemset
            • numpy.generic.max
            • numpy.generic.mean
            • numpy.generic.min
            • numpy.generic.newbyteorder
            • numpy.generic.nonzero
            • numpy.generic.prod
            • numpy.generic.ptp
            • numpy.generic.put
            • numpy.generic.ravel
            • numpy.generic.repeat
            • numpy.generic.reshape
            • numpy.generic.resize
            • numpy.generic.round
            • numpy.generic.searchsorted
            • numpy.generic.setfield
            • numpy.generic.setflags
            • numpy.generic.sort
            • numpy.generic.squeeze
            • numpy.generic.std
            • numpy.generic.sum
            • numpy.generic.swapaxes
            • numpy.generic.take
            • numpy.generic.tobytes
            • numpy.generic.tofile
            • numpy.generic.tolist
            • numpy.generic.tostring
            • numpy.generic.trace
            • numpy.generic.transpose
            • numpy.generic.var
            • numpy.generic.view
          • numpy.generic.__array__
          • numpy.generic.__array_wrap__
          • numpy.generic.squeeze
          • numpy.generic.byteswap
          • numpy.generic.__reduce__
          • numpy.generic.__setstate__
          • numpy.generic.setflags
        • Defining new types
      • Data type objects (dtype)
        • Specifying and constructing data types
          • numpy.dtype
            • numpy.dtype.base
            • numpy.dtype.descr
            • numpy.dtype.fields
            • numpy.dtype.hasobject
            • numpy.dtype.isalignedstruct
            • numpy.dtype.isbuiltin
            • numpy.dtype.isnative
            • numpy.dtype.metadata
            • numpy.dtype.name
            • numpy.dtype.names
            • numpy.dtype.shape
            • numpy.dtype.str
            • numpy.dtype.subdtype
            • numpy.dtype.newbyteorder
        • dtype
          • Attributes
            • numpy.dtype.type
            • numpy.dtype.kind
            • numpy.dtype.char
            • numpy.dtype.num
            • numpy.dtype.str
            • numpy.dtype.name
            • numpy.dtype.itemsize
            • numpy.dtype.byteorder
            • numpy.dtype.fields
            • numpy.dtype.names
            • numpy.dtype.subdtype
            • numpy.dtype.shape
            • numpy.dtype.hasobject
            • numpy.dtype.flags
            • numpy.dtype.isbuiltin
            • numpy.dtype.isnative
            • numpy.dtype.descr
            • numpy.dtype.alignment
          • Methods
            • numpy.dtype.newbyteorder
            • numpy.dtype.__reduce__
            • numpy.dtype.__setstate__
      • Indexing
        • Basic Slicing and Indexing
        • Advanced Indexing
          • Integer array indexing
            • Purely integer array indexing
            • Combining advanced and basic indexing
          • Boolean array indexing
        • Detailed notes
        • Record Access
        • Flat Iterator indexing
      • Iterating Over Arrays
        • Single Array Iteration
          • Controlling Iteration Order
          • Modifying Array Values
          • Using an External Loop
          • Tracking an Index or Multi-Index
          • Buffering the Array Elements
          • Iterating as a Specific Data Type
        • Broadcasting Array Iteration
          • Iterator-Allocated Output Arrays
          • Outer Product Iteration
          • Reduction Iteration
        • Putting the Inner Loop in Cython
      • Standard array subclasses
        • Special attributes and methods
        • Matrix objects
          • numpy.matrix.T
          • numpy.matrix.H
          • numpy.matrix.I
          • numpy.matrix.A
          • numpy.matrix
            • numpy.matrix.A
            • numpy.matrix.A1
            • numpy.matrix.H
            • numpy.matrix.I
            • numpy.matrix.T
            • numpy.matrix.base
            • numpy.matrix.ctypes
            • numpy.matrix.data
            • numpy.matrix.dtype
            • numpy.matrix.flags
            • numpy.matrix.flat
            • numpy.matrix.imag
            • numpy.matrix.itemsize
            • numpy.matrix.nbytes
            • numpy.matrix.ndim
            • numpy.matrix.real
            • numpy.matrix.shape
            • numpy.matrix.size
            • numpy.matrix.strides
            • numpy.matrix.all
            • numpy.matrix.any
            • numpy.matrix.argmax
            • numpy.matrix.argmin
            • numpy.matrix.argpartition
            • numpy.matrix.argsort
            • numpy.matrix.astype
            • numpy.matrix.byteswap
            • numpy.matrix.choose
            • numpy.matrix.clip
            • numpy.matrix.compress
            • numpy.matrix.conj
            • numpy.matrix.conjugate
            • numpy.matrix.copy
            • numpy.matrix.cumprod
            • numpy.matrix.cumsum
            • numpy.matrix.diagonal
            • numpy.matrix.dot
            • numpy.matrix.dump
            • numpy.matrix.dumps
            • numpy.matrix.fill
            • numpy.matrix.flatten
            • numpy.matrix.getA
            • numpy.matrix.getA1
            • numpy.matrix.getH
            • numpy.matrix.getI
            • numpy.matrix.getT
            • numpy.matrix.getfield
            • numpy.matrix.item
            • numpy.matrix.itemset
            • numpy.matrix.max
            • numpy.matrix.mean
            • numpy.matrix.min
            • numpy.matrix.newbyteorder
            • numpy.matrix.nonzero
            • numpy.matrix.partition
            • numpy.matrix.prod
            • numpy.matrix.ptp
            • numpy.matrix.put
            • numpy.matrix.ravel
            • numpy.matrix.repeat
            • numpy.matrix.reshape
            • numpy.matrix.resize
            • numpy.matrix.round
            • numpy.matrix.searchsorted
            • numpy.matrix.setfield
            • numpy.matrix.setflags
            • numpy.matrix.sort
            • numpy.matrix.squeeze
            • numpy.matrix.std
            • numpy.matrix.sum
            • numpy.matrix.swapaxes
            • numpy.matrix.take
            • numpy.matrix.tobytes
            • numpy.matrix.tofile
            • numpy.matrix.tolist
            • numpy.matrix.tostring
            • numpy.matrix.trace
            • numpy.matrix.transpose
            • numpy.matrix.var
            • numpy.matrix.view
          • numpy.asmatrix
          • numpy.bmat
        • Memory-mapped file arrays
          • numpy.memmap
            • numpy.memmap.flush
          • numpy.memmap.flush
        • Character arrays (numpy.char)
          • numpy.chararray
            • numpy.chararray.T
            • numpy.chararray.base
            • numpy.chararray.ctypes
            • numpy.chararray.data
            • numpy.chararray.dtype
            • numpy.chararray.flags
            • numpy.chararray.flat
            • numpy.chararray.imag
            • numpy.chararray.itemsize
            • numpy.chararray.nbytes
            • numpy.chararray.ndim
            • numpy.chararray.real
            • numpy.chararray.shape
            • numpy.chararray.size
            • numpy.chararray.strides
            • numpy.chararray.astype
            • numpy.chararray.copy
            • numpy.chararray.count
            • numpy.chararray.decode
            • numpy.chararray.dump
            • numpy.chararray.dumps
            • numpy.chararray.encode
            • numpy.chararray.endswith
            • numpy.chararray.expandtabs
            • numpy.chararray.fill
            • numpy.chararray.find
            • numpy.chararray.flatten
            • numpy.chararray.getfield
            • numpy.chararray.index
            • numpy.chararray.isalnum
            • numpy.chararray.isalpha
            • numpy.chararray.isdecimal
            • numpy.chararray.isdigit
            • numpy.chararray.islower
            • numpy.chararray.isnumeric
            • numpy.chararray.isspace
            • numpy.chararray.istitle
            • numpy.chararray.isupper
            • numpy.chararray.item
            • numpy.chararray.join
            • numpy.chararray.ljust
            • numpy.chararray.lower
            • numpy.chararray.lstrip
            • numpy.chararray.nonzero
            • numpy.chararray.put
            • numpy.chararray.ravel
            • numpy.chararray.repeat
            • numpy.chararray.replace
            • numpy.chararray.reshape
            • numpy.chararray.resize
            • numpy.chararray.rfind
            • numpy.chararray.rindex
            • numpy.chararray.rjust
            • numpy.chararray.rsplit
            • numpy.chararray.rstrip
            • numpy.chararray.searchsorted
            • numpy.chararray.setfield
            • numpy.chararray.setflags
            • numpy.chararray.sort
            • numpy.chararray.split
            • numpy.chararray.splitlines
            • numpy.chararray.squeeze
            • numpy.chararray.startswith
            • numpy.chararray.strip
            • numpy.chararray.swapaxes
            • numpy.chararray.swapcase
            • numpy.chararray.take
            • numpy.chararray.title
            • numpy.chararray.tofile
            • numpy.chararray.tolist
            • numpy.chararray.tostring
            • numpy.chararray.translate
            • numpy.chararray.transpose
            • numpy.chararray.upper
            • numpy.chararray.view
            • numpy.chararray.zfill
          • numpy.core.defchararray.array
        • Record arrays (numpy.rec)
          • numpy.recarray
            • numpy.recarray.T
            • numpy.recarray.base
            • numpy.recarray.ctypes
            • numpy.recarray.data
            • numpy.recarray.dtype
            • numpy.recarray.flags
            • numpy.recarray.flat
            • numpy.recarray.imag
            • numpy.recarray.itemsize
            • numpy.recarray.nbytes
            • numpy.recarray.ndim
            • numpy.recarray.real
            • numpy.recarray.shape
            • numpy.recarray.size
            • numpy.recarray.strides
            • numpy.recarray.all
            • numpy.recarray.any
            • numpy.recarray.argmax
            • numpy.recarray.argmin
            • numpy.recarray.argpartition
            • numpy.recarray.argsort
            • numpy.recarray.astype
            • numpy.recarray.byteswap
            • numpy.recarray.choose
            • numpy.recarray.clip
            • numpy.recarray.compress
            • numpy.recarray.conj
            • numpy.recarray.conjugate
            • numpy.recarray.copy
            • numpy.recarray.cumprod
            • numpy.recarray.cumsum
            • numpy.recarray.diagonal
            • numpy.recarray.dot
            • numpy.recarray.dump
            • numpy.recarray.dumps
            • numpy.recarray.field
            • numpy.recarray.fill
            • numpy.recarray.flatten
            • numpy.recarray.getfield
            • numpy.recarray.item
            • numpy.recarray.itemset
            • numpy.recarray.max
            • numpy.recarray.mean
            • numpy.recarray.min
            • numpy.recarray.newbyteorder
            • numpy.recarray.nonzero
            • numpy.recarray.partition
            • numpy.recarray.prod
            • numpy.recarray.ptp
            • numpy.recarray.put
            • numpy.recarray.ravel
            • numpy.recarray.repeat
            • numpy.recarray.reshape
            • numpy.recarray.resize
            • numpy.recarray.round
            • numpy.recarray.searchsorted
            • numpy.recarray.setfield
            • numpy.recarray.setflags
            • numpy.recarray.sort
            • numpy.recarray.squeeze
            • numpy.recarray.std
            • numpy.recarray.sum
            • numpy.recarray.swapaxes
            • numpy.recarray.take
            • numpy.recarray.tobytes
            • numpy.recarray.tofile
            • numpy.recarray.tolist
            • numpy.recarray.tostring
            • numpy.recarray.trace
            • numpy.recarray.transpose
            • numpy.recarray.var
            • numpy.recarray.view
          • numpy.record
            • numpy.record.T
            • numpy.record.base
            • numpy.record.data
            • numpy.record.dtype
            • numpy.record.flags
            • numpy.record.flat
            • numpy.record.imag
            • numpy.record.itemsize
            • numpy.record.nbytes
            • numpy.record.ndim
            • numpy.record.real
            • numpy.record.shape
            • numpy.record.size
            • numpy.record.strides
            • numpy.record.all
            • numpy.record.any
            • numpy.record.argmax
            • numpy.record.argmin
            • numpy.record.argsort
            • numpy.record.astype
            • numpy.record.byteswap
            • numpy.record.choose
            • numpy.record.clip
            • numpy.record.compress
            • numpy.record.conj
            • numpy.record.conjugate
            • numpy.record.copy
            • numpy.record.cumprod
            • numpy.record.cumsum
            • numpy.record.diagonal
            • numpy.record.dump
            • numpy.record.dumps
            • numpy.record.fill
            • numpy.record.flatten
            • numpy.record.getfield
            • numpy.record.item
            • numpy.record.itemset
            • numpy.record.max
            • numpy.record.mean
            • numpy.record.min
            • numpy.record.newbyteorder
            • numpy.record.nonzero
            • numpy.record.pprint
            • numpy.record.prod
            • numpy.record.ptp
            • numpy.record.put
            • numpy.record.ravel
            • numpy.record.repeat
            • numpy.record.reshape
            • numpy.record.resize
            • numpy.record.round
            • numpy.record.searchsorted
            • numpy.record.setfield
            • numpy.record.setflags
            • numpy.record.sort
            • numpy.record.squeeze
            • numpy.record.std
            • numpy.record.sum
            • numpy.record.swapaxes
            • numpy.record.take
            • numpy.record.tobytes
            • numpy.record.tofile
            • numpy.record.tolist
            • numpy.record.tostring
            • numpy.record.trace
            • numpy.record.transpose
            • numpy.record.var
            • numpy.record.view
        • Masked arrays (numpy.ma)
        • Standard container class
          • numpy.lib.user_array.container
            • numpy.lib.user_array.container.astype
            • numpy.lib.user_array.container.byteswap
            • numpy.lib.user_array.container.copy
            • numpy.lib.user_array.container.tostring
        • Array Iterators
          • Default iteration
          • Flat iteration
            • numpy.ndarray.flat
          • N-dimensional enumeration
            • numpy.ndenumerate
              • numpy.ndenumerate.next
          • Iterator for broadcasting
            • numpy.broadcast
              • numpy.broadcast.index
              • numpy.broadcast.iters
              • numpy.broadcast.shape
              • numpy.broadcast.size
              • numpy.broadcast.next
              • numpy.broadcast.reset
      • Masked arrays
        • The numpy.ma module
          • Rationale
          • What is a masked array?
          • The numpy.ma module
        • Using numpy.ma
          • Constructing masked arrays
            • numpy.ma.array
            • numpy.ma.masked_array
            • numpy.ma.asarray
            • numpy.ma.asanyarray
            • numpy.ma.fix_invalid
            • numpy.ma.masked_equal
            • numpy.ma.masked_greater
            • numpy.ma.masked_greater_equal
            • numpy.ma.masked_inside
            • numpy.ma.masked_invalid
            • numpy.ma.masked_less
            • numpy.ma.masked_less_equal
            • numpy.ma.masked_not_equal
            • numpy.ma.masked_object
            • numpy.ma.masked_outside
            • numpy.ma.masked_values
            • numpy.ma.masked_where
          • Accessing the data
          • Accessing the mask
          • Accessing only the valid entries
          • Modifying the mask
            • Masking an entry
            • Unmasking an entry
          • Indexing and slicing
          • Operations on masked arrays
        • Examples
          • Data with a given value representing missing data
          • Filling in the missing data
          • Numerical operations
          • Ignoring extreme values
        • Constants of the numpy.ma module
        • The MaskedArray class
          • Attributes and properties of masked arrays
            • numpy.ma.MaskedArray.base
            • numpy.ma.MaskedArray.ctypes
            • numpy.ma.MaskedArray.dtype
            • numpy.ma.MaskedArray.flags
            • numpy.ma.MaskedArray.itemsize
            • numpy.ma.MaskedArray.nbytes
            • numpy.ma.MaskedArray.ndim
            • numpy.ma.MaskedArray.shape
            • numpy.ma.MaskedArray.size
            • numpy.ma.MaskedArray.strides
            • numpy.ma.MaskedArray.imag
            • numpy.ma.MaskedArray.real
            • numpy.ma.MaskedArray.flat
            • numpy.ma.MaskedArray.__array_priority__
        • MaskedArray methods
          • Conversion
            • numpy.ma.MaskedArray.__float__
            • numpy.ma.MaskedArray.__hex__
            • numpy.ma.MaskedArray.__int__
            • numpy.ma.MaskedArray.__long__
            • numpy.ma.MaskedArray.__oct__
            • numpy.ma.MaskedArray.view
            • numpy.ma.MaskedArray.astype
            • numpy.ma.MaskedArray.byteswap
            • numpy.ma.MaskedArray.compressed
            • numpy.ma.MaskedArray.filled
            • numpy.ma.MaskedArray.tofile
            • numpy.ma.MaskedArray.toflex
            • numpy.ma.MaskedArray.tolist
            • numpy.ma.MaskedArray.torecords
            • numpy.ma.MaskedArray.tostring
            • numpy.ma.MaskedArray.tobytes
          • Shape manipulation
            • numpy.ma.MaskedArray.flatten
            • numpy.ma.MaskedArray.ravel
            • numpy.ma.MaskedArray.reshape
            • numpy.ma.MaskedArray.resize
            • numpy.ma.MaskedArray.squeeze
            • numpy.ma.MaskedArray.swapaxes
            • numpy.ma.MaskedArray.transpose
            • numpy.ma.MaskedArray.T
          • Item selection and manipulation
            • numpy.ma.MaskedArray.argmax
            • numpy.ma.MaskedArray.argmin
            • numpy.ma.MaskedArray.argsort
            • numpy.ma.MaskedArray.choose
            • numpy.ma.MaskedArray.compress
            • numpy.ma.MaskedArray.diagonal
            • numpy.ma.MaskedArray.fill
            • numpy.ma.MaskedArray.item
            • numpy.ma.MaskedArray.nonzero
            • numpy.ma.MaskedArray.put
            • numpy.ma.MaskedArray.repeat
            • numpy.ma.MaskedArray.searchsorted
            • numpy.ma.MaskedArray.sort
            • numpy.ma.MaskedArray.take
          • Pickling and copy
            • numpy.ma.MaskedArray.copy
            • numpy.ma.MaskedArray.dump
            • numpy.ma.MaskedArray.dumps
          • Calculations
            • numpy.ma.MaskedArray.all
            • numpy.ma.MaskedArray.anom
            • numpy.ma.MaskedArray.any
            • numpy.ma.MaskedArray.clip
            • numpy.ma.MaskedArray.conj
            • numpy.ma.MaskedArray.conjugate
            • numpy.ma.MaskedArray.cumprod
            • numpy.ma.MaskedArray.cumsum
            • numpy.ma.MaskedArray.max
            • numpy.ma.MaskedArray.mean
            • numpy.ma.MaskedArray.min
            • numpy.ma.MaskedArray.prod
            • numpy.ma.MaskedArray.product
            • numpy.ma.MaskedArray.ptp
            • numpy.ma.MaskedArray.round
            • numpy.ma.MaskedArray.std
            • numpy.ma.MaskedArray.sum
            • numpy.ma.MaskedArray.trace
            • numpy.ma.MaskedArray.var
          • Arithmetic and comparison operations
            • Comparison operators:
              • numpy.ma.MaskedArray.__lt__
              • numpy.ma.MaskedArray.__le__
              • numpy.ma.MaskedArray.__gt__
              • numpy.ma.MaskedArray.__ge__
              • numpy.ma.MaskedArray.__eq__
              • numpy.ma.MaskedArray.__ne__
            • Truth value of an array (bool):
              • numpy.ma.MaskedArray.__nonzero__
            • Arithmetic:
              • numpy.ma.MaskedArray.__abs__
              • numpy.ma.MaskedArray.__add__
              • numpy.ma.MaskedArray.__radd__
              • numpy.ma.MaskedArray.__sub__
              • numpy.ma.MaskedArray.__rsub__
              • numpy.ma.MaskedArray.__mul__
              • numpy.ma.MaskedArray.__rmul__
              • numpy.ma.MaskedArray.__div__
              • numpy.ma.MaskedArray.__rdiv__
              • numpy.ma.MaskedArray.__truediv__
              • numpy.ma.MaskedArray.__rtruediv__
              • numpy.ma.MaskedArray.__floordiv__
              • numpy.ma.MaskedArray.__rfloordiv__
              • numpy.ma.MaskedArray.__mod__
              • numpy.ma.MaskedArray.__rmod__
              • numpy.ma.MaskedArray.__divmod__
              • numpy.ma.MaskedArray.__rdivmod__
              • numpy.ma.MaskedArray.__pow__
              • numpy.ma.MaskedArray.__rpow__
              • numpy.ma.MaskedArray.__lshift__
              • numpy.ma.MaskedArray.__rlshift__
              • numpy.ma.MaskedArray.__rshift__
              • numpy.ma.MaskedArray.__rrshift__
              • numpy.ma.MaskedArray.__and__
              • numpy.ma.MaskedArray.__rand__
              • numpy.ma.MaskedArray.__or__
              • numpy.ma.MaskedArray.__ror__
              • numpy.ma.MaskedArray.__xor__
              • numpy.ma.MaskedArray.__rxor__
            • Arithmetic, in-place:
              • numpy.ma.MaskedArray.__iadd__
              • numpy.ma.MaskedArray.__isub__
              • numpy.ma.MaskedArray.__imul__
              • numpy.ma.MaskedArray.__idiv__
              • numpy.ma.MaskedArray.__itruediv__
              • numpy.ma.MaskedArray.__ifloordiv__
              • numpy.ma.MaskedArray.__imod__
              • numpy.ma.MaskedArray.__ipow__
              • numpy.ma.MaskedArray.__ilshift__
              • numpy.ma.MaskedArray.__irshift__
              • numpy.ma.MaskedArray.__iand__
              • numpy.ma.MaskedArray.__ior__
              • numpy.ma.MaskedArray.__ixor__
          • Representation
            • numpy.ma.MaskedArray.__repr__
            • numpy.ma.MaskedArray.__str__
            • numpy.ma.MaskedArray.ids
            • numpy.ma.MaskedArray.iscontiguous
          • Special methods
            • numpy.ma.MaskedArray.__copy__
            • numpy.ma.MaskedArray.__deepcopy__
            • numpy.ma.MaskedArray.__getstate__
            • numpy.ma.MaskedArray.__reduce__
            • numpy.ma.MaskedArray.__setstate__
            • numpy.ma.MaskedArray.__new__
            • numpy.ma.MaskedArray.__array__
            • numpy.ma.MaskedArray.__array_wrap__
            • numpy.ma.MaskedArray.__len__
            • numpy.ma.MaskedArray.__getitem__
            • numpy.ma.MaskedArray.__setitem__
            • numpy.ma.MaskedArray.__delitem__
            • numpy.ma.MaskedArray.__getslice__
            • numpy.ma.MaskedArray.__setslice__
            • numpy.ma.MaskedArray.__contains__
          • Specific methods
            • Handling the mask
              • numpy.ma.MaskedArray.__setmask__
              • numpy.ma.MaskedArray.harden_mask
              • numpy.ma.MaskedArray.soften_mask
              • numpy.ma.MaskedArray.unshare_mask
              • numpy.ma.MaskedArray.shrink_mask
            • Handling the fill_value
              • numpy.ma.MaskedArray.get_fill_value
              • numpy.ma.MaskedArray.set_fill_value
            • Counting the missing elements
              • numpy.ma.MaskedArray.count
        • Masked array operations
          • Constants
            • numpy.ma.MaskType
          • Creation
            • From existing data
              • numpy.ma.masked_array
              • numpy.ma.array
              • numpy.ma.copy
              • numpy.ma.frombuffer
              • numpy.ma.fromfunction
              • numpy.ma.MaskedArray.copy
            • Ones and zeros
              • numpy.ma.empty
              • numpy.ma.empty_like
              • numpy.ma.masked_all
              • numpy.ma.masked_all_like
              • numpy.ma.ones
              • numpy.ma.zeros
          • Inspecting the array
            • numpy.ma.all
            • numpy.ma.any
            • numpy.ma.count
            • numpy.ma.count_masked
            • numpy.ma.getmask
            • numpy.ma.getmaskarray
            • numpy.ma.getdata
            • numpy.ma.nonzero
            • numpy.ma.shape
            • numpy.ma.size
            • numpy.ma.is_masked
            • numpy.ma.is_mask
            • numpy.ma.MaskedArray.data
            • numpy.ma.MaskedArray.mask
            • numpy.ma.MaskedArray.recordmask
            • numpy.ma.MaskedArray.all
            • numpy.ma.MaskedArray.any
            • numpy.ma.MaskedArray.count
            • numpy.ma.MaskedArray.nonzero
            • numpy.ma.shape
            • numpy.ma.size
          • Manipulating a MaskedArray
            • Changing the shape
              • numpy.ma.ravel
              • numpy.ma.reshape
              • numpy.ma.resize
              • numpy.ma.MaskedArray.flatten
              • numpy.ma.MaskedArray.ravel
              • numpy.ma.MaskedArray.reshape
              • numpy.ma.MaskedArray.resize
            • Modifying axes
              • numpy.ma.swapaxes
              • numpy.ma.transpose
              • numpy.ma.MaskedArray.swapaxes
              • numpy.ma.MaskedArray.transpose
            • Changing the number of dimensions
              • numpy.ma.atleast_1d
              • numpy.ma.atleast_2d
              • numpy.ma.atleast_3d
              • numpy.ma.expand_dims
              • numpy.ma.squeeze
              • numpy.ma.MaskedArray.squeeze
              • numpy.ma.column_stack
              • numpy.ma.concatenate
              • numpy.ma.dstack
              • numpy.ma.hstack
              • numpy.ma.hsplit
              • numpy.ma.mr
              • numpy.ma.row_stack
              • numpy.ma.vstack
            • Joining arrays
              • numpy.ma.column_stack
              • numpy.ma.concatenate
              • numpy.ma.append
              • numpy.ma.dstack
              • numpy.ma.hstack
              • numpy.ma.vstack
          • Operations on masks
            • Creating a mask
              • numpy.ma.make_mask
              • numpy.ma.make_mask_none
              • numpy.ma.mask_or
              • numpy.ma.make_mask_descr
            • Accessing a mask
              • numpy.ma.getmask
              • numpy.ma.getmaskarray
              • numpy.ma.masked_array.mask
            • Finding masked data
              • numpy.ma.flatnotmasked_contiguous
              • numpy.ma.flatnotmasked_edges
              • numpy.ma.notmasked_contiguous
              • numpy.ma.notmasked_edges
            • Modifying a mask
              • numpy.ma.mask_cols
              • numpy.ma.mask_or
              • numpy.ma.mask_rowcols
              • numpy.ma.mask_rows
              • numpy.ma.harden_mask
              • numpy.ma.soften_mask
              • numpy.ma.MaskedArray.harden_mask
              • numpy.ma.MaskedArray.soften_mask
              • numpy.ma.MaskedArray.shrink_mask
              • numpy.ma.MaskedArray.unshare_mask
          • Conversion operations
            • > to a masked array
              • numpy.ma.asarray
              • numpy.ma.asanyarray
              • numpy.ma.fix_invalid
              • numpy.ma.masked_equal
              • numpy.ma.masked_greater
              • numpy.ma.masked_greater_equal
              • numpy.ma.masked_inside
              • numpy.ma.masked_invalid
              • numpy.ma.masked_less
              • numpy.ma.masked_less_equal
              • numpy.ma.masked_not_equal
              • numpy.ma.masked_object
              • numpy.ma.masked_outside
              • numpy.ma.masked_values
              • numpy.ma.masked_where
            • > to a ndarray
              • numpy.ma.compress_cols
              • numpy.ma.compress_rowcols
              • numpy.ma.compress_rows
              • numpy.ma.compressed
              • numpy.ma.filled
              • numpy.ma.MaskedArray.compressed
              • numpy.ma.MaskedArray.filled
            • > to another object
              • numpy.ma.MaskedArray.tofile
              • numpy.ma.MaskedArray.tolist
              • numpy.ma.MaskedArray.torecords
              • numpy.ma.MaskedArray.tobytes
            • Pickling and unpickling
              • numpy.ma.dump
              • numpy.ma.dumps
              • numpy.ma.load
              • numpy.ma.loads
            • Filling a masked array
              • numpy.ma.common_fill_value
              • numpy.ma.default_fill_value
              • numpy.ma.maximum_fill_value
              • numpy.ma.maximum_fill_value
              • numpy.ma.set_fill_value
              • numpy.ma.MaskedArray.get_fill_value
              • numpy.ma.MaskedArray.set_fill_value
              • numpy.ma.MaskedArray.fill_value
          • Masked arrays arithmetics
            • Arithmetics
              • numpy.ma.anom
              • numpy.ma.anomalies
              • numpy.ma.average
              • numpy.ma.conjugate
              • numpy.ma.corrcoef
              • numpy.ma.cov
              • numpy.ma.cumsum
              • numpy.ma.cumprod
              • numpy.ma.mean
              • numpy.ma.median
              • numpy.ma.power
              • numpy.ma.prod
              • numpy.ma.std
              • numpy.ma.sum
              • numpy.ma.var
              • numpy.ma.MaskedArray.anom
              • numpy.ma.MaskedArray.cumprod
              • numpy.ma.MaskedArray.cumsum
              • numpy.ma.MaskedArray.mean
              • numpy.ma.MaskedArray.prod
              • numpy.ma.MaskedArray.std
              • numpy.ma.MaskedArray.sum
              • numpy.ma.MaskedArray.var
            • Minimum/maximum
              • numpy.ma.argmax
              • numpy.ma.argmin
              • numpy.ma.max
              • numpy.ma.min
              • numpy.ma.ptp
              • numpy.ma.MaskedArray.argmax
              • numpy.ma.MaskedArray.argmin
              • numpy.ma.MaskedArray.max
              • numpy.ma.MaskedArray.min
              • numpy.ma.MaskedArray.ptp
            • Sorting
              • numpy.ma.argsort
              • numpy.ma.sort
              • numpy.ma.MaskedArray.argsort
              • numpy.ma.MaskedArray.sort
            • Algebra
              • numpy.ma.diag
              • numpy.ma.dot
              • numpy.ma.identity
              • numpy.ma.inner
              • numpy.ma.innerproduct
              • numpy.ma.outer
              • numpy.ma.outerproduct
              • numpy.ma.trace
              • numpy.ma.transpose
              • numpy.ma.MaskedArray.trace
              • numpy.ma.MaskedArray.transpose
            • Polynomial fit
              • numpy.ma.vander
              • numpy.ma.polyfit
            • Clipping and rounding
              • numpy.ma.around
              • numpy.ma.clip
              • numpy.ma.round
              • numpy.ma.MaskedArray.clip
              • numpy.ma.MaskedArray.round
            • Miscellanea
              • numpy.ma.allequal
              • numpy.ma.allclose
              • numpy.ma.apply_along_axis
              • numpy.ma.arange
              • numpy.ma.choose
              • numpy.ma.ediff1d
              • numpy.ma.indices
              • numpy.ma.where
      • The Array Interface
        • Python side
        • C-struct access
        • Type description examples
        • Differences with Array interface (Version 2)
      • Datetimes and Timedeltas
        • Basic Datetimes
        • Datetime and Timedelta Arithmetic
        • Datetime Units
        • Business Day Functionality
          • np.is_busday():
          • np.busday_count():
            • Custom Weekmasks
        • Differences Between 1.6 and 1.7 Datetimes
          • String Parsing
          • Unit Conversion
          • Datetime Arithmetic
    • Universal functions (ufunc)
      • Broadcasting
      • Output type determination
      • Use of internal buffers
        • numpy.setbufsize
      • Error handling
        • numpy.seterr
        • numpy.seterrcall
      • Casting Rules
      • Overriding Ufunc behavior
      • ufunc
        • Optional keyword arguments
        • Attributes
          • numpy.ufunc.nin
          • numpy.ufunc.nout
          • numpy.ufunc.nargs
          • numpy.ufunc.ntypes
          • numpy.ufunc.types
          • numpy.ufunc.identity
        • Methods
          • numpy.ufunc.reduce
          • numpy.ufunc.accumulate
          • numpy.ufunc.reduceat
          • numpy.ufunc.outer
          • numpy.ufunc.at
      • Available ufuncs
        • Math operations
        • Trigonometric functions
        • Bit-twiddling functions
        • Comparison functions
        • Floating functions
    • Routines
      • Array creation routines
        • Ones and zeros
          • numpy.empty
          • numpy.empty_like
          • numpy.eye
          • numpy.identity
          • numpy.ones
          • numpy.ones_like
          • numpy.zeros
          • numpy.zeros_like
          • numpy.full
          • numpy.full_like
        • From existing data
          • numpy.array
          • numpy.asarray
          • numpy.asanyarray
          • numpy.ascontiguousarray
          • numpy.asmatrix
          • numpy.copy
          • numpy.frombuffer
          • numpy.fromfile
          • numpy.fromfunction
          • numpy.fromiter
          • numpy.fromstring
          • numpy.loadtxt
        • Creating record arrays (numpy.rec)
          • numpy.core.records.array
          • numpy.core.records.fromarrays
          • numpy.core.records.fromrecords
          • numpy.core.records.fromstring
          • numpy.core.records.fromfile
        • Creating character arrays (numpy.char)
          • numpy.core.defchararray.array
          • numpy.core.defchararray.asarray
        • Numerical ranges
          • numpy.arange
          • numpy.linspace
          • numpy.logspace
          • numpy.meshgrid
          • numpy.mgrid
          • numpy.ogrid
        • Building matrices
          • numpy.diag
          • numpy.diagflat
          • numpy.tri
          • numpy.tril
          • numpy.triu
          • numpy.vander
        • The Matrix class
          • numpy.mat
          • numpy.bmat
      • Array manipulation routines
        • Basic operations
          • numpy.copyto
        • Changing array shape
          • numpy.reshape
          • numpy.ravel
          • numpy.ndarray.flat
          • numpy.ndarray.flatten
        • Transpose-like operations
          • numpy.rollaxis
          • numpy.swapaxes
          • numpy.ndarray.T
          • numpy.transpose
        • Changing number of dimensions
          • numpy.atleast_1d
          • numpy.atleast_2d
          • numpy.atleast_3d
          • numpy.broadcast
            • numpy.broadcast.index
            • numpy.broadcast.iters
            • numpy.broadcast.shape
            • numpy.broadcast.size
            • numpy.broadcast.next
            • numpy.broadcast.reset
          • numpy.broadcast_arrays
          • numpy.expand_dims
          • numpy.squeeze
        • Changing kind of array
          • numpy.asarray
          • numpy.asanyarray
          • numpy.asmatrix
          • numpy.asfarray
          • numpy.asfortranarray
          • numpy.ascontiguousarray
          • numpy.asarray_chkfinite
          • numpy.asscalar
          • numpy.require
        • Joining arrays
          • numpy.column_stack
          • numpy.concatenate
          • numpy.dstack
          • numpy.hstack
          • numpy.vstack
        • Splitting arrays
          • numpy.array_split
          • numpy.dsplit
          • numpy.hsplit
          • numpy.split
          • numpy.vsplit
        • Tiling arrays
          • numpy.tile
          • numpy.repeat
        • Adding and removing elements
          • numpy.delete
          • numpy.insert
          • numpy.append
          • numpy.resize
          • numpy.trim_zeros
          • numpy.unique
        • Rearranging elements
          • numpy.fliplr
          • numpy.flipud
          • numpy.reshape
          • numpy.roll
          • numpy.rot90
      • Binary operations
        • Elementwise bit operations
          • numpy.bitwise_and
          • numpy.bitwise_or
          • numpy.bitwise_xor
          • numpy.invert
          • numpy.left_shift
          • numpy.right_shift
        • Bit packing
          • numpy.packbits
          • numpy.unpackbits
        • Output formatting
          • numpy.binary_repr
      • String operations
        • String operations
          • numpy.core.defchararray.add
          • numpy.core.defchararray.multiply
          • numpy.core.defchararray.mod
          • numpy.core.defchararray.capitalize
          • numpy.core.defchararray.center
          • numpy.core.defchararray.decode
          • numpy.core.defchararray.encode
          • numpy.core.defchararray.join
          • numpy.core.defchararray.ljust
          • numpy.core.defchararray.lower
          • numpy.core.defchararray.lstrip
          • numpy.core.defchararray.partition
          • numpy.core.defchararray.replace
          • numpy.core.defchararray.rjust
          • numpy.core.defchararray.rpartition
          • numpy.core.defchararray.rsplit
          • numpy.core.defchararray.rstrip
          • numpy.core.defchararray.split
          • numpy.core.defchararray.splitlines
          • numpy.core.defchararray.strip
          • numpy.core.defchararray.swapcase
          • numpy.core.defchararray.title
          • numpy.core.defchararray.translate
          • numpy.core.defchararray.upper
          • numpy.core.defchararray.zfill
        • Comparison
          • numpy.core.defchararray.equal
          • numpy.core.defchararray.not_equal
          • numpy.core.defchararray.greater_equal
          • numpy.core.defchararray.less_equal
          • numpy.core.defchararray.greater
          • numpy.core.defchararray.less
        • String information
          • numpy.core.defchararray.count
          • numpy.core.defchararray.find
          • numpy.core.defchararray.index
          • numpy.core.defchararray.isalpha
          • numpy.core.defchararray.isdecimal
          • numpy.core.defchararray.isdigit
          • numpy.core.defchararray.islower
          • numpy.core.defchararray.isnumeric
          • numpy.core.defchararray.isspace
          • numpy.core.defchararray.istitle
          • numpy.core.defchararray.isupper
          • numpy.core.defchararray.rfind
          • numpy.core.defchararray.rindex
          • numpy.core.defchararray.startswith
        • Convenience class
          • numpy.core.defchararray.chararray
            • numpy.core.defchararray.chararray.T
            • numpy.core.defchararray.chararray.base
            • numpy.core.defchararray.chararray.ctypes
            • numpy.core.defchararray.chararray.data
            • numpy.core.defchararray.chararray.dtype
            • numpy.core.defchararray.chararray.flags
            • numpy.core.defchararray.chararray.flat
            • numpy.core.defchararray.chararray.imag
            • numpy.core.defchararray.chararray.itemsize
            • numpy.core.defchararray.chararray.nbytes
            • numpy.core.defchararray.chararray.ndim
            • numpy.core.defchararray.chararray.real
            • numpy.core.defchararray.chararray.shape
            • numpy.core.defchararray.chararray.size
            • numpy.core.defchararray.chararray.strides
            • numpy.core.defchararray.chararray.astype
            • numpy.core.defchararray.chararray.copy
            • numpy.core.defchararray.chararray.count
            • numpy.core.defchararray.chararray.decode
            • numpy.core.defchararray.chararray.dump
            • numpy.core.defchararray.chararray.dumps
            • numpy.core.defchararray.chararray.encode
            • numpy.core.defchararray.chararray.endswith
            • numpy.core.defchararray.chararray.expandtabs
            • numpy.core.defchararray.chararray.fill
            • numpy.core.defchararray.chararray.find
            • numpy.core.defchararray.chararray.flatten
            • numpy.core.defchararray.chararray.getfield
            • numpy.core.defchararray.chararray.index
            • numpy.core.defchararray.chararray.isalnum
            • numpy.core.defchararray.chararray.isalpha
            • numpy.core.defchararray.chararray.isdecimal
            • numpy.core.defchararray.chararray.isdigit
            • numpy.core.defchararray.chararray.islower
            • numpy.core.defchararray.chararray.isnumeric
            • numpy.core.defchararray.chararray.isspace
            • numpy.core.defchararray.chararray.istitle
            • numpy.core.defchararray.chararray.isupper
            • numpy.core.defchararray.chararray.item
            • numpy.core.defchararray.chararray.join
            • numpy.core.defchararray.chararray.ljust
            • numpy.core.defchararray.chararray.lower
            • numpy.core.defchararray.chararray.lstrip
            • numpy.core.defchararray.chararray.nonzero
            • numpy.core.defchararray.chararray.put
            • numpy.core.defchararray.chararray.ravel
            • numpy.core.defchararray.chararray.repeat
            • numpy.core.defchararray.chararray.replace
            • numpy.core.defchararray.chararray.reshape
            • numpy.core.defchararray.chararray.resize
            • numpy.core.defchararray.chararray.rfind
            • numpy.core.defchararray.chararray.rindex
            • numpy.core.defchararray.chararray.rjust
            • numpy.core.defchararray.chararray.rsplit
            • numpy.core.defchararray.chararray.rstrip
            • numpy.core.defchararray.chararray.searchsorted
            • numpy.core.defchararray.chararray.setfield
            • numpy.core.defchararray.chararray.setflags
            • numpy.core.defchararray.chararray.sort
            • numpy.core.defchararray.chararray.split
            • numpy.core.defchararray.chararray.splitlines
            • numpy.core.defchararray.chararray.squeeze
            • numpy.core.defchararray.chararray.startswith
            • numpy.core.defchararray.chararray.strip
            • numpy.core.defchararray.chararray.swapaxes
            • numpy.core.defchararray.chararray.swapcase
            • numpy.core.defchararray.chararray.take
            • numpy.core.defchararray.chararray.title
            • numpy.core.defchararray.chararray.tofile
            • numpy.core.defchararray.chararray.tolist
            • numpy.core.defchararray.chararray.tostring
            • numpy.core.defchararray.chararray.translate
            • numpy.core.defchararray.chararray.transpose
            • numpy.core.defchararray.chararray.upper
            • numpy.core.defchararray.chararray.view
            • numpy.core.defchararray.chararray.zfill
      • C-Types Foreign Function Interface (numpy.ctypeslib)
      • Datetime Support Functions
        • Business Day Functions
          • numpy.busdaycalendar
            • numpy.busdaycalendar.weekmask
            • numpy.busdaycalendar.holidays
          • numpy.is_busday
          • numpy.busday_offset
          • numpy.busday_count
      • Data type routines
        • numpy.can_cast
        • numpy.promote_types
        • numpy.min_scalar_type
        • numpy.result_type
        • numpy.common_type
        • numpy.obj2sctype
        • Creating data types
          • numpy.dtype
            • numpy.dtype.base
            • numpy.dtype.descr
            • numpy.dtype.fields
            • numpy.dtype.hasobject
            • numpy.dtype.isalignedstruct
            • numpy.dtype.isbuiltin
            • numpy.dtype.isnative
            • numpy.dtype.metadata
            • numpy.dtype.name
            • numpy.dtype.names
            • numpy.dtype.shape
            • numpy.dtype.str
            • numpy.dtype.subdtype
            • numpy.dtype.newbyteorder
          • numpy.format_parser
        • Data type information
          • numpy.finfo
          • numpy.iinfo
            • numpy.iinfo.min
            • numpy.iinfo.max
          • numpy.MachAr
        • Data type testing
          • numpy.issctype
          • numpy.issubdtype
          • numpy.issubsctype
          • numpy.issubclass
          • numpy.find_common_type
        • Miscellaneous
          • numpy.typename
          • numpy.sctype2char
          • numpy.mintypecode
      • Optionally Scipy-accelerated routines (numpy.dual)
        • Linear algebra
        • FFT
        • Other
      • Mathematical functions with automatic domain (numpy.emath)
      • Floating point error handling
        • Setting and getting error handling
          • numpy.seterr
          • numpy.geterr
          • numpy.seterrcall
          • numpy.geterrcall
          • numpy.errstate
        • Internal functions
          • numpy.seterrobj
          • numpy.geterrobj
      • Discrete Fourier Transform (numpy.fft)
        • Standard FFTs
          • numpy.fft.fft
          • numpy.fft.ifft
          • numpy.fft.fft2
          • numpy.fft.ifft2
          • numpy.fft.fftn
          • numpy.fft.ifftn
        • Real FFTs
          • numpy.fft.rfft
          • numpy.fft.irfft
          • numpy.fft.rfft2
          • numpy.fft.irfft2
          • numpy.fft.rfftn
          • numpy.fft.irfftn
        • Hermitian FFTs
          • numpy.fft.hfft
          • numpy.fft.ihfft
        • Helper routines
          • numpy.fft.fftfreq
          • numpy.fft.rfftfreq
          • numpy.fft.fftshift
          • numpy.fft.ifftshift
        • Background information
        • Implementation details
        • Real and Hermitian transforms
        • Higher dimensions
        • References
        • Examples
      • Financial functions
        • Simple financial functions
          • numpy.fv
          • numpy.pv
          • numpy.npv
          • numpy.pmt
          • numpy.ppmt
          • numpy.ipmt
          • numpy.irr
          • numpy.mirr
          • numpy.nper
          • numpy.rate
      • Functional programming
        • numpy.apply_along_axis
        • numpy.apply_over_axes
        • numpy.vectorize
          • numpy.vectorize.__call__
        • numpy.frompyfunc
        • numpy.piecewise
      • Numpy-specific help functions
        • Finding help
          • numpy.lookfor
        • Reading help
          • numpy.info
          • numpy.source
      • Indexing routines
        • Generating index arrays
          • numpy.c
          • numpy.r
          • numpy.s
          • numpy.nonzero
          • numpy.where
          • numpy.indices
          • numpy.ix
          • numpy.ogrid
          • numpy.ravel_multi_index
          • numpy.unravel_index
          • numpy.diag_indices
          • numpy.diag_indices_from
          • numpy.mask_indices
          • numpy.tril_indices
          • numpy.tril_indices_from
          • numpy.triu_indices
          • numpy.triu_indices_from
        • Indexing-like operations
          • numpy.take
          • numpy.choose
          • numpy.compress
          • numpy.diag
          • numpy.diagonal
          • numpy.select
        • Inserting data into arrays
          • numpy.place
          • numpy.put
          • numpy.putmask
          • numpy.fill_diagonal
        • Iterating over arrays
          • numpy.nditer
            • numpy.nditer.copy
            • numpy.nditer.debug_print
            • numpy.nditer.enable_external_loop
            • numpy.nditer.iternext
            • numpy.nditer.next
            • numpy.nditer.remove_axis
            • numpy.nditer.remove_multi_index
            • numpy.nditer.reset
          • numpy.ndenumerate
            • numpy.ndenumerate.next
          • numpy.ndindex
            • numpy.ndindex.ndincr
            • numpy.ndindex.next
          • numpy.flatiter
            • numpy.flatiter.coords
            • numpy.flatiter.copy
            • numpy.flatiter.next
      • Input and output
        • NPZ files
          • numpy.load
          • numpy.save
          • numpy.savez
          • numpy.savez_compressed
        • Text files
          • numpy.loadtxt
          • numpy.savetxt
          • numpy.genfromtxt
          • numpy.fromregex
          • numpy.fromstring
          • numpy.ndarray.tofile
          • numpy.ndarray.tolist
        • Raw binary files
        • String formatting
          • numpy.array_repr
          • numpy.array_str
        • Memory mapping files
          • numpy.memmap
            • numpy.memmap.flush
        • Text formatting options
          • numpy.set_printoptions
          • numpy.get_printoptions
          • numpy.set_string_function
        • Base-n representations
          • numpy.binary_repr
          • numpy.base_repr
        • Data sources
          • numpy.DataSource
            • numpy.DataSource.abspath
            • numpy.DataSource.exists
            • numpy.DataSource.open
      • Linear algebra (numpy.linalg)
        • Matrix and vector products
          • numpy.dot
          • numpy.vdot
          • numpy.inner
          • numpy.outer
          • numpy.tensordot
          • numpy.einsum
          • numpy.linalg.matrix_power
          • numpy.kron
        • Decompositions
          • numpy.linalg.cholesky
          • numpy.linalg.qr
          • numpy.linalg.svd
        • Matrix eigenvalues
          • numpy.linalg.eig
          • numpy.linalg.eigh
          • numpy.linalg.eigvals
          • numpy.linalg.eigvalsh
        • Norms and other numbers
          • numpy.linalg.norm
          • numpy.linalg.cond
          • numpy.linalg.det
          • numpy.linalg.matrix_rank
          • numpy.linalg.slogdet
          • numpy.trace
        • Solving equations and inverting matrices
          • numpy.linalg.solve
          • numpy.linalg.tensorsolve
          • numpy.linalg.lstsq
          • numpy.linalg.inv
          • numpy.linalg.pinv
          • numpy.linalg.tensorinv
        • Exceptions
          • numpy.linalg.LinAlgError
        • Linear algebra on several matrices at once
      • Logic functions
        • Truth value testing
          • numpy.all
          • numpy.any
        • Array contents
          • numpy.isfinite
          • numpy.isinf
          • numpy.isnan
          • numpy.isneginf
          • numpy.isposinf
        • Array type testing
          • numpy.iscomplex
          • numpy.iscomplexobj
          • numpy.isfortran
          • numpy.isreal
          • numpy.isrealobj
          • numpy.isscalar
        • Logical operations
          • numpy.logical_and
          • numpy.logical_or
          • numpy.logical_not
          • numpy.logical_xor
        • Comparison
          • numpy.allclose
          • numpy.isclose
          • numpy.array_equal
          • numpy.array_equiv
          • numpy.greater
          • numpy.greater_equal
          • numpy.less
          • numpy.less_equal
          • numpy.equal
          • numpy.not_equal
      • Masked array operations
        • Constants
          • numpy.ma.MaskType
        • Creation
          • From existing data
            • numpy.ma.masked_array
            • numpy.ma.array
            • numpy.ma.copy
            • numpy.ma.frombuffer
            • numpy.ma.fromfunction
            • numpy.ma.MaskedArray.copy
          • Ones and zeros
            • numpy.ma.empty
            • numpy.ma.empty_like
            • numpy.ma.masked_all
            • numpy.ma.masked_all_like
            • numpy.ma.ones
            • numpy.ma.zeros
        • Inspecting the array
          • numpy.ma.all
          • numpy.ma.any
          • numpy.ma.count
          • numpy.ma.count_masked
          • numpy.ma.getmask
          • numpy.ma.getmaskarray
          • numpy.ma.getdata
          • numpy.ma.nonzero
          • numpy.ma.shape
          • numpy.ma.size
          • numpy.ma.is_masked
          • numpy.ma.is_mask
          • numpy.ma.MaskedArray.data
          • numpy.ma.MaskedArray.mask
          • numpy.ma.MaskedArray.recordmask
          • numpy.ma.MaskedArray.all
          • numpy.ma.MaskedArray.any
          • numpy.ma.MaskedArray.count
          • numpy.ma.MaskedArray.nonzero
          • numpy.ma.shape
          • numpy.ma.size
        • Manipulating a MaskedArray
          • Changing the shape
            • numpy.ma.ravel
            • numpy.ma.reshape
            • numpy.ma.resize
            • numpy.ma.MaskedArray.flatten
            • numpy.ma.MaskedArray.ravel
            • numpy.ma.MaskedArray.reshape
            • numpy.ma.MaskedArray.resize
          • Modifying axes
            • numpy.ma.swapaxes
            • numpy.ma.transpose
            • numpy.ma.MaskedArray.swapaxes
            • numpy.ma.MaskedArray.transpose
          • Changing the number of dimensions
            • numpy.ma.atleast_1d
            • numpy.ma.atleast_2d
            • numpy.ma.atleast_3d
            • numpy.ma.expand_dims
            • numpy.ma.squeeze
            • numpy.ma.MaskedArray.squeeze
            • numpy.ma.column_stack
            • numpy.ma.concatenate
            • numpy.ma.dstack
            • numpy.ma.hstack
            • numpy.ma.hsplit
            • numpy.ma.mr
            • numpy.ma.row_stack
            • numpy.ma.vstack
          • Joining arrays
            • numpy.ma.column_stack
            • numpy.ma.concatenate
            • numpy.ma.append
            • numpy.ma.dstack
            • numpy.ma.hstack
            • numpy.ma.vstack
        • Operations on masks
          • Creating a mask
            • numpy.ma.make_mask
            • numpy.ma.make_mask_none
            • numpy.ma.mask_or
            • numpy.ma.make_mask_descr
          • Accessing a mask
            • numpy.ma.getmask
            • numpy.ma.getmaskarray
            • numpy.ma.masked_array.mask
          • Finding masked data
            • numpy.ma.flatnotmasked_contiguous
            • numpy.ma.flatnotmasked_edges
            • numpy.ma.notmasked_contiguous
            • numpy.ma.notmasked_edges
          • Modifying a mask
            • numpy.ma.mask_cols
            • numpy.ma.mask_or
            • numpy.ma.mask_rowcols
            • numpy.ma.mask_rows
            • numpy.ma.harden_mask
            • numpy.ma.soften_mask
            • numpy.ma.MaskedArray.harden_mask
            • numpy.ma.MaskedArray.soften_mask
            • numpy.ma.MaskedArray.shrink_mask
            • numpy.ma.MaskedArray.unshare_mask
        • Conversion operations
          • > to a masked array
            • numpy.ma.asarray
            • numpy.ma.asanyarray
            • numpy.ma.fix_invalid
            • numpy.ma.masked_equal
            • numpy.ma.masked_greater
            • numpy.ma.masked_greater_equal
            • numpy.ma.masked_inside
            • numpy.ma.masked_invalid
            • numpy.ma.masked_less
            • numpy.ma.masked_less_equal
            • numpy.ma.masked_not_equal
            • numpy.ma.masked_object
            • numpy.ma.masked_outside
            • numpy.ma.masked_values
            • numpy.ma.masked_where
          • > to a ndarray
            • numpy.ma.compress_cols
            • numpy.ma.compress_rowcols
            • numpy.ma.compress_rows
            • numpy.ma.compressed
            • numpy.ma.filled
            • numpy.ma.MaskedArray.compressed
            • numpy.ma.MaskedArray.filled
          • > to another object
            • numpy.ma.MaskedArray.tofile
            • numpy.ma.MaskedArray.tolist
            • numpy.ma.MaskedArray.torecords
            • numpy.ma.MaskedArray.tobytes
          • Pickling and unpickling
            • numpy.ma.dump
            • numpy.ma.dumps
            • numpy.ma.load
            • numpy.ma.loads
          • Filling a masked array
            • numpy.ma.common_fill_value
            • numpy.ma.default_fill_value
            • numpy.ma.maximum_fill_value
            • numpy.ma.maximum_fill_value
            • numpy.ma.set_fill_value
            • numpy.ma.MaskedArray.get_fill_value
            • numpy.ma.MaskedArray.set_fill_value
            • numpy.ma.MaskedArray.fill_value
        • Masked arrays arithmetics
          • Arithmetics
            • numpy.ma.anom
            • numpy.ma.anomalies
            • numpy.ma.average
            • numpy.ma.conjugate
            • numpy.ma.corrcoef
            • numpy.ma.cov
            • numpy.ma.cumsum
            • numpy.ma.cumprod
            • numpy.ma.mean
            • numpy.ma.median
            • numpy.ma.power
            • numpy.ma.prod
            • numpy.ma.std
            • numpy.ma.sum
            • numpy.ma.var
            • numpy.ma.MaskedArray.anom
            • numpy.ma.MaskedArray.cumprod
            • numpy.ma.MaskedArray.cumsum
            • numpy.ma.MaskedArray.mean
            • numpy.ma.MaskedArray.prod
            • numpy.ma.MaskedArray.std
            • numpy.ma.MaskedArray.sum
            • numpy.ma.MaskedArray.var
          • Minimum/maximum
            • numpy.ma.argmax
            • numpy.ma.argmin
            • numpy.ma.max
            • numpy.ma.min
            • numpy.ma.ptp
            • numpy.ma.MaskedArray.argmax
            • numpy.ma.MaskedArray.argmin
            • numpy.ma.MaskedArray.max
            • numpy.ma.MaskedArray.min
            • numpy.ma.MaskedArray.ptp
          • Sorting
            • numpy.ma.argsort
            • numpy.ma.sort
            • numpy.ma.MaskedArray.argsort
            • numpy.ma.MaskedArray.sort
          • Algebra
            • numpy.ma.diag
            • numpy.ma.dot
            • numpy.ma.identity
            • numpy.ma.inner
            • numpy.ma.innerproduct
            • numpy.ma.outer
            • numpy.ma.outerproduct
            • numpy.ma.trace
            • numpy.ma.transpose
            • numpy.ma.MaskedArray.trace
            • numpy.ma.MaskedArray.transpose
          • Polynomial fit
            • numpy.ma.vander
            • numpy.ma.polyfit
          • Clipping and rounding
            • numpy.ma.around
            • numpy.ma.clip
            • numpy.ma.round
            • numpy.ma.MaskedArray.clip
            • numpy.ma.MaskedArray.round
          • Miscellanea
            • numpy.ma.allequal
            • numpy.ma.allclose
            • numpy.ma.apply_along_axis
            • numpy.ma.arange
            • numpy.ma.choose
            • numpy.ma.ediff1d
            • numpy.ma.indices
            • numpy.ma.where
      • Mathematical functions
        • Trigonometric functions
          • numpy.sin
          • numpy.cos
          • numpy.tan
          • numpy.arcsin
          • numpy.arccos
          • numpy.arctan
          • numpy.hypot
          • numpy.arctan2
          • numpy.degrees
          • numpy.radians
          • numpy.unwrap
          • numpy.deg2rad
          • numpy.rad2deg
        • Hyperbolic functions
          • numpy.sinh
          • numpy.cosh
          • numpy.tanh
          • numpy.arcsinh
          • numpy.arccosh
          • numpy.arctanh
        • Rounding
          • numpy.around
          • numpy.round
          • numpy.rint
          • numpy.fix
          • numpy.floor
          • numpy.ceil
          • numpy.trunc
        • Sums, products, differences
          • numpy.prod
          • numpy.sum
          • numpy.nansum
          • numpy.cumprod
          • numpy.cumsum
          • numpy.diff
          • numpy.ediff1d
          • numpy.gradient
          • numpy.cross
          • numpy.trapz
        • Exponents and logarithms
          • numpy.exp
          • numpy.expm1
          • numpy.exp2
          • numpy.log
          • numpy.log10
          • numpy.log2
          • numpy.log1p
          • numpy.logaddexp
          • numpy.logaddexp2
        • Other special functions
          • numpy.i0
          • numpy.sinc
        • Floating point routines
          • numpy.signbit
          • numpy.copysign
          • numpy.frexp
          • numpy.ldexp
        • Arithmetic operations
          • numpy.add
          • numpy.reciprocal
          • numpy.negative
          • numpy.multiply
          • numpy.divide
          • numpy.power
          • numpy.subtract
          • numpy.true_divide
          • numpy.floor_divide
          • numpy.fmod
          • numpy.mod
          • numpy.modf
          • numpy.remainder
        • Handling complex numbers
          • numpy.angle
          • numpy.real
          • numpy.imag
          • numpy.conj
        • Miscellaneous
          • numpy.convolve
          • numpy.clip
          • numpy.sqrt
          • numpy.square
          • numpy.absolute
          • numpy.fabs
          • numpy.sign
          • numpy.maximum
          • numpy.minimum
          • numpy.fmax
          • numpy.fmin
          • numpy.nan_to_num
          • numpy.real_if_close
          • numpy.interp
      • Matrix library (numpy.matlib)
        • numpy.matlib.empty
        • numpy.matlib.zeros
        • numpy.matlib.ones
        • numpy.matlib.eye
        • numpy.matlib.identity
        • numpy.matlib.repmat
        • numpy.matlib.rand
        • numpy.matlib.randn
      • Miscellaneous routines
        • Buffer objects
          • numpy.getbuffer
          • numpy.newbuffer
        • Performance tuning
          • numpy.alterdot
          • numpy.restoredot
          • numpy.setbufsize
          • numpy.getbufsize
      • Padding Arrays
        • numpy.pad
      • Polynomials
        • Transition notice
          • Polynomial Package
            • Using the Convenience Classes
              • Basics
              • Calculus
              • Other Polynomial Constructors
              • Fitting
            • Polynomial Module (numpy.polynomial.polynomial)
              • Polynomial Class
                • numpy.polynomial.polynomial.Polynomial
                  • numpy.polynomial.polynomial.Polynomial.__call__
                  • numpy.polynomial.polynomial.Polynomial.basis
                  • numpy.polynomial.polynomial.Polynomial.cast
                  • numpy.polynomial.polynomial.Polynomial.convert
                  • numpy.polynomial.polynomial.Polynomial.copy
                  • numpy.polynomial.polynomial.Polynomial.cutdeg
                  • numpy.polynomial.polynomial.Polynomial.degree
                  • numpy.polynomial.polynomial.Polynomial.deriv
                  • numpy.polynomial.polynomial.Polynomial.fit
                  • numpy.polynomial.polynomial.Polynomial.fromroots
                  • numpy.polynomial.polynomial.Polynomial.has_samecoef
                  • numpy.polynomial.polynomial.Polynomial.has_samedomain
                  • numpy.polynomial.polynomial.Polynomial.has_sametype
                  • numpy.polynomial.polynomial.Polynomial.has_samewindow
                  • numpy.polynomial.polynomial.Polynomial.identity
                  • numpy.polynomial.polynomial.Polynomial.integ
                  • numpy.polynomial.polynomial.Polynomial.linspace
                  • numpy.polynomial.polynomial.Polynomial.mapparms
                  • numpy.polynomial.polynomial.Polynomial.roots
                  • numpy.polynomial.polynomial.Polynomial.trim
                  • numpy.polynomial.polynomial.Polynomial.truncate
              • Basics
                • numpy.polynomial.polynomial.polyval
                • numpy.polynomial.polynomial.polyval2d
                • numpy.polynomial.polynomial.polyval3d
                • numpy.polynomial.polynomial.polygrid2d
                • numpy.polynomial.polynomial.polygrid3d
                • numpy.polynomial.polynomial.polyroots
                • numpy.polynomial.polynomial.polyfromroots
              • Fitting
                • numpy.polynomial.polynomial.polyfit
                • numpy.polynomial.polynomial.polyvander
                • numpy.polynomial.polynomial.polyvander2d
                • numpy.polynomial.polynomial.polyvander3d
              • Calculus
                • numpy.polynomial.polynomial.polyder
                • numpy.polynomial.polynomial.polyint
              • Algebra
                • numpy.polynomial.polynomial.polyadd
                • numpy.polynomial.polynomial.polysub
                • numpy.polynomial.polynomial.polymul
                • numpy.polynomial.polynomial.polymulx
                • numpy.polynomial.polynomial.polydiv
                • numpy.polynomial.polynomial.polypow
              • Miscellaneous
                • numpy.polynomial.polynomial.polycompanion
                • numpy.polynomial.polynomial.polydomain
                • numpy.polynomial.polynomial.polyzero
                • numpy.polynomial.polynomial.polyone
                • numpy.polynomial.polynomial.polyx
                • numpy.polynomial.polynomial.polytrim
                • numpy.polynomial.polynomial.polyline
            • Chebyshev Module (numpy.polynomial.chebyshev)
              • Chebyshev Class
                • numpy.polynomial.chebyshev.Chebyshev
                  • numpy.polynomial.chebyshev.Chebyshev.__call__
                  • numpy.polynomial.chebyshev.Chebyshev.basis
                  • numpy.polynomial.chebyshev.Chebyshev.cast
                  • numpy.polynomial.chebyshev.Chebyshev.convert
                  • numpy.polynomial.chebyshev.Chebyshev.copy
                  • numpy.polynomial.chebyshev.Chebyshev.cutdeg
                  • numpy.polynomial.chebyshev.Chebyshev.degree
                  • numpy.polynomial.chebyshev.Chebyshev.deriv
                  • numpy.polynomial.chebyshev.Chebyshev.fit
                  • numpy.polynomial.chebyshev.Chebyshev.fromroots
                  • numpy.polynomial.chebyshev.Chebyshev.has_samecoef
                  • numpy.polynomial.chebyshev.Chebyshev.has_samedomain
                  • numpy.polynomial.chebyshev.Chebyshev.has_sametype
                  • numpy.polynomial.chebyshev.Chebyshev.has_samewindow
                  • numpy.polynomial.chebyshev.Chebyshev.identity
                  • numpy.polynomial.chebyshev.Chebyshev.integ
                  • numpy.polynomial.chebyshev.Chebyshev.linspace
                  • numpy.polynomial.chebyshev.Chebyshev.mapparms
                  • numpy.polynomial.chebyshev.Chebyshev.roots
                  • numpy.polynomial.chebyshev.Chebyshev.trim
                  • numpy.polynomial.chebyshev.Chebyshev.truncate
              • Basics
                • numpy.polynomial.chebyshev.chebval
                • numpy.polynomial.chebyshev.chebval2d
                • numpy.polynomial.chebyshev.chebval3d
                • numpy.polynomial.chebyshev.chebgrid2d
                • numpy.polynomial.chebyshev.chebgrid3d
                • numpy.polynomial.chebyshev.chebroots
                • numpy.polynomial.chebyshev.chebfromroots
              • Fitting
                • numpy.polynomial.chebyshev.chebfit
                • numpy.polynomial.chebyshev.chebvander
                • numpy.polynomial.chebyshev.chebvander2d
                • numpy.polynomial.chebyshev.chebvander3d
              • Calculus
                • numpy.polynomial.chebyshev.chebder
                • numpy.polynomial.chebyshev.chebint
              • Algebra
                • numpy.polynomial.chebyshev.chebadd
                • numpy.polynomial.chebyshev.chebsub
                • numpy.polynomial.chebyshev.chebmul
                • numpy.polynomial.chebyshev.chebmulx
                • numpy.polynomial.chebyshev.chebdiv
                • numpy.polynomial.chebyshev.chebpow
              • Quadrature
                • numpy.polynomial.chebyshev.chebgauss
                • numpy.polynomial.chebyshev.chebweight
              • Miscellaneous
                • numpy.polynomial.chebyshev.chebcompanion
                • numpy.polynomial.chebyshev.chebdomain
                • numpy.polynomial.chebyshev.chebzero
                • numpy.polynomial.chebyshev.chebone
                • numpy.polynomial.chebyshev.chebx
                • numpy.polynomial.chebyshev.chebtrim
                • numpy.polynomial.chebyshev.chebline
                • numpy.polynomial.chebyshev.cheb2poly
                • numpy.polynomial.chebyshev.poly2cheb
            • Legendre Module (numpy.polynomial.legendre)
              • Legendre Class
                • numpy.polynomial.legendre.Legendre
                  • numpy.polynomial.legendre.Legendre.__call__
                  • numpy.polynomial.legendre.Legendre.basis
                  • numpy.polynomial.legendre.Legendre.cast
                  • numpy.polynomial.legendre.Legendre.convert
                  • numpy.polynomial.legendre.Legendre.copy
                  • numpy.polynomial.legendre.Legendre.cutdeg
                  • numpy.polynomial.legendre.Legendre.degree
                  • numpy.polynomial.legendre.Legendre.deriv
                  • numpy.polynomial.legendre.Legendre.fit
                  • numpy.polynomial.legendre.Legendre.fromroots
                  • numpy.polynomial.legendre.Legendre.has_samecoef
                  • numpy.polynomial.legendre.Legendre.has_samedomain
                  • numpy.polynomial.legendre.Legendre.has_sametype
                  • numpy.polynomial.legendre.Legendre.has_samewindow
                  • numpy.polynomial.legendre.Legendre.identity
                  • numpy.polynomial.legendre.Legendre.integ
                  • numpy.polynomial.legendre.Legendre.linspace
                  • numpy.polynomial.legendre.Legendre.mapparms
                  • numpy.polynomial.legendre.Legendre.roots
                  • numpy.polynomial.legendre.Legendre.trim
                  • numpy.polynomial.legendre.Legendre.truncate
              • Basics
                • numpy.polynomial.legendre.legval
                • numpy.polynomial.legendre.legval2d
                • numpy.polynomial.legendre.legval3d
                • numpy.polynomial.legendre.leggrid2d
                • numpy.polynomial.legendre.leggrid3d
                • numpy.polynomial.legendre.legroots
                • numpy.polynomial.legendre.legfromroots
              • Fitting
                • numpy.polynomial.legendre.legfit
                • numpy.polynomial.legendre.legvander
                • numpy.polynomial.legendre.legvander2d
                • numpy.polynomial.legendre.legvander3d
              • Calculus
                • numpy.polynomial.legendre.legder
                • numpy.polynomial.legendre.legint
              • Algebra
                • numpy.polynomial.legendre.legadd
                • numpy.polynomial.legendre.legsub
                • numpy.polynomial.legendre.legmul
                • numpy.polynomial.legendre.legmulx
                • numpy.polynomial.legendre.legdiv
                • numpy.polynomial.legendre.legpow
              • Quadrature
                • numpy.polynomial.legendre.leggauss
                • numpy.polynomial.legendre.legweight
              • Miscellaneous
                • numpy.polynomial.legendre.legcompanion
                • numpy.polynomial.legendre.legdomain
                • numpy.polynomial.legendre.legzero
                • numpy.polynomial.legendre.legone
                • numpy.polynomial.legendre.legx
                • numpy.polynomial.legendre.legtrim
                • numpy.polynomial.legendre.legline
                • numpy.polynomial.legendre.leg2poly
                • numpy.polynomial.legendre.poly2leg
            • Laguerre Module (numpy.polynomial.laguerre)
              • Laguerre Class
                • numpy.polynomial.laguerre.Laguerre
                  • numpy.polynomial.laguerre.Laguerre.__call__
                  • numpy.polynomial.laguerre.Laguerre.basis
                  • numpy.polynomial.laguerre.Laguerre.cast
                  • numpy.polynomial.laguerre.Laguerre.convert
                  • numpy.polynomial.laguerre.Laguerre.copy
                  • numpy.polynomial.laguerre.Laguerre.cutdeg
                  • numpy.polynomial.laguerre.Laguerre.degree
                  • numpy.polynomial.laguerre.Laguerre.deriv
                  • numpy.polynomial.laguerre.Laguerre.fit
                  • numpy.polynomial.laguerre.Laguerre.fromroots
                  • numpy.polynomial.laguerre.Laguerre.has_samecoef
                  • numpy.polynomial.laguerre.Laguerre.has_samedomain
                  • numpy.polynomial.laguerre.Laguerre.has_sametype
                  • numpy.polynomial.laguerre.Laguerre.has_samewindow
                  • numpy.polynomial.laguerre.Laguerre.identity
                  • numpy.polynomial.laguerre.Laguerre.integ
                  • numpy.polynomial.laguerre.Laguerre.linspace
                  • numpy.polynomial.laguerre.Laguerre.mapparms
                  • numpy.polynomial.laguerre.Laguerre.roots
                  • numpy.polynomial.laguerre.Laguerre.trim
                  • numpy.polynomial.laguerre.Laguerre.truncate
              • Basics
                • numpy.polynomial.laguerre.lagval
                • numpy.polynomial.laguerre.lagval2d
                • numpy.polynomial.laguerre.lagval3d
                • numpy.polynomial.laguerre.laggrid2d
                • numpy.polynomial.laguerre.laggrid3d
                • numpy.polynomial.laguerre.lagroots
                • numpy.polynomial.laguerre.lagfromroots
              • Fitting
                • numpy.polynomial.laguerre.lagfit
                • numpy.polynomial.laguerre.lagvander
                • numpy.polynomial.laguerre.lagvander2d
                • numpy.polynomial.laguerre.lagvander3d
              • Calculus
                • numpy.polynomial.laguerre.lagder
                • numpy.polynomial.laguerre.lagint
              • Algebra
                • numpy.polynomial.laguerre.lagadd
                • numpy.polynomial.laguerre.lagsub
                • numpy.polynomial.laguerre.lagmul
                • numpy.polynomial.laguerre.lagmulx
                • numpy.polynomial.laguerre.lagdiv
                • numpy.polynomial.laguerre.lagpow
              • Quadrature
                • numpy.polynomial.laguerre.laggauss
                • numpy.polynomial.laguerre.lagweight
              • Miscellaneous
                • numpy.polynomial.laguerre.lagcompanion
                • numpy.polynomial.laguerre.lagdomain
                • numpy.polynomial.laguerre.lagzero
                • numpy.polynomial.laguerre.lagone
                • numpy.polynomial.laguerre.lagx
                • numpy.polynomial.laguerre.lagtrim
                • numpy.polynomial.laguerre.lagline
                • numpy.polynomial.laguerre.lag2poly
                • numpy.polynomial.laguerre.poly2lag
            • Hermite Module, “Physicists’” (numpy.polynomial.hermite)
              • Hermite Class
                • numpy.polynomial.hermite.Hermite
                  • numpy.polynomial.hermite.Hermite.__call__
                  • numpy.polynomial.hermite.Hermite.basis
                  • numpy.polynomial.hermite.Hermite.cast
                  • numpy.polynomial.hermite.Hermite.convert
                  • numpy.polynomial.hermite.Hermite.copy
                  • numpy.polynomial.hermite.Hermite.cutdeg
                  • numpy.polynomial.hermite.Hermite.degree
                  • numpy.polynomial.hermite.Hermite.deriv
                  • numpy.polynomial.hermite.Hermite.fit
                  • numpy.polynomial.hermite.Hermite.fromroots
                  • numpy.polynomial.hermite.Hermite.has_samecoef
                  • numpy.polynomial.hermite.Hermite.has_samedomain
                  • numpy.polynomial.hermite.Hermite.has_sametype
                  • numpy.polynomial.hermite.Hermite.has_samewindow
                  • numpy.polynomial.hermite.Hermite.identity
                  • numpy.polynomial.hermite.Hermite.integ
                  • numpy.polynomial.hermite.Hermite.linspace
                  • numpy.polynomial.hermite.Hermite.mapparms
                  • numpy.polynomial.hermite.Hermite.roots
                  • numpy.polynomial.hermite.Hermite.trim
                  • numpy.polynomial.hermite.Hermite.truncate
              • Basics
                • numpy.polynomial.hermite.hermval
                • numpy.polynomial.hermite.hermval2d
                • numpy.polynomial.hermite.hermval3d
                • numpy.polynomial.hermite.hermgrid2d
                • numpy.polynomial.hermite.hermgrid3d
                • numpy.polynomial.hermite.hermroots
                • numpy.polynomial.hermite.hermfromroots
              • Fitting
                • numpy.polynomial.hermite.hermfit
                • numpy.polynomial.hermite.hermvander
                • numpy.polynomial.hermite.hermvander2d
                • numpy.polynomial.hermite.hermvander3d
              • Calculus
                • numpy.polynomial.hermite.hermder
                • numpy.polynomial.hermite.hermint
              • Algebra
                • numpy.polynomial.hermite.hermadd
                • numpy.polynomial.hermite.hermsub
                • numpy.polynomial.hermite.hermmul
                • numpy.polynomial.hermite.hermmulx
                • numpy.polynomial.hermite.hermdiv
                • numpy.polynomial.hermite.hermpow
              • Quadrature
                • numpy.polynomial.hermite.hermgauss
                • numpy.polynomial.hermite.hermweight
              • Miscellaneous
                • numpy.polynomial.hermite.hermcompanion
                • numpy.polynomial.hermite.hermdomain
                • numpy.polynomial.hermite.hermzero
                • numpy.polynomial.hermite.hermone
                • numpy.polynomial.hermite.hermx
                • numpy.polynomial.hermite.hermtrim
                • numpy.polynomial.hermite.hermline
                • numpy.polynomial.hermite.herm2poly
                • numpy.polynomial.hermite.poly2herm
            • HermiteE Module, “Probabilists’” (numpy.polynomial.hermite_e)
              • HermiteE Class
                • numpy.polynomial.hermite_e.HermiteE
                  • numpy.polynomial.hermite_e.HermiteE.__call__
                  • numpy.polynomial.hermite_e.HermiteE.basis
                  • numpy.polynomial.hermite_e.HermiteE.cast
                  • numpy.polynomial.hermite_e.HermiteE.convert
                  • numpy.polynomial.hermite_e.HermiteE.copy
                  • numpy.polynomial.hermite_e.HermiteE.cutdeg
                  • numpy.polynomial.hermite_e.HermiteE.degree
                  • numpy.polynomial.hermite_e.HermiteE.deriv
                  • numpy.polynomial.hermite_e.HermiteE.fit
                  • numpy.polynomial.hermite_e.HermiteE.fromroots
                  • numpy.polynomial.hermite_e.HermiteE.has_samecoef
                  • numpy.polynomial.hermite_e.HermiteE.has_samedomain
                  • numpy.polynomial.hermite_e.HermiteE.has_sametype
                  • numpy.polynomial.hermite_e.HermiteE.has_samewindow
                  • numpy.polynomial.hermite_e.HermiteE.identity
                  • numpy.polynomial.hermite_e.HermiteE.integ
                  • numpy.polynomial.hermite_e.HermiteE.linspace
                  • numpy.polynomial.hermite_e.HermiteE.mapparms
                  • numpy.polynomial.hermite_e.HermiteE.roots
                  • numpy.polynomial.hermite_e.HermiteE.trim
                  • numpy.polynomial.hermite_e.HermiteE.truncate
              • Basics
                • numpy.polynomial.hermite_e.hermeval
                • numpy.polynomial.hermite_e.hermeval2d
                • numpy.polynomial.hermite_e.hermeval3d
                • numpy.polynomial.hermite_e.hermegrid2d
                • numpy.polynomial.hermite_e.hermegrid3d
                • numpy.polynomial.hermite_e.hermeroots
                • numpy.polynomial.hermite_e.hermefromroots
              • Fitting
                • numpy.polynomial.hermite_e.hermefit
                • numpy.polynomial.hermite_e.hermevander
                • numpy.polynomial.hermite_e.hermevander2d
                • numpy.polynomial.hermite_e.hermevander3d
              • Calculus
                • numpy.polynomial.hermite_e.hermeder
                • numpy.polynomial.hermite_e.hermeint
              • Algebra
                • numpy.polynomial.hermite_e.hermeadd
                • numpy.polynomial.hermite_e.hermesub
                • numpy.polynomial.hermite_e.hermemul
                • numpy.polynomial.hermite_e.hermemulx
                • numpy.polynomial.hermite_e.hermediv
                • numpy.polynomial.hermite_e.hermepow
              • Quadrature
                • numpy.polynomial.hermite_e.hermegauss
                • numpy.polynomial.hermite_e.hermeweight
              • Miscellaneous
                • numpy.polynomial.hermite_e.hermecompanion
                • numpy.polynomial.hermite_e.hermedomain
                • numpy.polynomial.hermite_e.hermezero
                • numpy.polynomial.hermite_e.hermeone
                • numpy.polynomial.hermite_e.hermex
                • numpy.polynomial.hermite_e.hermetrim
                • numpy.polynomial.hermite_e.hermeline
                • numpy.polynomial.hermite_e.herme2poly
                • numpy.polynomial.hermite_e.poly2herme
          • Poly1d
            • Basics
              • numpy.poly1d
                • numpy.poly1d.__call__
                • numpy.poly1d.deriv
                • numpy.poly1d.integ
              • numpy.polyval
              • numpy.poly
              • numpy.roots
            • Fitting
              • numpy.polyfit
            • Calculus
              • numpy.polyder
              • numpy.polyint
            • Arithmetic
              • numpy.polyadd
              • numpy.polydiv
              • numpy.polymul
              • numpy.polysub
            • Warnings
              • numpy.RankWarning
      • Random sampling (numpy.random)
        • Simple random data
          • numpy.random.rand
          • numpy.random.randn
          • numpy.random.randint
          • numpy.random.random_integers
          • numpy.random.random_sample
          • numpy.random.random
          • numpy.random.ranf
          • numpy.random.sample
          • numpy.random.choice
          • numpy.random.bytes
        • Permutations
          • numpy.random.shuffle
          • numpy.random.permutation
        • Distributions
          • numpy.random.beta
          • numpy.random.binomial
          • numpy.random.chisquare
          • numpy.random.dirichlet
          • numpy.random.exponential
          • numpy.random.f
          • numpy.random.gamma
          • numpy.random.geometric
          • numpy.random.gumbel
          • numpy.random.hypergeometric
          • numpy.random.laplace
          • numpy.random.logistic
          • numpy.random.lognormal
          • numpy.random.logseries
          • numpy.random.multinomial
          • numpy.random.multivariate_normal
          • numpy.random.negative_binomial
          • numpy.random.noncentral_chisquare
          • numpy.random.noncentral_f
          • numpy.random.normal
          • numpy.random.pareto
          • numpy.random.poisson
          • numpy.random.power
          • numpy.random.rayleigh
          • numpy.random.standard_cauchy
          • numpy.random.standard_exponential
          • numpy.random.standard_gamma
          • numpy.random.standard_normal
          • numpy.random.standard_t
          • numpy.random.triangular
          • numpy.random.uniform
          • numpy.random.vonmises
          • numpy.random.wald
          • numpy.random.weibull
          • numpy.random.zipf
        • Random generator
          • numpy.random.RandomState
            • numpy.random.RandomState.beta
            • numpy.random.RandomState.binomial
            • numpy.random.RandomState.bytes
            • numpy.random.RandomState.chisquare
            • numpy.random.RandomState.choice
            • numpy.random.RandomState.dirichlet
            • numpy.random.RandomState.exponential
            • numpy.random.RandomState.f
            • numpy.random.RandomState.gamma
            • numpy.random.RandomState.geometric
            • numpy.random.RandomState.get_state
            • numpy.random.RandomState.gumbel
            • numpy.random.RandomState.hypergeometric
            • numpy.random.RandomState.laplace
            • numpy.random.RandomState.logistic
            • numpy.random.RandomState.lognormal
            • numpy.random.RandomState.logseries
            • numpy.random.RandomState.multinomial
            • numpy.random.RandomState.multivariate_normal
            • numpy.random.RandomState.negative_binomial
            • numpy.random.RandomState.noncentral_chisquare
            • numpy.random.RandomState.noncentral_f
            • numpy.random.RandomState.normal
            • numpy.random.RandomState.pareto
            • numpy.random.RandomState.permutation
            • numpy.random.RandomState.poisson
            • numpy.random.RandomState.power
            • numpy.random.RandomState.rand
            • numpy.random.RandomState.randint
            • numpy.random.RandomState.randn
            • numpy.random.RandomState.random_integers
            • numpy.random.RandomState.random_sample
            • numpy.random.RandomState.rayleigh
            • numpy.random.RandomState.seed
            • numpy.random.RandomState.set_state
            • numpy.random.RandomState.shuffle
            • numpy.random.RandomState.standard_cauchy
            • numpy.random.RandomState.standard_exponential
            • numpy.random.RandomState.standard_gamma
            • numpy.random.RandomState.standard_normal
            • numpy.random.RandomState.standard_t
            • numpy.random.RandomState.tomaxint
            • numpy.random.RandomState.triangular
            • numpy.random.RandomState.uniform
            • numpy.random.RandomState.vonmises
            • numpy.random.RandomState.wald
            • numpy.random.RandomState.weibull
            • numpy.random.RandomState.zipf
          • numpy.random.seed
          • numpy.random.get_state
          • numpy.random.set_state
      • Set routines
        • Making proper sets
          • numpy.unique
        • Boolean operations
          • numpy.in1d
          • numpy.intersect1d
          • numpy.setdiff1d
          • numpy.setxor1d
          • numpy.union1d
      • Sorting, searching, and counting
        • Sorting
          • numpy.sort
          • numpy.lexsort
          • numpy.argsort
          • numpy.ndarray.sort
          • numpy.msort
          • numpy.sort_complex
          • numpy.partition
          • numpy.argpartition
        • Searching
          • numpy.argmax
          • numpy.nanargmax
          • numpy.argmin
          • numpy.nanargmin
          • numpy.argwhere
          • numpy.nonzero
          • numpy.flatnonzero
          • numpy.where
          • numpy.searchsorted
          • numpy.extract
        • Counting
          • numpy.count_nonzero
      • Statistics
        • Order statistics
          • numpy.amin
          • numpy.amax
          • numpy.nanmin
          • numpy.nanmax
          • numpy.ptp
          • numpy.percentile
        • Averages and variances
          • numpy.median
          • numpy.average
          • numpy.mean
          • numpy.std
          • numpy.var
          • numpy.nanmean
          • numpy.nanstd
          • numpy.nanvar
        • Correlating
          • numpy.corrcoef
          • numpy.correlate
          • numpy.cov
        • Histograms
          • numpy.histogram
          • numpy.histogram2d
          • numpy.histogramdd
          • numpy.bincount
          • numpy.digitize
      • Test Support (numpy.testing)
        • Asserts
          • numpy.testing.assert_almost_equal
          • numpy.testing.assert_approx_equal
          • numpy.testing.assert_array_almost_equal
          • numpy.testing.assert_allclose
          • numpy.testing.assert_array_almost_equal_nulp
          • numpy.testing.assert_array_max_ulp
          • numpy.testing.assert_array_equal
          • numpy.testing.assert_array_less
          • numpy.testing.assert_equal
          • numpy.testing.assert_raises
          • numpy.testing.assert_raises_regex
          • numpy.testing.assert_warns
          • numpy.testing.assert_string_equal
        • Decorators
          • numpy.testing.decorators.deprecated
          • numpy.testing.decorators.knownfailureif
          • numpy.testing.decorators.setastest
          • numpy.testing.decorators.skipif
          • numpy.testing.decorators.slow
          • numpy.testing.decorate_methods
        • Test Running
          • numpy.testing.Tester
          • numpy.testing.run_module_suite
          • numpy.testing.rundocs
      • Window functions
        • Various windows
          • numpy.bartlett
          • numpy.blackman
          • numpy.hamming
          • numpy.hanning
          • numpy.kaiser
    • Packaging (numpy.distutils)
      • Modules in numpy.distutils
        • misc_util
          • numpy.distutils.misc_util.get_numpy_include_dirs
          • numpy.distutils.misc_util.dict_append
          • numpy.distutils.misc_util.appendpath
          • numpy.distutils.misc_util.allpath
          • numpy.distutils.misc_util.dot_join
          • numpy.distutils.misc_util.generate_config_py
          • numpy.distutils.misc_util.get_cmd
          • numpy.distutils.misc_util.terminal_has_colors
          • numpy.distutils.misc_util.red_text
          • numpy.distutils.misc_util.green_text
          • numpy.distutils.misc_util.yellow_text
          • numpy.distutils.misc_util.blue_text
          • numpy.distutils.misc_util.cyan_text
          • numpy.distutils.misc_util.cyg2win32
          • numpy.distutils.misc_util.all_strings
          • numpy.distutils.misc_util.has_f_sources
          • numpy.distutils.misc_util.has_cxx_sources
          • numpy.distutils.misc_util.filter_sources
          • numpy.distutils.misc_util.get_dependencies
          • numpy.distutils.misc_util.is_local_src_dir
          • numpy.distutils.misc_util.get_ext_source_files
          • numpy.distutils.misc_util.get_script_files
        • Other modules
          • numpy.distutils.system_info.get_info
          • numpy.distutils.system_info.get_standard_file
          • numpy.distutils.cpuinfo.cpu
          • numpy.distutils.log.set_verbosity
          • numpy.distutils.exec_command
      • Building Installable C libraries
        • npy-pkg-config files
        • Reusing a C library from another package
      • Conversion of .src files
        • Fortran files
          • Named repeat rule
          • Short repeat rule
          • Pre-defined names
        • Other files
    • Numpy C-API
      • Python Types and C-Structures
        • New Python Types Defined
          • PyArray_Type
          • PyArrayDescr_Type
          • PyUFunc_Type
          • PyArrayIter_Type
          • PyArrayMultiIter_Type
          • PyArrayNeighborhoodIter_Type
          • PyArrayFlags_Type
          • ScalarArrayTypes
        • Other C-Structures
          • PyArray_Dims
          • PyArray_Chunk
          • PyArrayInterface
          • Internally used structures
      • System configuration
        • Data type sizes
        • Platform information
      • Data Type API
        • Enumerated Types
        • Defines
          • Max and min values for integers
          • Number of bits in data types
          • Bit-width references to enumerated typenums
          • Integer that can hold a pointer
        • C-type names
          • Boolean
          • (Un)Signed Integer
          • (Complex) Floating point
          • Bit-width names
        • Printf Formatting
      • Array API
        • Array structure and data access
          • Data access
        • Creating arrays
          • From scratch
          • From other objects
        • Dealing with types
          • General check of Python Type
          • Data-type checking
          • Converting data types
          • New data types
          • Special functions for NPY_OBJECT
        • Array flags
          • Basic Array Flags
          • Combinations of array flags
          • Flag-like constants
          • Flag checking
        • Array method alternative API
          • Conversion
          • Shape Manipulation
          • Item selection and manipulation
          • Calculation
        • Functions
          • Array Functions
          • Other functions
        • Auxiliary Data With Object Semantics
        • Array Iterators
        • Broadcasting (multi-iterators)
        • Neighborhood iterator
        • Array Scalars
        • Data-type descriptors
        • Conversion Utilities
          • For use with PyArg_ParseTuple
          • Other conversions
        • Miscellaneous
          • Importing the API
          • Checking the API Version
          • Internal Flexibility
          • Memory management
          • Threading support
            • Group 1
            • Group 2
          • Priority
          • Default buffers
          • Other constants
          • Miscellaneous Macros
          • Enumerated Types
      • Array Iterator API
        • Array Iterator
        • Converting from Previous NumPy Iterators
        • Simple Iteration Example
        • Simple Multi-Iteration Example
        • Iterator Data Types
        • Construction and Destruction
        • Functions For Iteration
      • UFunc API
        • Constants
        • Macros
        • Functions
        • Generic functions
        • Importing the API
      • Generalized Universal Function API
        • Definitions
        • Details of Signature
        • C-API for implementing Elementary Functions
      • Numpy core libraries
        • Numpy core math library
          • Floating point classification
          • Useful math constants
          • Low-level floating point manipulation
          • Complex functions
          • Linking against the core math library in an extension
          • Half-precision functions
      • C API Deprecations
        • Background
        • Deprecation Mechanism NPY_NO_DEPRECATED_API
    • Numpy internals
      • Numpy C Code Explanations
        • Memory model
        • Data-type encapsulation
        • N-D Iterators
        • Broadcasting
        • Array Scalars
        • Advanced (“Fancy”) Indexing
          • Fancy-indexing check
          • Fancy-indexing implementation
            • Creating the mapping object
            • Binding the mapping object
            • Getting (or Setting)
        • Universal Functions
          • Setup
          • Function call
            • One Loop
            • Strided Loop
            • Buffered Loop
          • Final output manipulation
          • Methods
            • Setup
            • Reduce
            • Accumulate
            • Reduceat
      • Internal organization of numpy arrays
      • Multidimensional Array Indexing Order Issues
    • Numpy and SWIG
      • Numpy.i: a SWIG Interface File for NumPy
        • Introduction
        • Using numpy.i
        • Available Typemaps
          • Input Arrays
          • In-Place Arrays
          • Argout Arrays
          • Argout View Arrays
          • Memory Managed Argout View Arrays
          • Output Arrays
          • Other Common Types: bool
          • Other Common Types: complex
        • NumPy Array Scalars and SWIG
          • Why is There a Second File?
        • Helper Functions
          • Macros
          • Routines
        • Beyond the Provided Typemaps
          • A Common Example
          • Other Situations
          • A Final Note
        • Summary
      • Testing the numpy.i Typemaps
        • Introduction
        • Testing Organization
        • Testing Header Files
        • Testing Source Files
        • Testing SWIG Interface Files
        • Testing Python Scripts
    • Acknowledgements
  • F2PY Users Guide and Reference Manual
    • Introduction
      • Three ways to wrap - getting started
        • The quick way
        • The smart way
        • The quick and smart way
      • Signature file
        • Python module block
        • Fortran/C routine signatures
          • Type declarations
          • Statements
          • Attributes
        • Extensions
          • F2PY directives
          • C expressions
          • Multiline blocks
      • Using F2PY bindings in Python
        • Scalar arguments
        • String arguments
        • Array arguments
        • Call-back arguments
          • Resolving arguments to call-back functions
        • Common blocks
        • Fortran 90 module data
          • Allocatable arrays
      • Using F2PY
        • Command f2py
        • Python module f2py2e
      • Using via numpy.distutils
      • Advanced F2PY usages
        • Adding self-written functions to F2PY generated modules
        • Modifying the dictionary of a F2PY generated module
  • Contributing to Numpy
    • Working with NumPy source code
      • Introduction
        • Install git
          • Overview
          • In detail
      • Following the latest source
        • Get the local copy of the code
        • Updating the code
      • Git for development
        • Getting started with Git development
          • Basic Git setup
          • Making your own copy (fork) of NumPy
            • Set up and configure a github account
            • Create your own forked copy of NumPy
          • Set up your fork
            • Overview
            • In detail
              • Clone your fork
              • Linking your repository to the upstream repo
        • Git configuration
          • Overview
          • In detail
            • user.name and user.email
            • Aliases
            • Editor
            • Merging
        • Development workflow
          • Basic workflow
            • Making a new feature branch
            • The editing workflow
              • Overview
              • In more detail
              • Writing the commit message
            • Rebasing on master
              • Recovering from mess-ups
            • Asking for your changes to be merged with the main repo
              • Asking for code review
              • Filing a pull request
            • Pushing changes to the main repo
          • Additional things you might want to do
            • Rewriting commit history
            • Deleting a branch on github
            • Several people sharing a single repository
            • Exploring your repository
            • Backporting
      • git resources
        • Tutorials and summaries
        • Advanced git workflow
        • Manual pages online
  • Numpy Enhancement Proposals
    • Implemented NEPs
      • A Mechanism for Overriding Ufuncs
        • Executive summary
        • Motivation
        • Proposed interface
          • In combination with Python’s binary operations
        • Demo
      • Generalized Universal Functions
        • Definitions
        • Details of Signature
        • C-API for implementing Elementary Functions
      • Optimizing Iterator/UFunc Performance
        • Table of Contents
        • Abstract
        • Motivation
          • Image Compositing Example
        • Improving Cache-Coherency
          • Output Layout Selection Algorithm
        • Coalescing Dimensions
        • Inner Loop Specialization
        • Implementation Details
          • Iterator Rewrite
          • Proposed Iterator Memory Layout
          • Proposed Iterator API
            • Old -> New Iterator API Conversion
            • Iterator Pointer Type
            • Construction and Destruction
            • Functions For Iteration
            • Examples
            • Python Lambda UFunc Example
            • Python Addition Example
            • Image Compositing Example Revisited
            • Image Compositing With NumExpr
      • A Simple File Format for NumPy Arrays
        • Abstract
        • Rationale
        • Use Cases
        • Requirements
        • Format Specification: Version 1.0
        • Conventions
        • Alternatives
        • Implementation
        • References
        • Copyright
    • Other NEPs
      • Missing Data Functionality in NumPy
        • Table of Contents
        • Abstract
        • Definition of Missing Data
          • Unknown Yet Existing Data (NA)
          • Data That Doesn’t Exist Or Is Being Skipped (IGNORE)
        • Implementation Techniques For Missing Values
          • Bit Patterns Signalling Missing Values (bitpattern)
          • Boolean Masks Signalling Missing Values (mask)
        • Glossary of Terms
        • Missing Values as Seen in Python
          • Working With Missing Values
          • Accessing a Boolean Mask
          • Creating NA-Masked Arrays
          • NA-Masks When Constructing From Lists
          • Mask Implementation Details
          • New ndarray Methods
          • Element-wise UFuncs With Missing Values
          • Reduction UFuncs With Missing Values
          • Parameterized NA Data Types
          • Future Expansion to multi-NA Payloads
          • Differences with numpy.ma
          • Boolean Indexing
          • PEP 3118
          • Cython
          • Hard Masks
          • Shared Masks
          • Interaction With Pre-existing C API Usage
            • Numpy Documentation - How to extend NumPy
            • Tutorial From Cython Website
            • Numerical Python - JPL website
        • C Implementation Details
          • Mask Binary Format
        • C Iterator API Changes: Iteration With Masks
          • Iterator Mask Features
          • Iterator NA-array Features
        • Rejected Alternative
          • Parameterized Data Type Which Adds Additional Memory for the NA Flag
        • Acknowledgments
      • Cleaning the math configuration of numpy.core
        • Executive summary
        • Current problems
        • Requirements
        • Proposal
        • Issues
        • License
      • A proposal for adding groupby functionality to NumPy
        • Executive summary
        • Example Use Case
        • Ufunc methods proposed
        • Functions proposed
      • A proposal to build numpy without warning with a big set of warning flags
        • Executive summary
        • Warning flags
        • Kind of warnings
          • unused parameter
          • signed/unsigned comparison
          • half-initialized structures
      • Replacing Trac with a different bug tracker
        • Scenario
          • new release
          • subcomponent maintainer
          • Review, newcoming code
        • Current trac limitation
        • Possible candidates
          • Updated trac + plugins
          • Redmine
          • Roundup
      • Deferred UFunc Evaluation
        • Abstract
        • Motivation
        • Example Python Code
        • Proposed Deferred Evaluation API
          • Error Handling
          • Interaction With UPDATEIFCOPY
          • Other Implementation Details
          • Further Optimization
      • Structured array extensions
      • A proposal for implementing some date/time types in NumPy
        • Executive summary
        • Types proposed
        • Time units
        • datetime64
          • Building a datetime64 dtype
          • Setting and getting values
          • Comparisons
          • Compatibility issues
        • timedelta64
          • Building a timedelta64 dtype
          • Setting and getting values
          • Comparisons
          • Compatibility issues
        • Examples of use
        • Operating with date/time arrays
          • datetime64 vs datetime64
            • Casting rules
          • datetime64 vs timedelta64
            • Casting rules
          • timedelta64 vs timedelta64
            • Casting rules
        • dtype vs time units conversions
        • Necessary changes to NumPy
          • Addition of metadata to dtypes
          • Ufunc interface extension
          • Array Intervace Extensions
        • Final considerations
          • Why the fractional time and events: [3Y/12]//50
          • Why the origin metadata disappeared
          • Operations with mixed time units
      • A (third) proposal for implementing some date/time types in NumPy
        • Executive summary
        • Types proposed
          • datetime64
            • Time units
            • Building a datetime64 dtype
            • Setting and getting values
            • Comparisons
            • Compatibility issues
          • timedelta64
            • Time units
            • Building a timedelta64 dtype
            • Setting and getting values
            • Comparisons
            • Compatibility issues
        • Examples of use
        • Operating with date/time arrays
          • datetime64 vs datetime64
            • Casting rules
          • datetime64 vs timedelta64
            • Casting rules
          • timedelta64 vs timedelta64
            • Casting rules
        • dtype vs time units conversions
        • Final considerations
          • Why the origin metadata disappeared
          • Operations with mixed time units
          • Why there is not a quarter time unit?
  • Release Notes
    • NumPy 1.10.0 Release Notes
      • Highlights
      • Dropped Support
      • Future Changes
      • Compatibility notes
      • New Features
        • np.cbrt to compute cube root for real floats
        • numpy.distutils now allows parallel compilation
      • Improvements
        • np.digitize using binary search
        • np.poly now casts integer inputs to float
        • np.interp can now be used with periodic functions
      • Changes
        • dotblas functionality moved to multiarray
        • stricter check of gufunc signature compliance
      • Deprecations
        • SafeEval
        • alterdot, restoredot
        • pkgload, PackageLoader
    • NumPy 1.9.1 Release Notes
      • Issues fixed
    • NumPy 1.9.0 Release Notes
      • Highlights
      • Dropped Support
      • Future Changes
      • Compatibility notes
        • The diagonal and diag functions return readonly views.
        • Special scalar float values don’t cause upcast to double anymore
        • Percentile output changes
        • ndarray.tofile exception type
        • Invalid fill value exceptions
        • Polynomial Classes no longer derived from PolyBase
        • Using numpy.random.binomial may change the RNG state vs. numpy < 1.9
        • Random seed enforced to be a 32 bit unsigned integer
        • Argmin and argmax out argument
        • Einsum
        • Indexing
        • Non-integer reduction axis indexes are deprecated
        • promote_types and string dtype
        • can_cast and string dtype
        • astype and string dtype
        • npyio.recfromcsv keyword arguments change
        • The doc/swig directory moved
        • The npy_3kcompat.h header changed
        • Negative indices in C-Api sq_item and sq_ass_item sequence methods
        • NDIter
        • zeros_like for string dtypes now returns empty strings
      • New Features
        • Percentile supports more interpolation options
        • Generalized axis support for median and percentile
        • Dtype parameter added to np.linspace and np.logspace
        • More general np.triu and np.tril broadcasting
        • tobytes alias for tostring method
        • Build system
        • Compatibility to python numbers module
        • increasing parameter added to np.vander
        • unique_counts parameter added to np.unique
        • Support for median and percentile in nanfunctions
        • NumpyVersion class added
        • Allow saving arrays with large number of named columns
        • Full broadcasting support for np.cross
      • Improvements
        • Better numerical stability for sum in some cases
        • Percentile implemented in terms of np.partition
        • Performance improvement for np.array
        • Performance improvement for np.searchsorted
        • Optional reduced verbosity for np.distutils
        • Covariance check in np.random.multivariate_normal
        • Polynomial Classes no longer template based
        • More GIL releases
        • MaskedArray support for more complicated base classes
        • C-API
      • Deprecations
        • Non-integer scalars for sequence repetition
        • select input deprecations
        • rank function
        • Object array equality comparisons
        • C-API
    • NumPy 1.8.2 Release Notes
      • Issues fixed
    • NumPy 1.8.1 Release Notes
      • Issues fixed
      • Changes
        • NDIter
        • Optional reduced verbosity for np.distutils
      • Deprecations
        • C-API
    • NumPy 1.8.0 Release Notes
      • Highlights
      • Dropped Support
      • Future Changes
      • Compatibility notes
        • NPY_RELAXED_STRIDES_CHECKING
        • Binary operations with non-arrays as second argument
        • Function median used with overwrite_input only partially sorts array
        • Fix to financial.npv
        • Runtime warnings when comparing NaN numbers
      • New Features
        • Support for linear algebra on stacked arrays
        • In place fancy indexing for ufuncs
        • New functions partition and argpartition
        • New functions nanmean, nanvar and nanstd
        • New functions full and full_like
        • IO compatibility with large files
        • Building against OpenBLAS
        • New constant
        • New modes for qr
        • New invert argument to in1d
        • Advanced indexing using np.newaxis
        • C-API
        • runtests.py
      • Improvements
        • IO performance improvements
        • Performance improvements to pad
        • Performance improvements to isnan, isinf, isfinite and byteswap
        • Performance improvements via SSE2 vectorization
        • Performance improvements to median
        • Overrideable operand flags in ufunc C-API
      • Changes
        • General
        • C-API Array Additions
        • C-API Ufunc Additions
        • C-API Developer Improvements
      • Deprecations
        • General
      • Authors
    • NumPy 1.7.2 Release Notes
      • Issues fixed
    • NumPy 1.7.1 Release Notes
      • Issues fixed
    • NumPy 1.7.0 Release Notes
      • Highlights
      • Compatibility notes
      • New features
        • Reduction UFuncs Generalize axis= Parameter
        • Reduction UFuncs New keepdims= Parameter
        • Datetime support
        • Custom formatter for printing arrays
        • New function numpy.random.choice
        • New function isclose
        • Preliminary multi-dimensional support in the polynomial package
        • Ability to pad rank-n arrays
        • New argument to searchsorted
        • Build system
        • C API
      • Changes
        • General
        • Casting Rules
      • Deprecations
        • General
        • C-API
    • NumPy 1.6.2 Release Notes
      • Issues fixed
        • numpy.core
        • numpy.lib
        • numpy.distutils
        • numpy.random
      • Changes
        • numpy.f2py
        • numpy.poly
    • NumPy 1.6.1 Release Notes
      • Issues Fixed
    • NumPy 1.6.0 Release Notes
      • Highlights
      • New features
        • New 16-bit floating point type
        • New iterator
        • Legendre, Laguerre, Hermite, HermiteE polynomials in numpy.polynomial
        • Fortran assumed shape array and size function support in numpy.f2py
        • Other new functions
      • Changes
        • default error handling
        • numpy.distutils
        • numpy.testing
        • C API
      • Deprecated features
      • Removed features
        • numpy.fft
        • numpy.memmap
        • numpy.lib
        • numpy.ma
        • numpy.distutils
    • NumPy 1.5.0 Release Notes
      • Highlights
        • Python 3 compatibility
        • PEP 3118 compatibility
      • New features
        • Warning on casting complex to real
        • Dot method for ndarrays
        • linalg.slogdet function
        • new header
      • Changes
        • polynomial.polynomial
        • polynomial.chebyshev
        • histogram
        • correlate
    • NumPy 1.4.0 Release Notes
      • Highlights
      • New features
        • Extended array wrapping mechanism for ufuncs
        • Automatic detection of forward incompatibilities
        • New iterators
        • New polynomial support
        • New C API
        • New ufuncs
        • New defines
        • Testing
        • Reusing npymath
        • Improved set operations
      • Improvements
      • Deprecations
      • Internal changes
        • Use C99 complex functions when available
        • split multiarray and umath source code
        • Separate compilation
        • Separate core math library
    • NumPy 1.3.0 Release Notes
      • Highlights
        • Python 2.6 support
        • Generalized ufuncs
        • Experimental Windows 64 bits support
      • New features
        • Formatting issues
        • Nan handling in max/min
        • Nan handling in sign
        • New ufuncs
        • Masked arrays
        • gfortran support on windows
        • Arch option for windows binary
      • Deprecated features
        • Histogram
      • Documentation changes
      • New C API
        • Multiarray API
        • Ufunc API
        • New defines
        • Portable NAN, INFINITY, etc...
      • Internal changes
        • numpy.core math configuration revamp
        • umath refactor
        • Improvements to build warnings
        • Separate core math library
        • CPU arch detection
  • About NumPy
    • NumPy community
  • About this documentation
    • Conventions
  • Reporting bugs
  • Numpy License
  • Glossary
    • Jargon


Index

_ | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | Y | Z

_

__abs__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__add__ (numpy.ndarray attribute)
__add__() (numpy.ma.MaskedArray method)
__and__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__array__() (numpy.generic method)
(numpy.ma.MaskedArray method)
(numpy.ndarray method)
__array_finalize__ (ndarray attribute)
__array_interface__ (built-in variable)
(numpy.generic attribute)
__array_priority__ (ndarray attribute)
(numpy.generic attribute)
(numpy.ma.MaskedArray attribute)
__array_struct__ (C variable)
(numpy.generic attribute)
__array_wrap__ (ndarray attribute)
__array_wrap__() (numpy.generic method)
(numpy.ma.MaskedArray method)
(numpy.ndarray method)
__call__() (numpy.poly1d method)
(numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
(numpy.vectorize method)
__contains__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__copy__() (numpy.ma.MaskedArray method)
(numpy.ndarray method)
__deepcopy__() (numpy.ma.MaskedArray method)
(numpy.ndarray method)
__delitem__ (numpy.ma.MaskedArray attribute)
__div__ (numpy.ndarray attribute)
__div__() (numpy.ma.MaskedArray method)
__divmod__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__eq__ (numpy.ndarray attribute)
__eq__() (numpy.ma.MaskedArray method)
__float__ (numpy.ndarray attribute)
__float__() (numpy.ma.MaskedArray method)
__floordiv__ (numpy.ndarray attribute)
__floordiv__() (numpy.ma.MaskedArray method)
__ge__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__getitem__ (numpy.ndarray attribute)
__getitem__() (numpy.ma.MaskedArray method)
__getslice__ (numpy.ndarray attribute)
__getslice__() (numpy.ma.MaskedArray method)
__getstate__() (numpy.ma.MaskedArray method)
__gt__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__hex__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__iadd__ (numpy.ndarray attribute)
__iadd__() (numpy.ma.MaskedArray method)
__iand__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__idiv__ (numpy.ndarray attribute)
__idiv__() (numpy.ma.MaskedArray method)
__ifloordiv__ (numpy.ndarray attribute)
__ifloordiv__() (numpy.ma.MaskedArray method)
__ilshift__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__imod__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__imul__ (numpy.ndarray attribute)
__imul__() (numpy.ma.MaskedArray method)
__int__ (numpy.ndarray attribute)
__int__() (numpy.ma.MaskedArray method)
__invert__ (numpy.ndarray attribute)
__ior__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__ipow__ (numpy.ndarray attribute)
__ipow__() (numpy.ma.MaskedArray method)
__irshift__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__isub__ (numpy.ndarray attribute)
__isub__() (numpy.ma.MaskedArray method)
__itruediv__ (numpy.ndarray attribute)
__itruediv__() (numpy.ma.MaskedArray method)
__ixor__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__le__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__len__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__long__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__lshift__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__lt__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__mod__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__mul__ (numpy.ndarray attribute)
__mul__() (numpy.ma.MaskedArray method)
__ne__ (numpy.ndarray attribute)
__ne__() (numpy.ma.MaskedArray method)
__neg__ (numpy.ndarray attribute)
__new__() (numpy.ma.MaskedArray static method)
(numpy.ndarray static method)
__nonzero__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__oct__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__or__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__pos__ (numpy.ndarray attribute)
__pow__ (numpy.ndarray attribute)
__pow__() (numpy.ma.MaskedArray method)
__radd__() (numpy.ma.MaskedArray method)
__rand__ (numpy.ma.MaskedArray attribute)
__rdiv__ (numpy.ma.MaskedArray attribute)
__rdivmod__ (numpy.ma.MaskedArray attribute)
__reduce__() (numpy.dtype method)
(numpy.generic method)
(numpy.ma.MaskedArray method)
(numpy.ndarray method)
__repr__ (numpy.ndarray attribute)
__repr__() (numpy.ma.MaskedArray method)
__rfloordiv__() (numpy.ma.MaskedArray method)
__rlshift__ (numpy.ma.MaskedArray attribute)
__rmod__ (numpy.ma.MaskedArray attribute)
__rmul__() (numpy.ma.MaskedArray method)
__ror__ (numpy.ma.MaskedArray attribute)
__rpow__() (numpy.ma.MaskedArray method)
__rrshift__ (numpy.ma.MaskedArray attribute)
__rshift__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)
__rsub__() (numpy.ma.MaskedArray method)
__rtruediv__() (numpy.ma.MaskedArray method)
__rxor__ (numpy.ma.MaskedArray attribute)
__setitem__ (numpy.ndarray attribute)
__setitem__() (numpy.ma.MaskedArray method)
__setmask__() (numpy.ma.MaskedArray method)
__setslice__ (numpy.ndarray attribute)
__setslice__() (numpy.ma.MaskedArray method)
__setstate__() (numpy.dtype method)
(numpy.generic method)
(numpy.ma.MaskedArray method)
(numpy.ndarray method)
__str__ (numpy.ndarray attribute)
__str__() (numpy.ma.MaskedArray method)
__sub__ (numpy.ndarray attribute)
__sub__() (numpy.ma.MaskedArray method)
__truediv__ (numpy.ndarray attribute)
__truediv__() (numpy.ma.MaskedArray method)
__xor__ (numpy.ma.MaskedArray attribute)
(numpy.ndarray attribute)

A

A (numpy.matrix attribute)
A1 (numpy.matrix attribute)
absolute (in module numpy)
abspath() (numpy.DataSource method)
accumulate
ufunc methods
accumulate() (numpy.ufunc method)
add (in module numpy)
add() (in module numpy.core.defchararray)
add_data_dir() (numpy.distutils.misc_util.Configuration method)
add_data_files() (numpy.distutils.misc_util.Configuration method)
add_extension() (numpy.distutils.misc_util.Configuration method)
add_headers() (numpy.distutils.misc_util.Configuration method)
add_include_dirs() (numpy.distutils.misc_util.Configuration method)
add_installed_library() (numpy.distutils.misc_util.Configuration method)
add_library() (numpy.distutils.misc_util.Configuration method)
add_npy_pkg_config() (numpy.distutils.misc_util.Configuration method)
add_scripts() (numpy.distutils.misc_util.Configuration method)
add_subpackage() (numpy.distutils.misc_util.Configuration method)
adding new
dtype
ufunc, [1], [2], [3], [4]
aligned
alignment (numpy.dtype attribute)
all (in module numpy.ma)
all() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
all_strings() (in module numpy.distutils.misc_util)
allclose() (in module numpy)
(in module numpy.ma)
allequal() (in module numpy.ma)
allpath() (in module numpy.distutils.misc_util)
along an axis
alterdot() (in module numpy)
amax() (in module numpy)
amin() (in module numpy)
angle() (in module numpy)
anom (in module numpy.ma)
anom() (numpy.ma.masked_array method)
(numpy.ma.MaskedArray method)
anomalies (in module numpy.ma)
any (in module numpy.ma)
any() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
append() (in module numpy)
(in module numpy.ma)
appendpath() (in module numpy.distutils.misc_util)
apply_along_axis() (in module numpy)
(in module numpy.ma)
apply_over_axes() (in module numpy)
arange (in module numpy.ma)
arange() (in module numpy)
arccos (in module numpy)
arccosh (in module numpy)
arcsin (in module numpy)
arcsinh (in module numpy)
arctan (in module numpy)
arctan2 (in module numpy)
arctanh (in module numpy)
argmax() (in module numpy)
(in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
argmin() (in module numpy)
(in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
argpartition() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
argsort() (in module numpy)
(in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
argwhere() (in module numpy)
arithmetic, [1]
around (in module numpy.ma)
around() (in module numpy)
array
C-API
interface
protocol
array iterator, [1], [2], [3]
array scalars
array() (in module numpy)
(in module numpy.core.defchararray)
(in module numpy.core.records)
(in module numpy.ma)
array_equal() (in module numpy)
array_equiv() (in module numpy)
array_like
array_repr() (in module numpy)
array_split() (in module numpy)
array_str() (in module numpy)
as_array() (in module numpy.ctypeslib)
as_ctypes() (in module numpy.ctypeslib)
asanyarray() (in module numpy)
(in module numpy.ma)
asarray() (in module numpy)
(in module numpy.core.defchararray)
(in module numpy.ma)
asarray_chkfinite() (in module numpy)
ascontiguousarray() (in module numpy)
asfarray() (in module numpy)
asfortranarray() (in module numpy)
asmatrix() (in module numpy)
asscalar() (in module numpy)
assert_allclose() (in module numpy.testing)
assert_almost_equal() (in module numpy.testing)
assert_approx_equal() (in module numpy.testing)
assert_array_almost_equal() (in module numpy.testing)
assert_array_almost_equal_nulp() (in module numpy.testing)
assert_array_equal() (in module numpy.testing)
assert_array_less() (in module numpy.testing)
assert_array_max_ulp() (in module numpy.testing)
assert_equal() (in module numpy.testing)
assert_raises() (in module numpy.testing)
assert_raises_regex() (in module numpy.testing)
assert_string_equal() (in module numpy.testing)
assert_warns() (in module numpy.testing)
astype() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.lib.user_array.container method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
at() (numpy.ufunc method)
atleast_1d (in module numpy.ma)
atleast_1d() (in module numpy)
atleast_2d (in module numpy.ma)
atleast_2d() (in module numpy)
atleast_3d (in module numpy.ma)
atleast_3d() (in module numpy)
attribute
attributes
ufunc
average() (in module numpy)
(in module numpy.ma)
axis

B

bartlett() (in module numpy)
base
(numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.dtype attribute)
(numpy.flatiter attribute)
(numpy.generic attribute)
(numpy.ma.MaskType attribute)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.recarray attribute)
(numpy.record attribute)
base_repr() (in module numpy)
baseclass (numpy.ma.masked_array attribute)
(numpy.ma.MaskedArray attribute)
basis() (numpy.polynomial.chebyshev.Chebyshev class method)
(numpy.polynomial.hermite.Hermite class method)
(numpy.polynomial.hermite_e.HermiteE class method)
(numpy.polynomial.laguerre.Laguerre class method)
(numpy.polynomial.legendre.Legendre class method)
(numpy.polynomial.polynomial.Polynomial class method)
bench() (numpy.testing.Tester method)
beta() (in module numpy.random)
(numpy.random.RandomState method)
binary_repr() (in module numpy)
bincount() (in module numpy)
binomial() (in module numpy.random)
(numpy.random.RandomState method)
bitwise_and (in module numpy)
bitwise_or (in module numpy)
bitwise_xor (in module numpy)
blackman() (in module numpy)
BLAS
blue_text() (in module numpy.distutils.misc_util)
bmat() (in module numpy)
Boost.Python
broadcast
(class in numpy)
broadcast_arrays() (in module numpy)
broadcastable
broadcasting, [1], [2]
buffers
busday_count() (in module numpy)
busday_offset() (in module numpy)
busdaycalendar (class in numpy)
byteorder (numpy.dtype attribute)
bytes() (in module numpy.random)
(numpy.random.RandomState method)
byteswap() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.lib.user_array.container method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)

C

C order
C-API
array
iterator, [1], [2]
ndarray, [1]
ufunc, [1]
C-order
c_ (in module numpy)
can_cast() (in module numpy)
capitalize() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
cast() (numpy.polynomial.chebyshev.Chebyshev class method)
(numpy.polynomial.hermite.Hermite class method)
(numpy.polynomial.hermite_e.HermiteE class method)
(numpy.polynomial.laguerre.Laguerre class method)
(numpy.polynomial.legendre.Legendre class method)
(numpy.polynomial.polynomial.Polynomial class method)
casting rules
ufunc
ceil (in module numpy)
center() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
char (numpy.dtype attribute)
character arrays
chararray (class in numpy)
(class in numpy.core.defchararray)
cheb2poly() (in module numpy.polynomial.chebyshev)
chebadd() (in module numpy.polynomial.chebyshev)
chebcompanion() (in module numpy.polynomial.chebyshev)
chebder() (in module numpy.polynomial.chebyshev)
chebdiv() (in module numpy.polynomial.chebyshev)
chebdomain (in module numpy.polynomial.chebyshev)
chebfit() (in module numpy.polynomial.chebyshev)
chebfromroots() (in module numpy.polynomial.chebyshev)
chebgauss() (in module numpy.polynomial.chebyshev)
chebgrid2d() (in module numpy.polynomial.chebyshev)
chebgrid3d() (in module numpy.polynomial.chebyshev)
chebint() (in module numpy.polynomial.chebyshev)
chebline() (in module numpy.polynomial.chebyshev)
chebmul() (in module numpy.polynomial.chebyshev)
chebmulx() (in module numpy.polynomial.chebyshev)
chebone (in module numpy.polynomial.chebyshev)
chebpow() (in module numpy.polynomial.chebyshev)
chebroots() (in module numpy.polynomial.chebyshev)
chebsub() (in module numpy.polynomial.chebyshev)
chebtrim() (in module numpy.polynomial.chebyshev)
chebval() (in module numpy.polynomial.chebyshev)
chebval2d() (in module numpy.polynomial.chebyshev)
chebval3d() (in module numpy.polynomial.chebyshev)
chebvander() (in module numpy.polynomial.chebyshev)
chebvander2d() (in module numpy.polynomial.chebyshev)
chebvander3d() (in module numpy.polynomial.chebyshev)
chebweight() (in module numpy.polynomial.chebyshev)
chebx (in module numpy.polynomial.chebyshev)
Chebyshev (class in numpy.polynomial.chebyshev)
chebzero (in module numpy.polynomial.chebyshev)
chisquare() (in module numpy.random)
(numpy.random.RandomState method)
choice() (in module numpy.random)
(numpy.random.RandomState method)
cholesky() (in module numpy.linalg)
choose() (in module numpy)
(in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
class.__array__() (in module numpy)
class.__array_finalize__() (in module numpy)
class.__array_prepare__() (in module numpy)
class.__array_priority__ (in module numpy)
class.__array_wrap__() (in module numpy)
class.__numpy_ufunc__() (in module numpy)
clip (numpy.ma.masked_array attribute)
(numpy.ma.MaskedArray attribute)
clip() (in module numpy)
(in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
code generation
coeffs (numpy.poly1d attribute)
column-major, [1]
column_stack (in module numpy.ma)
column_stack() (in module numpy)
common_fill_value() (in module numpy.ma)
common_type() (in module numpy)
comparison, [1]
compress() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
compress_cols() (in module numpy.ma)
compress_rowcols() (in module numpy.ma)
compress_rows() (in module numpy.ma)
compressed() (in module numpy.ma)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
concatenate() (in module numpy)
(in module numpy.ma)
cond() (in module numpy.linalg)
Configuration (class in numpy.distutils.misc_util)
conj (in module numpy)
conj() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
conjugate (in module numpy.ma)
conjugate() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
construction
from None, dtype
from dict, dtype
from dtype, dtype
from list, dtype
from string, dtype
from tuple, dtype
from type, dtype
container (class in numpy.lib.user_array)
container class
contiguous
convert() (numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
convolve() (in module numpy)
coords (numpy.flatiter attribute)
copy (in module numpy.ma)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
copy() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.flatiter method)
(numpy.generic method)
(numpy.lib.user_array.container method)
(numpy.ma.MaskType method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.nditer method)
(numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
(numpy.recarray method)
(numpy.record method)
copysign (in module numpy)
copyto() (in module numpy)
corrcoef() (in module numpy)
(in module numpy.ma)
correlate() (in module numpy)
cos (in module numpy)
cosh (in module numpy)
count() (in module numpy.core.defchararray)
(in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
count_masked() (in module numpy.ma)
count_nonzero() (in module numpy)
cov() (in module numpy)
(in module numpy.ma)
cpu (in module numpy.distutils.cpuinfo)
cross() (in module numpy)
ctypes, [1]
(numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.recarray attribute)
ctypes_load_library() (in module numpy.ctypeslib)
cumprod (in module numpy.ma)
cumprod() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
cumsum (in module numpy.ma)
cumsum() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
cutdeg() (numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
cyan_text() (in module numpy.distutils.misc_util)
cyg2win32() (in module numpy.distutils.misc_util)
cython, [1]

D

data (numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.generic attribute)
(numpy.ma.MaskType attribute)
(numpy.ma.MaskedArray attribute), [1]
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.recarray attribute)
(numpy.record attribute)
DataSource (class in numpy)
debug_print() (numpy.nditer method)
decode() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
decorate_methods() (in module numpy.testing)
decorator
default_fill_value() (in module numpy.ma)
deg2rad (in module numpy)
degree() (numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
degrees (in module numpy)
delete() (in module numpy)
deprecated() (in module numpy.testing.decorators)
deriv() (numpy.poly1d method)
(numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
descr (numpy.dtype attribute)
det() (in module numpy.linalg)
diag() (in module numpy)
(in module numpy.ma)
diag_indices() (in module numpy)
diag_indices_from() (in module numpy)
diagflat() (in module numpy)
diagonal (numpy.ma.masked_array attribute)
(numpy.ma.MaskedArray attribute)
diagonal() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
dict_append() (in module numpy.distutils.misc_util)
dictionary
diff() (in module numpy)
digitize() (in module numpy)
dirichlet() (in module numpy.random)
(numpy.random.RandomState method)
distutils
divide (in module numpy)
domain (numpy.polynomial.chebyshev.Chebyshev attribute)
(numpy.polynomial.hermite.Hermite attribute)
(numpy.polynomial.hermite_e.HermiteE attribute)
(numpy.polynomial.laguerre.Laguerre attribute)
(numpy.polynomial.legendre.Legendre attribute)
(numpy.polynomial.polynomial.Polynomial attribute)
dot() (in module numpy)
(in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
dot_join() (in module numpy.distutils.misc_util)
dsplit() (in module numpy)
dstack (in module numpy.ma)
dstack() (in module numpy)
dtype
adding new
construction from None
construction from dict
construction from dtype
construction from list
construction from string
construction from tuple
construction from type
field
record
scalar
sub-array, [1]
dtype (class in numpy)
(numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.generic attribute)
(numpy.ma.MaskType attribute)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.recarray attribute)
(numpy.record attribute)
dtypes (numpy.nditer attribute)
dump() (in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
dumps() (in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)

E

ediff1d() (in module numpy)
(in module numpy.ma)
eig() (in module numpy.linalg)
eigh() (in module numpy.linalg)
eigvals() (in module numpy.linalg)
eigvalsh() (in module numpy.linalg)
einsum() (in module numpy)
ellipsis
empty (in module numpy.ma)
empty() (in module numpy)
(in module numpy.matlib)
empty_like (in module numpy.ma)
empty_like() (in module numpy)
enable_external_loop() (numpy.nditer method)
encode() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
endswith() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
equal (in module numpy)
equal() (in module numpy.core.defchararray)
error handling
errstate (class in numpy)
excludes (numpy.testing.Tester attribute)
exists() (numpy.DataSource method)
exp (in module numpy)
exp2 (in module numpy)
expand_dims() (in module numpy)
(in module numpy.ma)
expandtabs() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
expm1 (in module numpy)
exponential() (in module numpy.random)
(numpy.random.RandomState method)
extension module, [1]
extract() (in module numpy)
eye() (in module numpy)
(in module numpy.matlib)

F

f() (in module numpy.random)
(numpy.random.RandomState method)
f2py, [1]
fabs (in module numpy)
fft() (in module numpy.fft)
fft2() (in module numpy.fft)
fftfreq() (in module numpy.fft)
fftn() (in module numpy.fft)
fftshift() (in module numpy.fft)
field
dtype
field() (numpy.recarray method)
fields (numpy.dtype attribute)
fill() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
fill_diagonal() (in module numpy)
fill_value (numpy.ma.masked_array attribute)
(numpy.ma.MaskedArray attribute), [1]
filled() (in module numpy.ma)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
filter_sources() (in module numpy.distutils.misc_util)
find() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
find_common_type() (in module numpy)
finfo (class in numpy)
finished (numpy.nditer attribute)
fit() (numpy.polynomial.chebyshev.Chebyshev class method)
(numpy.polynomial.hermite.Hermite class method)
(numpy.polynomial.hermite_e.HermiteE class method)
(numpy.polynomial.laguerre.Laguerre class method)
(numpy.polynomial.legendre.Legendre class method)
(numpy.polynomial.polynomial.Polynomial class method)
fix() (in module numpy)
fix_invalid() (in module numpy.ma)
flags (numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.dtype attribute)
(numpy.generic attribute)
(numpy.ma.MaskType attribute)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.recarray attribute)
(numpy.record attribute)
flat (numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.generic attribute)
(numpy.ma.MaskType attribute)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.recarray attribute)
(numpy.record attribute)
flatiter (class in numpy)
flatnonzero() (in module numpy)
flatnotmasked_contiguous() (in module numpy.ma)
flatnotmasked_edges() (in module numpy.ma)
flatten (numpy.ma.masked_array attribute)
(numpy.ma.MaskedArray attribute)
flatten() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
flattened
fliplr() (in module numpy)
flipud() (in module numpy)
floor (in module numpy)
floor_divide (in module numpy)
flush() (numpy.memmap method)
fmax (in module numpy)
fmin (in module numpy)
fmod (in module numpy)
format_parser (class in numpy)
Fortran order
Fortran-order
frexp (in module numpy)
from dict
dtype construction
from dtype
dtype construction
from list
dtype construction
from None
dtype construction
from string
dtype construction
from tuple
dtype construction
from type
dtype construction
fromarrays() (in module numpy.core.records)
frombuffer (in module numpy.ma)
frombuffer() (in module numpy)
fromfile() (in module numpy)
(in module numpy.core.records)
fromfunction (in module numpy.ma)
fromfunction() (in module numpy)
fromiter() (in module numpy)
frompyfunc() (in module numpy)
fromrecords() (in module numpy.core.records)
fromregex() (in module numpy)
fromroots() (numpy.polynomial.chebyshev.Chebyshev class method)
(numpy.polynomial.hermite.Hermite class method)
(numpy.polynomial.hermite_e.HermiteE class method)
(numpy.polynomial.laguerre.Laguerre class method)
(numpy.polynomial.legendre.Legendre class method)
(numpy.polynomial.polynomial.Polynomial class method)
fromstring() (in module numpy)
(in module numpy.core.records)
full() (in module numpy)
full_like() (in module numpy)
fv() (in module numpy)

G

gamma() (in module numpy.random)
(numpy.random.RandomState method)
generate_config_py() (in module numpy.distutils.misc_util)
generic (class in numpy)
genfromtxt() (in module numpy)
geometric() (in module numpy.random)
(numpy.random.RandomState method)
get_build_temp_dir() (numpy.distutils.misc_util.Configuration method)
get_cmd() (in module numpy.distutils.misc_util)
get_config_cmd() (numpy.distutils.misc_util.Configuration method)
get_dependencies() (in module numpy.distutils.misc_util)
get_distribution() (numpy.distutils.misc_util.Configuration method)
get_ext_source_files() (in module numpy.distutils.misc_util)
get_fill_value() (numpy.ma.masked_array method)
(numpy.ma.MaskedArray method)
get_imag() (numpy.ma.masked_array method)
get_info() (in module numpy.distutils.system_info)
(numpy.distutils.misc_util.Configuration method)
get_numpy_include_dirs() (in module numpy.distutils.misc_util)
get_printoptions() (in module numpy)
get_real() (numpy.ma.masked_array method)
get_script_files() (in module numpy.distutils.misc_util)
get_standard_file() (in module numpy.distutils.system_info)
get_state() (in module numpy.random)
(numpy.random.RandomState method)
get_subpackage() (numpy.distutils.misc_util.Configuration method)
get_version() (numpy.distutils.misc_util.Configuration method)
getA() (numpy.matrix method)
getA1() (numpy.matrix method)
getbuffer() (in module numpy)
getbufsize() (in module numpy)
getdata() (in module numpy.ma)
geterr() (in module numpy)
geterrcall() (in module numpy)
geterrobj() (in module numpy)
getfield() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
getH() (numpy.matrix method)
getI() (numpy.matrix method)
getmask() (in module numpy.ma)
getmaskarray() (in module numpy.ma)
getslice
ndarray special methods
getT() (numpy.matrix method)
gradient() (in module numpy)
greater (in module numpy)
greater() (in module numpy.core.defchararray)
greater_equal (in module numpy)
greater_equal() (in module numpy.core.defchararray)
green_text() (in module numpy.distutils.misc_util)
gumbel() (in module numpy.random)
(numpy.random.RandomState method)

H

H (numpy.matrix attribute)
hamming() (in module numpy)
hanning() (in module numpy)
harden_mask (in module numpy.ma)
harden_mask() (numpy.ma.masked_array method)
(numpy.ma.MaskedArray method)
hardmask (numpy.ma.masked_array attribute)
(numpy.ma.MaskedArray attribute)
has_cxx_sources() (in module numpy.distutils.misc_util)
has_delayed_bufalloc (numpy.nditer attribute)
has_f_sources() (in module numpy.distutils.misc_util)
has_index (numpy.nditer attribute)
has_multi_index (numpy.nditer attribute)
has_samecoef() (numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
has_samedomain() (numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
has_sametype() (numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
has_samewindow() (numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
hasobject (numpy.dtype attribute)
have_f77c() (numpy.distutils.misc_util.Configuration method)
have_f90c() (numpy.distutils.misc_util.Configuration method)
herm2poly() (in module numpy.polynomial.hermite)
hermadd() (in module numpy.polynomial.hermite)
hermcompanion() (in module numpy.polynomial.hermite)
hermder() (in module numpy.polynomial.hermite)
hermdiv() (in module numpy.polynomial.hermite)
hermdomain (in module numpy.polynomial.hermite)
herme2poly() (in module numpy.polynomial.hermite_e)
hermeadd() (in module numpy.polynomial.hermite_e)
hermecompanion() (in module numpy.polynomial.hermite_e)
hermeder() (in module numpy.polynomial.hermite_e)
hermediv() (in module numpy.polynomial.hermite_e)
hermedomain (in module numpy.polynomial.hermite_e)
hermefit() (in module numpy.polynomial.hermite_e)
hermefromroots() (in module numpy.polynomial.hermite_e)
hermegauss() (in module numpy.polynomial.hermite_e)
hermegrid2d() (in module numpy.polynomial.hermite_e)
hermegrid3d() (in module numpy.polynomial.hermite_e)
hermeint() (in module numpy.polynomial.hermite_e)
hermeline() (in module numpy.polynomial.hermite_e)
hermemul() (in module numpy.polynomial.hermite_e)
hermemulx() (in module numpy.polynomial.hermite_e)
hermeone (in module numpy.polynomial.hermite_e)
hermepow() (in module numpy.polynomial.hermite_e)
hermeroots() (in module numpy.polynomial.hermite_e)
hermesub() (in module numpy.polynomial.hermite_e)
hermetrim() (in module numpy.polynomial.hermite_e)
hermeval() (in module numpy.polynomial.hermite_e)
hermeval2d() (in module numpy.polynomial.hermite_e)
hermeval3d() (in module numpy.polynomial.hermite_e)
hermevander() (in module numpy.polynomial.hermite_e)
hermevander2d() (in module numpy.polynomial.hermite_e)
hermevander3d() (in module numpy.polynomial.hermite_e)
hermeweight() (in module numpy.polynomial.hermite_e)
hermex (in module numpy.polynomial.hermite_e)
hermezero (in module numpy.polynomial.hermite_e)
hermfit() (in module numpy.polynomial.hermite)
hermfromroots() (in module numpy.polynomial.hermite)
hermgauss() (in module numpy.polynomial.hermite)
hermgrid2d() (in module numpy.polynomial.hermite)
hermgrid3d() (in module numpy.polynomial.hermite)
hermint() (in module numpy.polynomial.hermite)
Hermite (class in numpy.polynomial.hermite)
HermiteE (class in numpy.polynomial.hermite_e)
hermline() (in module numpy.polynomial.hermite)
hermmul() (in module numpy.polynomial.hermite)
hermmulx() (in module numpy.polynomial.hermite)
hermone (in module numpy.polynomial.hermite)
hermpow() (in module numpy.polynomial.hermite)
hermroots() (in module numpy.polynomial.hermite)
hermsub() (in module numpy.polynomial.hermite)
hermtrim() (in module numpy.polynomial.hermite)
hermval() (in module numpy.polynomial.hermite)
hermval2d() (in module numpy.polynomial.hermite)
hermval3d() (in module numpy.polynomial.hermite)
hermvander() (in module numpy.polynomial.hermite)
hermvander2d() (in module numpy.polynomial.hermite)
hermvander3d() (in module numpy.polynomial.hermite)
hermweight() (in module numpy.polynomial.hermite)
hermx (in module numpy.polynomial.hermite)
hermzero (in module numpy.polynomial.hermite)
hfft() (in module numpy.fft)
histogram() (in module numpy)
histogram2d() (in module numpy)
histogramdd() (in module numpy)
holidays (numpy.busdaycalendar attribute)
hsplit (in module numpy.ma)
hsplit() (in module numpy)
hstack (in module numpy.ma)
hstack() (in module numpy)
hypergeometric() (in module numpy.random)
(numpy.random.RandomState method)
hypot (in module numpy)

I

I (numpy.matrix attribute)
i0() (in module numpy)
identity (in module numpy.ma)
(numpy.ufunc attribute)
identity() (in module numpy)
(in module numpy.matlib)
(numpy.polynomial.chebyshev.Chebyshev class method)
(numpy.polynomial.hermite.Hermite class method)
(numpy.polynomial.hermite_e.HermiteE class method)
(numpy.polynomial.laguerre.Laguerre class method)
(numpy.polynomial.legendre.Legendre class method)
(numpy.polynomial.polynomial.Polynomial class method)
ids() (numpy.ma.masked_array method)
(numpy.ma.MaskedArray method)
ifft() (in module numpy.fft)
ifft2() (in module numpy.fft)
ifftn() (in module numpy.fft)
ifftshift() (in module numpy.fft)
ihfft() (in module numpy.fft)
iinfo (class in numpy)
imag (numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.generic attribute)
(numpy.ma.MaskType attribute)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.recarray attribute)
(numpy.record attribute)
imag() (in module numpy)
immutable
import_array (C function)
import_ufunc (C function)
in1d() (in module numpy)
index (numpy.broadcast attribute)
(numpy.flatiter attribute)
(numpy.nditer attribute)
index() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
indexing, [1], [2]
indices() (in module numpy)
(in module numpy.ma)
info() (in module numpy)
inner() (in module numpy)
(in module numpy.ma)
innerproduct() (in module numpy.ma)
insert() (in module numpy)
instance
integ() (numpy.poly1d method)
(numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
interface
array
interp() (in module numpy)
intersect1d() (in module numpy)
inv() (in module numpy.linalg)
invert (in module numpy)
ipmt() (in module numpy)
irfft() (in module numpy.fft)
irfft2() (in module numpy.fft)
irfftn() (in module numpy.fft)
irr() (in module numpy)
is_busday() (in module numpy)
is_local_src_dir() (in module numpy.distutils.misc_util)
is_mask() (in module numpy.ma)
is_masked() (in module numpy.ma)
isalignedstruct (numpy.dtype attribute)
isalnum() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
isalpha() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
isbuiltin (numpy.dtype attribute)
isclose() (in module numpy)
iscomplex() (in module numpy)
iscomplexobj() (in module numpy)
iscontiguous() (numpy.ma.masked_array method)
(numpy.ma.MaskedArray method)
isdecimal() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
isdigit() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
isfinite (in module numpy)
isfortran() (in module numpy)
isinf (in module numpy)
islower() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
isnan (in module numpy)
isnative (numpy.dtype attribute)
isneginf() (in module numpy)
isnumeric() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
isposinf() (in module numpy)
isreal() (in module numpy)
isrealobj() (in module numpy)
isscalar() (in module numpy)
issctype() (in module numpy)
isspace() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
issubclass_() (in module numpy)
issubdtype() (in module numpy)
issubsctype() (in module numpy)
istitle() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
isupper() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
item() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
itemset() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
itemsize (numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.dtype attribute)
(numpy.generic attribute)
(numpy.ma.MaskType attribute)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.recarray attribute)
(numpy.record attribute)
iterable
iterationneedsapi (numpy.nditer attribute)
iterator
C-API, [1], [2]
iterindex (numpy.nditer attribute)
iternext() (numpy.nditer method)
iterrange (numpy.nditer attribute)
iters (numpy.broadcast attribute)
itersize (numpy.nditer attribute)
itviews (numpy.nditer attribute)
ix_() (in module numpy)

J

join() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)

K

kaiser() (in module numpy)
keyword arguments
ufunc
kind (numpy.dtype attribute)
knownfailureif() (in module numpy.testing.decorators)
kron() (in module numpy)

L

lag2poly() (in module numpy.polynomial.laguerre)
lagadd() (in module numpy.polynomial.laguerre)
lagcompanion() (in module numpy.polynomial.laguerre)
lagder() (in module numpy.polynomial.laguerre)
lagdiv() (in module numpy.polynomial.laguerre)
lagdomain (in module numpy.polynomial.laguerre)
lagfit() (in module numpy.polynomial.laguerre)
lagfromroots() (in module numpy.polynomial.laguerre)
laggauss() (in module numpy.polynomial.laguerre)
laggrid2d() (in module numpy.polynomial.laguerre)
laggrid3d() (in module numpy.polynomial.laguerre)
lagint() (in module numpy.polynomial.laguerre)
lagline() (in module numpy.polynomial.laguerre)
lagmul() (in module numpy.polynomial.laguerre)
lagmulx() (in module numpy.polynomial.laguerre)
lagone (in module numpy.polynomial.laguerre)
lagpow() (in module numpy.polynomial.laguerre)
lagroots() (in module numpy.polynomial.laguerre)
lagsub() (in module numpy.polynomial.laguerre)
lagtrim() (in module numpy.polynomial.laguerre)
Laguerre (class in numpy.polynomial.laguerre)
lagval() (in module numpy.polynomial.laguerre)
lagval2d() (in module numpy.polynomial.laguerre)
lagval3d() (in module numpy.polynomial.laguerre)
lagvander() (in module numpy.polynomial.laguerre)
lagvander2d() (in module numpy.polynomial.laguerre)
lagvander3d() (in module numpy.polynomial.laguerre)
lagweight() (in module numpy.polynomial.laguerre)
lagx (in module numpy.polynomial.laguerre)
lagzero (in module numpy.polynomial.laguerre)
laplace() (in module numpy.random)
(numpy.random.RandomState method)
ldexp (in module numpy)
left_shift (in module numpy)
leg2poly() (in module numpy.polynomial.legendre)
legadd() (in module numpy.polynomial.legendre)
legcompanion() (in module numpy.polynomial.legendre)
legder() (in module numpy.polynomial.legendre)
legdiv() (in module numpy.polynomial.legendre)
legdomain (in module numpy.polynomial.legendre)
Legendre (class in numpy.polynomial.legendre)
legfit() (in module numpy.polynomial.legendre)
legfromroots() (in module numpy.polynomial.legendre)
leggauss() (in module numpy.polynomial.legendre)
leggrid2d() (in module numpy.polynomial.legendre)
leggrid3d() (in module numpy.polynomial.legendre)
legint() (in module numpy.polynomial.legendre)
legline() (in module numpy.polynomial.legendre)
legmul() (in module numpy.polynomial.legendre)
legmulx() (in module numpy.polynomial.legendre)
legone (in module numpy.polynomial.legendre)
legpow() (in module numpy.polynomial.legendre)
legroots() (in module numpy.polynomial.legendre)
legsub() (in module numpy.polynomial.legendre)
legtrim() (in module numpy.polynomial.legendre)
legval() (in module numpy.polynomial.legendre)
legval2d() (in module numpy.polynomial.legendre)
legval3d() (in module numpy.polynomial.legendre)
legvander() (in module numpy.polynomial.legendre)
legvander2d() (in module numpy.polynomial.legendre)
legvander3d() (in module numpy.polynomial.legendre)
legweight() (in module numpy.polynomial.legendre)
legx (in module numpy.polynomial.legendre)
legzero (in module numpy.polynomial.legendre)
less (in module numpy)
less() (in module numpy.core.defchararray)
less_equal (in module numpy)
less_equal() (in module numpy.core.defchararray)
lexsort() (in module numpy)
LinAlgError
linspace() (in module numpy)
(numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
list
ljust() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
load() (in module numpy)
(in module numpy.ma)
load_library() (in module numpy.ctypeslib)
loads() (in module numpy.ma)
loadtxt() (in module numpy)
log (in module numpy)
log10 (in module numpy)
log1p (in module numpy)
log2 (in module numpy)
logaddexp (in module numpy)
logaddexp2 (in module numpy)
logical_and (in module numpy)
logical_not (in module numpy)
logical_or (in module numpy)
logical_xor (in module numpy)
logistic() (in module numpy.random)
(numpy.random.RandomState method)
lognormal() (in module numpy.random)
(numpy.random.RandomState method)
logseries() (in module numpy.random)
(numpy.random.RandomState method)
logspace() (in module numpy)
lookfor() (in module numpy)
lower() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
lstrip() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
lstsq() (in module numpy.linalg)

M

MachAr (class in numpy)
make_config_py() (numpy.distutils.misc_util.Configuration method)
make_mask() (in module numpy.ma)
make_mask_descr() (in module numpy.ma)
make_mask_none() (in module numpy.ma)
make_svn_version_py() (numpy.distutils.misc_util.Configuration method)
mapparms() (numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
mask
(numpy.ma.MaskedArray attribute), [1]
(numpy.ma.masked_array attribute)
mask_cols() (in module numpy.ma)
mask_indices() (in module numpy)
mask_or() (in module numpy.ma)
mask_rowcols() (in module numpy.ma)
mask_rows() (in module numpy.ma)
masked (in module numpy.ma)
masked array
masked arrays
masked_all() (in module numpy.ma)
masked_all_like() (in module numpy.ma)
masked_array (in module numpy.ma)
masked_equal() (in module numpy.ma)
masked_greater() (in module numpy.ma)
masked_greater_equal() (in module numpy.ma)
masked_inside() (in module numpy.ma)
masked_invalid() (in module numpy.ma)
masked_less() (in module numpy.ma)
masked_less_equal() (in module numpy.ma)
masked_not_equal() (in module numpy.ma)
masked_object() (in module numpy.ma)
masked_outside() (in module numpy.ma)
masked_print_options (in module numpy.ma)
masked_values() (in module numpy.ma)
masked_where() (in module numpy.ma)
MaskedArray (class in numpy.ma)
MaskType (in module numpy.ma)
mat() (in module numpy)
matrix, [1]
(class in numpy)
matrix_power() (in module numpy.linalg)
matrix_rank() (in module numpy.linalg)
max (numpy.iinfo attribute)
max() (in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
maximum (in module numpy)
maximum_fill_value() (in module numpy.ma)
maxpower (numpy.polynomial.chebyshev.Chebyshev attribute)
(numpy.polynomial.hermite.Hermite attribute)
(numpy.polynomial.hermite_e.HermiteE attribute)
(numpy.polynomial.laguerre.Laguerre attribute)
(numpy.polynomial.legendre.Legendre attribute)
(numpy.polynomial.polynomial.Polynomial attribute)
mean (in module numpy.ma)
mean() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
median() (in module numpy)
(in module numpy.ma)
memmap (class in numpy)
memory maps
memory model
ndarray
meshgrid() (in module numpy)
metadata (numpy.dtype attribute)
method
methods
accumulate, ufunc
reduce, ufunc
reduceat, ufunc
ufunc
mgrid (in module numpy)
min (numpy.iinfo attribute)
min() (in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
min_scalar_type() (in module numpy)
mini() (numpy.ma.masked_array method)
minimum (in module numpy)
mintypecode() (in module numpy)
mirr() (in module numpy)
mod (in module numpy)
mod() (in module numpy.core.defchararray)
modf (in module numpy)
mr_ (in module numpy.ma)
msort() (in module numpy)
multi_index (numpy.nditer attribute)
multinomial() (in module numpy.random)
(numpy.random.RandomState method)
multiply (in module numpy)
multiply() (in module numpy.core.defchararray)
multivariate_normal() (in module numpy.random)
(numpy.random.RandomState method)

N

name (numpy.dtype attribute)
names (numpy.dtype attribute)
nan_to_num() (in module numpy)
nanargmax() (in module numpy)
nanargmin() (in module numpy)
nanmax() (in module numpy)
nanmean() (in module numpy)
nanmin() (in module numpy)
nanstd() (in module numpy)
nansum() (in module numpy)
nanvar() (in module numpy)
nargs (numpy.ufunc attribute)
nbytes (numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.generic attribute)
(numpy.ma.MaskType attribute)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.recarray attribute)
(numpy.record attribute)
nd (numpy.broadcast attribute)
ndarray, [1]
C-API, [1]
memory model
special methods getslice
special methods setslice
subtyping, [1]
view
ndarray (class in numpy)
ndenumerate (class in numpy)
ndim (numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.generic attribute)
(numpy.ma.MaskType attribute)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.nditer attribute)
(numpy.recarray attribute)
(numpy.record attribute)
ndincr() (numpy.ndindex method)
ndindex (class in numpy)
nditer (class in numpy)
ndpointer() (built-in function)
(in module numpy.ctypeslib)
negative (in module numpy)
negative_binomial() (in module numpy.random)
(numpy.random.RandomState method)
newaxis
(in module numpy)
newbuffer() (in module numpy)
newbyteorder() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.dtype method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
next (numpy.broadcast attribute)
(numpy.flatiter attribute)
(numpy.nditer attribute)
next() (numpy.ndenumerate method)
(numpy.ndindex method)
nickname (numpy.polynomial.chebyshev.Chebyshev attribute)
(numpy.polynomial.hermite.Hermite attribute)
(numpy.polynomial.hermite_e.HermiteE attribute)
(numpy.polynomial.laguerre.Laguerre attribute)
(numpy.polynomial.legendre.Legendre attribute)
(numpy.polynomial.polynomial.Polynomial attribute)
nin (numpy.ufunc attribute)
NO_IMPORT_ARRAY (C macro)
NO_IMPORT_UFUNC (C variable)
nomask (in module numpy.ma)
non-contiguous
noncentral_chisquare() (in module numpy.random)
(numpy.random.RandomState method)
noncentral_f() (in module numpy.random)
(numpy.random.RandomState method)
nonzero (in module numpy.ma)
nonzero() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
nop (numpy.nditer attribute)
norm() (in module numpy.linalg)
normal() (in module numpy.random)
(numpy.random.RandomState method)
not_equal (in module numpy)
not_equal() (in module numpy.core.defchararray)
notmasked_contiguous() (in module numpy.ma)
notmasked_edges() (in module numpy.ma)
nout (numpy.ufunc attribute)
nper() (in module numpy)
npv() (in module numpy)
NPY_1_PI (C variable)
NPY_2_PI (C variable)
NPY_ALLOW_C_API (C macro)
NPY_ALLOW_C_API_DEF (C macro)
NPY_ANYORDER (C variable)
NPY_ARRAY_ALIGNED (C variable), [1]
NPY_ARRAY_BEHAVED (C variable), [1]
NPY_ARRAY_BEHAVED_NS (C variable), [1]
NPY_ARRAY_C_CONTIGUOUS (C variable), [1]
NPY_ARRAY_CARRAY (C variable), [1]
NPY_ARRAY_CARRAY_RO (C variable), [1]
NPY_ARRAY_DEFAULT (C variable), [1]
NPY_ARRAY_ELEMENTSTRIDES (C variable)
NPY_ARRAY_ENSUREARRAY (C variable), [1], [2]
NPY_ARRAY_ENSURECOPY (C variable), [1], [2]
NPY_ARRAY_F_CONTIGUOUS (C variable), [1]
NPY_ARRAY_FARRAY (C variable), [1]
NPY_ARRAY_FARRAY_RO (C variable), [1]
NPY_ARRAY_FORCECAST (C variable), [1], [2]
NPY_ARRAY_IN_ARRAY (C variable), [1]
NPY_ARRAY_IN_FARRAY (C variable)
NPY_ARRAY_INOUT_ARRAY (C variable), [1]
NPY_ARRAY_INOUT_FARRAY (C variable)
NPY_ARRAY_NOTSWAPPED (C variable), [1]
NPY_ARRAY_OUT_ARRAY (C variable)
NPY_ARRAY_OUT_FARRAY (C variable)
NPY_ARRAY_OWNDATA (C variable)
NPY_ARRAY_UPDATE_ALL (C variable)
NPY_ARRAY_UPDATEIFCOPY (C variable), [1]
NPY_ARRAY_WRITEABLE (C variable), [1]
NPY_AUXDATA_CLONE (C function)
NPY_AUXDATA_FREE (C function)
NPY_BEGIN_ALLOW_THREADS (C macro)
NPY_BEGIN_THREADS (C macro)
NPY_BEGIN_THREADS_DEF (C macro)
NPY_BEGIN_THREADS_DESCR (C function)
NPY_BEGIN_THREADS_THRESHOLDED (C function)
NPY_BIG_ENDIAN (C variable)
npy_bool (C type)
NPY_BOOL (C variable)
NPY_BUFSIZE (C variable)
NPY_BYTE (C variable)
NPY_BYTE_ORDER (C variable)
NPY_CASTING (C type)
NPY_CDOUBLE (C variable)
NPY_CFLOAT (C variable)
npy_clear_floatstatus (C function)
NPY_CLIP (C variable), [1]
NPY_CLIPMODE (C type)
NPY_CLONGDOUBLE (C variable)
NPY_COMPLEX128 (C variable)
NPY_COMPLEX64 (C variable)
npy_copysign (C function)
NPY_CORDER (C variable)
NPY_CPU_AMD64 (C variable)
NPY_CPU_IA64 (C variable)
NPY_CPU_PARISC (C variable)
NPY_CPU_PPC (C variable)
NPY_CPU_PPC64 (C variable)
NPY_CPU_S390 (C variable)
NPY_CPU_SPARC (C variable)
NPY_CPU_SPARC64 (C variable)
NPY_CPU_X86 (C variable)
NPY_DATETIME (C variable)
NPY_DEFAULT_TYPE (C variable)
NPY_DISABLE_C_API (C macro)
NPY_DOUBLE (C variable)
npy_double_to_half (C function)
npy_doublebits_to_halfbits (C function)
NPY_E (C variable)
NPY_END_ALLOW_THREADS (C macro)
NPY_END_THREADS (C macro)
NPY_END_THREADS_DESCR (C function)
NPY_EQUIV_CASTING (C variable)
NPY_EULER (C variable)
NPY_FAIL (C variable)
NPY_FALSE (C variable)
NPY_FLOAT (C variable)
NPY_FLOAT16 (C variable)
NPY_FLOAT32 (C variable)
NPY_FLOAT64 (C variable)
npy_float_to_half (C function)
npy_floatbits_to_halfbits (C function)
NPY_FORTRANORDER (C variable)
NPY_FROM_FIELDS (C variable)
npy_get_floatstatus (C function)
NPY_HALF (C variable)
npy_half_copysign (C function)
npy_half_eq (C function)
npy_half_eq_nonan (C function)
npy_half_ge (C function)
npy_half_gt (C function)
npy_half_isfinite (C function)
npy_half_isinf (C function)
npy_half_isnan (C function)
npy_half_iszero (C function)
npy_half_le (C function)
npy_half_le_nonan (C function)
npy_half_lt (C function)
npy_half_lt_nonan (C function)
NPY_HALF_NAN (C variable)
npy_half_ne (C function)
NPY_HALF_NEGONE (C variable)
npy_half_nextafter (C function)
NPY_HALF_NINF (C variable)
NPY_HALF_NZERO (C variable)
NPY_HALF_ONE (C variable)
NPY_HALF_PINF (C variable)
NPY_HALF_PZERO (C variable)
npy_half_signbit (C function)
npy_half_spacing (C function)
npy_half_to_double (C function)
npy_half_to_float (C function)
NPY_HALF_ZERO (C variable)
npy_halfbits_to_doublebits (C function)
npy_halfbits_to_floatbits (C function)
NPY_INFINITY (C variable)
NPY_INT (C variable)
NPY_INT16 (C variable)
NPY_INT32 (C variable)
NPY_INT64 (C variable)
NPY_INT8 (C variable)
NPY_INTP (C variable)
npy_isfinite (C function)
npy_isinf (C function)
npy_isnan (C function)
NPY_ITEM_HASOBJECT (C variable)
NPY_ITEM_IS_POINTER (C variable)
NPY_ITEM_REFCOUNT (C variable)
NPY_ITER_ALIGNED (C variable)
NPY_ITER_ALLOCATE (C variable)
NPY_ITER_ARRAYMASK (C variable)
NPY_ITER_BUFFERED (C variable)
NPY_ITER_C_INDEX (C variable)
NPY_ITER_COMMON_DTYPE (C variable)
NPY_ITER_CONTIG (C variable)
NPY_ITER_COPY (C variable)
NPY_ITER_DELAY_BUFALLOC (C variable)
NPY_ITER_DONT_NEGATE_STRIDES (C variable)
NPY_ITER_EXTERNAL_LOOP (C variable)
NPY_ITER_F_INDEX (C variable)
NPY_ITER_GROWINNER (C variable)
NPY_ITER_MULTI_INDEX (C variable)
NPY_ITER_NBO (C variable)
NPY_ITER_NO_BROADCAST (C variable)
NPY_ITER_NO_SUBTYPE (C variable)
NPY_ITER_RANGED (C variable)
NPY_ITER_READONLY (C variable)
NPY_ITER_READWRITE (C variable)
NPY_ITER_REDUCE_OK (C variable)
NPY_ITER_REFS_OK (C variable)
NPY_ITER_UPDATEIFCOPY (C variable)
NPY_ITER_WRITEMASKED (C variable)
NPY_ITER_WRITEONLY (C variable)
NPY_ITER_ZEROSIZE_OK (C variable)
NPY_KEEPORDER (C variable)
NPY_LIST_PICKLE (C variable)
NPY_LITTLE_ENDIAN (C variable)
NPY_LOG10E (C variable)
NPY_LOG2E (C variable)
NPY_LOGE10 (C variable)
NPY_LOGE2 (C variable)
NPY_LONG (C variable)
NPY_LONGDOUBLE (C variable)
NPY_LONGLONG (C variable)
NPY_LOOP_BEGIN_THREADS (C macro)
NPY_LOOP_END_THREADS (C macro)
NPY_MASK (C variable)
NPY_MAX_BUFSIZE (C variable)
NPY_MAXDIMS (C variable)
NPY_MIN_BUFSIZE (C variable)
NPY_NAN (C variable)
NPY_NEEDS_INIT (C variable)
NPY_NEEDS_PYAPI (C variable)
npy_nextafter (C function)
NPY_NO_CASTING (C variable)
NPY_NOTYPE (C variable)
NPY_NSCALARKINDS (C variable)
NPY_NSORTS (C variable)
NPY_NTYPES (C variable)
NPY_NUM_FLOATTYPE (C variable)
NPY_NZERO (C variable)
NPY_OBJECT (C variable)
NPY_OBJECT_DTYPE_FLAGS (C variable)
NPY_ORDER (C type)
NPY_OUT_ARRAY (C variable)
NPY_PI (C variable)
NPY_PI_2 (C variable)
NPY_PI_4 (C variable)
NPY_PRIORITY (C variable)
NPY_PZERO (C variable)
NPY_RAISE (C variable), [1]
NPY_SAFE_CASTING (C variable)
NPY_SAME_KIND_CASTING (C variable)
NPY_SCALAR_PRIORITY (C variable)
NPY_SCALARKIND (C type)
npy_set_floatstatus_divbyzero (C function)
npy_set_floatstatus_invalid (C function)
npy_set_floatstatus_overflow (C function)
npy_set_floatstatus_underflow (C function)
NPY_SHORT (C variable)
npy_signbit (C function)
NPY_SIZEOF_DOUBLE (C variable)
NPY_SIZEOF_FLOAT (C variable)
NPY_SIZEOF_INT (C variable)
NPY_SIZEOF_LONG (C variable)
NPY_SIZEOF_LONG_DOUBLE (C variable)
NPY_SIZEOF_LONGLONG (C variable)
NPY_SIZEOF_PY_INTPTR_T (C variable)
NPY_SIZEOF_PY_LONG_LONG (C variable)
NPY_SIZEOF_SHORT (C variable)
NPY_SORTKIND (C type)
npy_spacing (C function)
NPY_STRING (C variable)
NPY_SUBTYPE_PRIORITY (C variable)
NPY_SUCCEED (C variable)
NPY_TIMEDELTA (C variable)
NPY_TRUE (C variable)
NPY_UBYTE (C variable)
NPY_UINT (C variable)
NPY_UINT16 (C variable)
NPY_UINT32 (C variable)
NPY_UINT64 (C variable)
NPY_UINT8 (C variable)
NPY_UINTP (C variable)
NPY_ULONG (C variable)
NPY_ULONGLONG (C variable)
NPY_UNICODE (C variable)
NPY_UNSAFE_CASTING (C variable)
NPY_USE_GETITEM (C variable)
NPY_USE_SETITEM (C variable)
NPY_USERDEF (C variable)
NPY_USHORT (C variable)
NPY_VERSION (C variable)
NPY_VOID (C variable)
NPY_WRAP (C variable), [1]
NpyAuxData (C type)
NpyAuxData_CloneFunc (C type)
NpyAuxData_FreeFunc (C type)
NpyIter (C type)
NpyIter_AdvancedNew (C function)
NpyIter_Copy (C function)
NpyIter_CreateCompatibleStrides (C function)
NpyIter_Deallocate (C function)
NpyIter_EnableExternalLoop (C function)
NpyIter_GetAxisStrideArray (C function)
NpyIter_GetBufferSize (C function)
NpyIter_GetDataPtrArray (C function)
NpyIter_GetDescrArray (C function)
NpyIter_GetFirstMaskNAOp (C function)
NpyIter_GetGetMultiIndex (C function)
NpyIter_GetIndexPtr (C function)
NpyIter_GetInitialDataPtrArray (C function)
NpyIter_GetInnerFixedStrideArray (C function)
NpyIter_GetInnerLoopSizePtr (C function)
NpyIter_GetInnerStrideArray (C function)
NpyIter_GetIterIndex (C function)
NpyIter_GetIterIndexRange (C function)
NpyIter_GetIterNext (C function)
NpyIter_GetIterSize (C function)
NpyIter_GetIterView (C function)
NpyIter_GetMaskNAIndexArray (C function)
NpyIter_GetMultiIndexFunc (C type)
NpyIter_GetNDim (C function)
NpyIter_GetNOp (C function)
NpyIter_GetOperandArray (C function)
NpyIter_GetReadFlags (C function)
NpyIter_GetShape (C function)
NpyIter_GetWriteFlags (C function)
NpyIter_GotoIndex (C function)
NpyIter_GotoIterIndex (C function)
NpyIter_GotoMultiIndex (C function)
NpyIter_HasDelayedBufAlloc (C function)
NpyIter_HasExternalLoop (C function)
NpyIter_HasIndex (C function)
NpyIter_HasMultiIndex (C function)
NpyIter_IsBuffered (C function)
NpyIter_IsFirstVisit (C function)
NpyIter_IsGrowInner (C function)
NpyIter_IterNextFunc (C type)
NpyIter_MultiNew (C function)
NpyIter_New (C function)
NpyIter_RemoveMultiIndex (C function)
NpyIter_RequiresBuffering (C function)
NpyIter_Reset (C function)
NpyIter_ResetBasePointers (C function)
NpyIter_ResetToIterIndexRange (C function)
NpyIter_Type (C type)
ntypes (numpy.ufunc attribute)
num (numpy.dtype attribute)
numiter (numpy.broadcast attribute)
numpy (module)
numpy.distutils (module)
numpy.distutils.exec_command (module)
numpy.distutils.misc_util (module)
numpy.doc.basics (module)
numpy.doc.broadcasting (module)
numpy.doc.byteswapping (module)
numpy.doc.creation (module)
numpy.doc.glossary (module)
numpy.doc.howtofind (module)
numpy.doc.indexing (module)
numpy.doc.internals (module)
numpy.doc.jargon (module)
numpy.doc.methods_vs_functions (module)
numpy.doc.misc (module)
numpy.doc.performance (module)
numpy.doc.structured_arrays (module)
numpy.doc.subclassing (module)
numpy.dual (module)
numpy.fft (module)
numpy.lib.scimath (module)

O

obj2sctype() (in module numpy)
offset
ogrid (in module numpy)
ones (in module numpy.ma)
ones() (in module numpy)
(in module numpy.matlib)
ones_like() (in module numpy)
open() (numpy.DataSource method)
operands (numpy.nditer attribute)
operation, [1]
operator, [1]
order (numpy.poly1d attribute)
outer() (in module numpy)
(in module numpy.ma)
(numpy.ufunc method)
outerproduct() (in module numpy.ma)

P

packbits() (in module numpy)
pad() (in module numpy)
pareto() (in module numpy.random)
(numpy.random.RandomState method)
partition() (in module numpy)
(in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
paths() (numpy.distutils.misc_util.Configuration method)
percentile() (in module numpy)
permutation() (in module numpy.random)
(numpy.random.RandomState method)
piecewise() (in module numpy)
pinv() (in module numpy.linalg)
place() (in module numpy)
pmt() (in module numpy)
poisson() (in module numpy.random)
(numpy.random.RandomState method)
poisson_lam_max (numpy.random.RandomState attribute)
poly() (in module numpy)
poly1d (class in numpy)
poly2cheb() (in module numpy.polynomial.chebyshev)
poly2herm() (in module numpy.polynomial.hermite)
poly2herme() (in module numpy.polynomial.hermite_e)
poly2lag() (in module numpy.polynomial.laguerre)
poly2leg() (in module numpy.polynomial.legendre)
polyadd() (in module numpy)
(in module numpy.polynomial.polynomial)
polycompanion() (in module numpy.polynomial.polynomial)
polyder() (in module numpy)
(in module numpy.polynomial.polynomial)
polydiv() (in module numpy)
(in module numpy.polynomial.polynomial)
polydomain (in module numpy.polynomial.polynomial)
polyfit() (in module numpy)
(in module numpy.ma)
(in module numpy.polynomial.polynomial)
polyfromroots() (in module numpy.polynomial.polynomial)
polygrid2d() (in module numpy.polynomial.polynomial)
polygrid3d() (in module numpy.polynomial.polynomial)
polyint() (in module numpy)
(in module numpy.polynomial.polynomial)
polyline() (in module numpy.polynomial.polynomial)
polymul() (in module numpy)
(in module numpy.polynomial.polynomial)
polymulx() (in module numpy.polynomial.polynomial)
Polynomial (class in numpy.polynomial.polynomial)
polyone (in module numpy.polynomial.polynomial)
polypow() (in module numpy.polynomial.polynomial)
polyroots() (in module numpy.polynomial.polynomial)
polysub() (in module numpy)
(in module numpy.polynomial.polynomial)
polytrim() (in module numpy.polynomial.polynomial)
polyval() (in module numpy)
(in module numpy.polynomial.polynomial)
polyval2d() (in module numpy.polynomial.polynomial)
polyval3d() (in module numpy.polynomial.polynomial)
polyvander() (in module numpy.polynomial.polynomial)
polyvander2d() (in module numpy.polynomial.polynomial)
polyvander3d() (in module numpy.polynomial.polynomial)
polyx (in module numpy.polynomial.polynomial)
polyzero (in module numpy.polynomial.polynomial)
power (in module numpy)
power() (in module numpy.ma)
(in module numpy.random)
(numpy.random.RandomState method)
ppmt() (in module numpy)
pprint() (numpy.record method)
prepare_test_args() (numpy.testing.Tester method)
prod (in module numpy.ma)
prod() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
product() (numpy.ma.masked_array method)
(numpy.ma.MaskedArray method)
promote_types() (in module numpy)
protocol
array
ptp() (in module numpy)
(in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
put() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
putmask() (in module numpy)
pv() (in module numpy)
PY_ARRAY_UNIQUE_SYMBOL (C macro)
PY_UFUNC_UNIQUE_SYMBOL (C variable)
PyArray_All (C function)
PyArray_Any (C function)
PyArray_Arange (C function)
PyArray_ArangeObj (C function)
PyArray_ArgMax (C function)
PyArray_ArgMin (C function)
PyArray_ArgPartition (C function)
PyArray_ArgSort (C function)
PyArray_ArrayDescr.base (C member)
PyArray_ArrayDescr.shape (C member)
PyArray_ArrayType (C function)
PyArray_ArrFuncs (C type)
PyArray_ArrFuncs.cancastscalarkindto (C member)
PyArray_ArrFuncs.cancastto (C member)
PyArray_ArrFuncs.castdict (C member)
PyArray_ArrFuncs.compare (C member)
PyArray_ArrFuncs.copyswap (C member)
PyArray_ArrFuncs.fill (C member)
PyArray_ArrFuncs.fromstr (C member)
PyArray_ArrFuncs.getitem (C member)
PyArray_ArrFuncs.listpickle (C member)
PyArray_ArrFuncs.nonzero (C member)
PyArray_ArrFuncs.scalarkind (C member)
PyArray_ArrFuncs.scanfunc (C member)
PyArray_ArrFuncs.setitem (C member)
PyArray_ArrFuncs.sort (C member)
PyArray_AsCArray (C function)
PyArray_AxisConverter (C function)
PyArray_BASE (C function)
PyArray_BoolConverter (C function)
PyArray_Broadcast (C function)
PyArray_BroadcastToShape (C function)
PyArray_BufferConverter (C function)
PyArray_ByteorderConverter (C function)
PyArray_BYTES (C function)
PyArray_Byteswap (C function)
PyArray_CanCastArrayTo (C function)
PyArray_CanCastSafely (C function)
PyArray_CanCastTo (C function)
PyArray_CanCastTypeTo (C function)
PyArray_CanCoerceScalar (C function)
PyArray_Cast (C function)
PyArray_CastingConverter (C function)
PyArray_CastScalarToCtype (C function)
PyArray_CastTo (C function)
PyArray_CastToType (C function)
PyArray_CEQ (C function)
PyArray_CGE (C function)
PyArray_CGT (C function)
PyArray_Check (C function)
PyArray_CheckAxis (C function)
PyArray_CheckExact (C function)
PyArray_CheckFromAny (C function)
PyArray_CheckScalar (C function)
PyArray_CheckStrides (C function)
PyArray_CHKFLAGS (C function)
PyArray_Choose (C function)
PyArray_Chunk (C type)
PyArray_Chunk.PyArray_Chunk.base (C member)
PyArray_Chunk.PyArray_Chunk.flags (C member)
PyArray_Chunk.PyArray_Chunk.len (C member)
PyArray_Chunk.PyArray_Chunk.ptr (C member)
PyArray_Chunk.PyObject_HEAD (C macro)
PyArray_CLE (C function)
PyArray_CLEARFLAGS (C function)
PyArray_Clip (C function)
PyArray_ClipmodeConverter (C function)
PyArray_CLT (C function)
PyArray_CNE (C function)
PyArray_CompareLists (C function)
PyArray_Compress (C function)
PyArray_Concatenate (C function)
PyArray_Conjugate (C function)
PyArray_ContiguousFromAny (C function)
PyArray_ConvertClipmodeSequence (C function)
PyArray_Converter (C function)
PyArray_ConvertToCommonType (C function)
PyArray_CopyAndTranspose (C function)
PyArray_CopyInto (C function)
PyArray_Correlate (C function)
PyArray_Correlate2 (C function)
PyArray_CountNonzero (C function)
PyArray_CumProd (C function)
PyArray_CumSum (C function)
PyArray_DATA (C function)
PyArray_DESCR (C function)
PyArray_Descr (C type)
PyArray_Descr.alignment (C member)
PyArray_Descr.byteorder (C member)
PyArray_Descr.elsize (C member)
PyArray_Descr.f (C member)
PyArray_Descr.fields (C member)
PyArray_Descr.flags (C member)
PyArray_Descr.kind (C member)
PyArray_Descr.subarray (C member)
PyArray_Descr.type (C member)
PyArray_Descr.type_num (C member)
PyArray_Descr.typeobj (C member)
Pyarray_DescrAlignConverter (C function)
Pyarray_DescrAlignConverter2 (C function)
PyArray_DescrCheck (C function)
PyArray_DescrConverter (C function)
PyArray_DescrConverter2 (C function)
PyArray_DescrFromObject (C function)
PyArray_DescrFromScalar (C function)
PyArray_DescrFromType (C function)
PyArray_DescrNew (C function)
PyArray_DescrNewByteorder (C function)
PyArray_DescrNewFromType (C function)
PyArray_Diagonal (C function)
PyArray_DIM (C function)
PyArray_DIMS (C function)
PyArray_Dims (C type)
PyArray_Dims.PyArray_Dims.len (C member)
PyArray_Dims.PyArray_Dims.ptr (C member)
PyArray_DTYPE (C function)
PyArray_Dump (C function)
PyArray_Dumps (C function)
PyArray_EinsteinSum (C function)
PyArray_Empty (C function)
PyArray_EMPTY (C function)
PyArray_ENABLEFLAGS (C function)
PyArray_EnsureArray (C function)
PyArray_EquivArrTypes (C function)
PyArray_EquivByteorders (C function)
PyArray_EquivTypenums (C function)
PyArray_EquivTypes (C function)
PyArray_FieldNames (C function)
PyArray_FillObjectArray (C function)
PyArray_FILLWBYTE (C function)
PyArray_FillWithScalar (C function)
PyArray_FLAGS (C function)
PyArray_Flatten (C function)
PyArray_free (C function)
PyArray_Free (C function)
PyArray_FROM_O (C function)
PyArray_FROM_OF (C function)
PyArray_FROM_OT (C function)
PyArray_FROM_OTF (C function), [1]
PyArray_FROMANY (C function)
PyArray_FromAny (C function)
PyArray_FromArray (C function)
PyArray_FromArrayAttr (C function)
PyArray_FromBuffer (C function)
PyArray_FromFile (C function)
PyArray_FromInterface (C function)
PyArray_FromObject (C function)
PyArray_FromScalar (C function)
PyArray_FromString (C function)
PyArray_FromStructInterface (C function)
PyArray_GetArrayParamsFromObject (C function)
PyArray_GetCastFunc (C function)
PyArray_GETCONTIGUOUS (C function)
PyArray_GetEndianness (C function)
PyArray_GetField (C function)
PyArray_GETITEM (C function)
PyArray_GetNDArrayCFeatureVersion (C function)
PyArray_GetNDArrayCVersion (C function)
PyArray_GetNumericOps (C function)
PyArray_GetPriority (C function)
PyArray_GetPtr (C function)
PyArray_GETPTR1 (C function)
PyArray_GETPTR2 (C function)
PyArray_GETPTR3 (C function)
PyArray_GETPTR4 (C function)
PyArray_HasArrayInterface (C function)
PyArray_HasArrayInterfaceType (C function)
PyArray_HASFIELDS (C function)
PyArray_INCREF (C function)
PyArray_InitArrFuncs (C function)
PyArray_InnerProduct (C function)
PyArray_IntpConverter (C function)
PyArray_IntpFromSequence (C function)
PyArray_IS_C_CONTIGUOUS (C function)
PyArray_IS_F_CONTIGUOUS (C function)
PyArray_ISALIGNED (C function)
PyArray_IsAnyScalar (C function)
PyArray_ISBEHAVED (C function)
PyArray_ISBEHAVED_RO (C function)
PyArray_ISBOOL (C function)
PyArray_ISBYTESWAPPED (C function)
PyArray_ISCARRAY (C function)
PyArray_ISCARRAY_RO (C function)
PyArray_ISCOMPLEX (C function)
PyArray_ISEXTENDED (C function)
PyArray_ISFARRAY (C function)
PyArray_ISFARRAY_RO (C function)
PyArray_ISFLEXIBLE (C function)
PyArray_ISFLOAT (C function)
PyArray_ISFORTRAN (C function)
PyArray_ISINTEGER (C function)
PyArray_ISNOTSWAPPED (C function)
PyArray_ISNUMBER (C function)
PyArray_ISOBJECT (C function)
PyArray_ISONESEGMENT (C function)
PyArray_ISPYTHON (C function)
PyArray_IsPythonScalar (C function)
PyArray_IsScalar (C function)
PyArray_ISSIGNED (C function)
PyArray_ISSTRING (C function)
PyArray_ISUNSIGNED (C function)
PyArray_ISUSERDEF (C function)
PyArray_ISWRITEABLE (C function)
PyArray_IsZeroDim (C function)
PyArray_Item_INCREF (C function)
PyArray_Item_XDECREF (C function)
PyArray_ITEMSIZE (C function)
PyArray_ITER_DATA (C function)
PyArray_ITER_GOTO (C function)
PyArray_ITER_GOTO1D (C function)
PyArray_ITER_NEXT (C function)
PyArray_ITER_NOTDONE (C function)
PyArray_ITER_RESET (C function)
PyArray_IterAllButAxis (C function)
PyArray_IterNew (C function)
PyArray_LexSort (C function)
PyArray_malloc (C function)
PyArray_MatrixProduct (C function)
PyArray_MatrixProduct2 (C function)
PyArray_MAX (C function)
PyArray_Max (C function)
PyArray_Mean (C function)
PyArray_MIN (C function)
PyArray_Min (C function)
PyArray_MinScalarType (C function)
PyArray_MoveInto (C function)
PyArray_MultiIter_DATA (C function)
PyArray_MultiIter_GOTO (C function)
PyArray_MultiIter_GOTO1D (C function)
PyArray_MultiIter_NEXT (C function)
PyArray_MultiIter_NEXTi (C function)
PyArray_MultiIter_NOTDONE (C function)
PyArray_MultiIter_RESET (C function)
PyArray_MultiIterNew (C function)
PyArray_MultiplyIntList (C function)
PyArray_MultiplyList (C function)
PyArray_NBYTES (C function)
PyArray_NDIM (C function)
PyArray_NeighborhoodIterNew (C function)
PyArray_New (C function)
PyArray_NewCopy (C function)
PyArray_NewFromDescr (C function)
PyArray_NewLikeArray (C function)
PyArray_Newshape (C function)
PyArray_Nonzero (C function)
PyArray_ObjectType (C function)
PyArray_One (C function)
PyArray_OrderConverter (C function)
PyArray_OutputConverter (C function)
PyArray_Partition (C function)
PyArray_Prod (C function)
PyArray_PromoteTypes (C function)
PyArray_Ptp (C function)
PyArray_PutMask (C function)
PyArray_PutTo (C function)
PyArray_PyIntAsInt (C function)
PyArray_PyIntAsIntp (C function)
PyArray_Ravel (C function)
PyArray_realloc (C function)
PyArray_REFCOUNT (C function)
PyArray_RegisterCanCast (C function)
PyArray_RegisterCastFunc (C function)
PyArray_RegisterDataType (C function)
PyArray_RemoveSmallest (C function)
PyArray_Repeat (C function)
PyArray_Reshape (C function)
PyArray_Resize (C function)
PyArray_ResultType (C function)
PyArray_Return (C function)
PyArray_Round (C function)
PyArray_SAMESHAPE (C function)
PyArray_Scalar (C function)
PyArray_ScalarAsCtype (C function)
PyArray_ScalarKind (C function)
PyArray_SearchsideConverter (C function)
PyArray_SearchSorted (C function)
PyArray_SetBaseObject (C function)
PyArray_SetField (C function)
PyArray_SETITEM (C function)
PyArray_SetNumericOps (C function)
PyArray_SetStringFunction (C function)
PyArray_SHAPE (C function)
PyArray_SimpleNew (C function), [1]
PyArray_SimpleNewFromData (C function), [1]
PyArray_SimpleNewFromDescr (C function)
PyArray_Size (C function)
PyArray_SIZE (C function)
PyArray_Sort (C function)
PyArray_SortkindConverter (C function)
PyArray_Squeeze (C function)
PyArray_Std (C function)
PyArray_STRIDE (C function)
PyArray_STRIDES (C function)
PyArray_Sum (C function)
PyArray_SwapAxes (C function)
PyArray_TakeFrom (C function)
PyArray_ToFile (C function)
PyArray_ToList (C function)
PyArray_ToScalar (C function)
PyArray_ToString (C function)
PyArray_Trace (C function)
PyArray_Transpose (C function)
PyArray_TYPE (C function)
PyArray_Type (C variable)
PyArray_TypeObjectFromType (C function)
PyArray_TypestrConvert (C function)
PyArray_UpdateFlags (C function)
PyArray_ValidType (C function)
PyArray_View (C function)
PyArray_Where (C function)
PyArray_XDECREF (C function)
PyArray_XDECREF_ERR (C function)
PyArray_Zero (C function)
PyArray_ZEROS (C function)
PyArray_Zeros (C function)
PyArrayDescr_Type (C variable)
PyArrayFlags_Type (C variable)
PyArrayInterface (C type)
PyArrayInterface.PyArrayInterface.data (C member)
PyArrayInterface.PyArrayInterface.descr (C member)
PyArrayInterface.PyArrayInterface.flags (C member)
PyArrayInterface.PyArrayInterface.itemsize (C member)
PyArrayInterface.PyArrayInterface.nd (C member)
PyArrayInterface.PyArrayInterface.shape (C member)
PyArrayInterface.PyArrayInterface.strides (C member)
PyArrayInterface.PyArrayInterface.two (C member)
PyArrayInterface.PyArrayInterface.typekind (C member)
PyArrayIter_Check (C function)
PyArrayIter_Type (C variable)
PyArrayIterObject (C type)
PyArrayIterObject.PyArrayIterObject.ao (C member)
PyArrayIterObject.PyArrayIterObject.backstrides (C member)
PyArrayIterObject.PyArrayIterObject.contiguous (C member)
PyArrayIterObject.PyArrayIterObject.coordinates (C member)
PyArrayIterObject.PyArrayIterObject.dataptr (C member)
PyArrayIterObject.PyArrayIterObject.dims_m1 (C member)
PyArrayIterObject.PyArrayIterObject.factors (C member)
PyArrayIterObject.PyArrayIterObject.index (C member)
PyArrayIterObject.PyArrayIterObject.nd_m1 (C member)
PyArrayIterObject.PyArrayIterObject.size (C member)
PyArrayIterObject.PyArrayIterObject.strides (C member)
PyArrayMapIter_Type (C variable)
PyArrayMultiIter_Type (C variable)
PyArrayMultiIterObject (C type)
PyArrayMultiIterObject.PyArrayMultiIterObject.dimensions (C member)
PyArrayMultiIterObject.PyArrayMultiIterObject.index (C member)
PyArrayMultiIterObject.PyArrayMultiIterObject.iters (C member)
PyArrayMultiIterObject.PyArrayMultiIterObject.nd (C member)
PyArrayMultiIterObject.PyArrayMultiIterObject.numiter (C member)
PyArrayMultiIterObject.PyArrayMultiIterObject.size (C member)
PyArrayMultiIterObject.PyObject_HEAD (C macro)
PyArrayNeighborhoodIter_Next (C function)
PyArrayNeighborhoodIter_Reset (C function)
PyArrayNeighborhoodIter_Type (C variable)
PyArrayNeighborhoodIterObject (C type)
PyArrayObject (C type)
PyArrayObject.base (C member)
PyArrayObject.data (C member)
PyArrayObject.descr (C member)
PyArrayObject.dimensions (C member)
PyArrayObject.flags (C member)
PyArrayObject.nd (C member)
PyArrayObject.PyObject_HEAD (C macro)
PyArrayObject.strides (C member)
PyArrayObject.weakreflist (C member)
PyDataMem_FREE (C function)
PyDataMem_NEW (C function)
PyDataMem_RENEW (C function)
PyDataType_FLAGCHK (C function)
PyDataType_HASFIELDS (C function)
PyDataType_ISBOOL (C function)
PyDataType_ISCOMPLEX (C function)
PyDataType_ISEXTENDED (C function)
PyDataType_ISFLEXIBLE (C function)
PyDataType_ISFLOAT (C function)
PyDataType_ISINTEGER (C function)
PyDataType_ISNUMBER (C function)
PyDataType_ISOBJECT (C function)
PyDataType_ISPYTHON (C function)
PyDataType_ISSIGNED (C function)
PyDataType_ISSTRING (C function)
PyDataType_ISUNSIGNED (C function)
PyDataType_ISUSERDEF (C function)
PyDataType_REFCHK (C function)
PyDimMem_FREE (C function)
PyDimMem_NEW (C function)
PyDimMem_RENEW (C function)
PyModule_AddIntConstant (C function)
PyModule_AddObject (C function)
PyModule_AddStringConstant (C function)
Python Enhancement Proposals
PEP 3118, [1], [2]
PyTypeNum_ISBOOL (C function)
PyTypeNum_ISCOMPLEX (C function)
PyTypeNum_ISEXTENDED (C function)
PyTypeNum_ISFLEXIBLE (C function)
PyTypeNum_ISFLOAT (C function)
PyTypeNum_ISINTEGER (C function)
PyTypeNum_ISNUMBER (C function)
PyTypeNum_ISOBJECT (C function)
PyTypeNum_ISPYTHON (C function)
PyTypeNum_ISSIGNED (C function)
PyTypeNum_ISSTRING (C function)
PyTypeNum_ISUNSIGNED (C function)
PyTypeNum_ISUSERDEF (C function)
PyUFunc_checkfperr (C function)
PyUFunc_clearfperr (C function)
PyUFunc_Loop1d (C type)
PyUFunc_PyFuncData (C type)
PyUFunc_Type (C variable)
PyUFuncLoopObject (C type)
PyUFuncObject (C type)
PyUFuncObject.PyObject_HEAD (C macro)
PyUFuncObject.PyUFuncObject.check_return (C member)
PyUFuncObject.PyUFuncObject.data (C member)
PyUFuncObject.PyUFuncObject.doc (C member)
PyUFuncObject.PyUFuncObject.identity (C member)
PyUFuncObject.PyUFuncObject.iter_flags (C member)
PyUFuncObject.PyUFuncObject.name (C member)
PyUFuncObject.PyUFuncObject.nargs (C member)
PyUFuncObject.PyUFuncObject.nin (C member)
PyUFuncObject.PyUFuncObject.nout (C member)
PyUFuncObject.PyUFuncObject.ntypes (C member)
PyUFuncObject.PyUFuncObject.obj (C member)
PyUFuncObject.PyUFuncObject.op_flags (C member)
PyUFuncObject.PyUFuncObject.ptr (C member)
PyUFuncObject.PyUFuncObject.types (C member)
PyUFuncObject.PyUFuncObject.userloops (C member)
PyUFuncReduceObject (C type)

Q

qr() (in module numpy.linalg)

R

r_ (in module numpy)
rad2deg (in module numpy)
radians (in module numpy)
rand() (in module numpy.matlib)
(in module numpy.random)
(numpy.random.RandomState method)
randint() (in module numpy.random)
(numpy.random.RandomState method)
randn() (in module numpy.matlib)
(in module numpy.random)
(numpy.random.RandomState method)
random() (in module numpy.random)
random_integers() (in module numpy.random)
(numpy.random.RandomState method)
random_sample() (in module numpy.random)
(numpy.random.RandomState method)
RandomState (class in numpy.random)
ranf() (in module numpy.random)
RankWarning
rate() (in module numpy)
ravel (in module numpy.ma)
ravel() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
ravel_multi_index() (in module numpy)
rayleigh() (in module numpy.random)
(numpy.random.RandomState method)
real (numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.generic attribute)
(numpy.ma.MaskType attribute)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.recarray attribute)
(numpy.record attribute)
real() (in module numpy)
real_if_close() (in module numpy)
recarray (class in numpy)
reciprocal (in module numpy)
record
dtype
record (class in numpy)
recordmask (numpy.ma.masked_array attribute)
(numpy.ma.MaskedArray attribute), [1]
red_text() (in module numpy.distutils.misc_util)
reduce
ufunc methods
reduce() (numpy.ufunc method)
reduceat
ufunc methods
reduceat() (numpy.ufunc method)
reference
reference counting, [1]
remainder (in module numpy)
remove_axis() (numpy.nditer method)
remove_multi_index() (numpy.nditer method)
repeat (numpy.ma.masked_array attribute)
(numpy.ma.MaskedArray attribute)
repeat() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
replace() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
repmat() (in module numpy.matlib)
require() (in module numpy)
reset() (numpy.broadcast method)
(numpy.nditer method)
reshape() (in module numpy)
(in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
resize() (in module numpy)
(in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
restoredot() (in module numpy)
result_type() (in module numpy)
rfft() (in module numpy.fft)
rfft2() (in module numpy.fft)
rfftfreq() (in module numpy.fft)
rfftn() (in module numpy.fft)
rfind() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
right_shift (in module numpy)
rindex() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
rint (in module numpy)
rjust() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
roll() (in module numpy)
rollaxis() (in module numpy)
roots() (in module numpy)
(numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
rot90() (in module numpy)
round() (in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
round_() (in module numpy)
row-major, [1]
row_stack (in module numpy.ma)
rpartition() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
rsplit() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
rstrip() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
run_module_suite() (in module numpy.testing)
rundocs() (in module numpy.testing)

S

s_ (in module numpy)
sample() (in module numpy.random)
save() (in module numpy)
savetxt() (in module numpy)
savez() (in module numpy)
savez_compressed() (in module numpy)
scalar
dtype
sctype2char() (in module numpy)
searchsorted() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
seed() (in module numpy.random)
(numpy.random.RandomState method)
select() (in module numpy)
self
set_fill_value() (in module numpy.ma)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
set_printoptions() (in module numpy)
set_state() (in module numpy.random)
(numpy.random.RandomState method)
set_string_function() (in module numpy)
set_verbosity() (in module numpy.distutils.log)
setastest() (in module numpy.testing.decorators)
setbufsize() (in module numpy)
setdiff1d() (in module numpy)
seterr() (in module numpy)
seterrcall() (in module numpy)
seterrobj() (in module numpy)
setfield() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
setflags() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
setslice
ndarray special methods
setxor1d() (in module numpy)
shape (numpy.broadcast attribute)
(numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.dtype attribute)
(numpy.generic attribute)
(numpy.ma.MaskType attribute)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.nditer attribute)
(numpy.recarray attribute)
(numpy.record attribute)
shape() (in module numpy.ma)
sharedmask (numpy.ma.masked_array attribute)
(numpy.ma.MaskedArray attribute)
shrink_mask() (numpy.ma.masked_array method)
(numpy.ma.MaskedArray method)
shuffle() (in module numpy.random)
(numpy.random.RandomState method)
sign (in module numpy)
signbit (in module numpy)
sin (in module numpy)
sinc() (in module numpy)
single-segment
sinh (in module numpy)
SIP
size (numpy.broadcast attribute)
(numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.generic attribute)
(numpy.ma.MaskType attribute)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.recarray attribute)
(numpy.record attribute)
size() (in module numpy.ma)
skipif() (in module numpy.testing.decorators)
slice
slicing
slogdet() (in module numpy.linalg)
slow() (in module numpy.testing.decorators)
soften_mask (in module numpy.ma)
soften_mask() (numpy.ma.masked_array method)
(numpy.ma.MaskedArray method)
solve() (in module numpy.linalg)
sort() (in module numpy)
(in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
sort_complex() (in module numpy)
source() (in module numpy)
special methods
getslice, ndarray
setslice, ndarray
split() (in module numpy)
(in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
splitlines() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
sqrt (in module numpy)
square (in module numpy)
squeeze (numpy.ma.masked_array attribute)
(numpy.ma.MaskedArray attribute)
squeeze() (in module numpy)
(in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
standard_cauchy() (in module numpy.random)
(numpy.random.RandomState method)
standard_exponential() (in module numpy.random)
(numpy.random.RandomState method)
standard_gamma() (in module numpy.random)
(numpy.random.RandomState method)
standard_normal() (in module numpy.random)
(numpy.random.RandomState method)
standard_t() (in module numpy.random)
(numpy.random.RandomState method)
startswith() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
std (in module numpy.ma)
std() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
str (numpy.dtype attribute)
stride
strides (numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.generic attribute)
(numpy.ma.MaskType attribute)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.recarray attribute)
(numpy.record attribute)
strip() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
sub-array
dtype, [1]
subdtype (numpy.dtype attribute)
subtract (in module numpy)
subtyping
ndarray, [1]
sum (in module numpy.ma)
sum() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
svd() (in module numpy.linalg)
swapaxes (in module numpy.ma)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
swapaxes() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
swapcase() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
swig

T

T (numpy.chararray attribute)
(numpy.core.defchararray.chararray attribute)
(numpy.generic attribute)
(numpy.ma.MaskType attribute)
(numpy.ma.MaskedArray attribute)
(numpy.ma.masked_array attribute)
(numpy.matrix attribute)
(numpy.memmap attribute)
(numpy.ndarray attribute)
(numpy.recarray attribute)
(numpy.record attribute)
take() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
tan (in module numpy)
tanh (in module numpy)
tensordot() (in module numpy)
tensorinv() (in module numpy.linalg)
tensorsolve() (in module numpy.linalg)
terminal_has_colors() (in module numpy.distutils.misc_util)
test() (numpy.testing.Tester method)
Tester (in module numpy.testing)
tile() (in module numpy)
title() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
tobytes() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
todict() (numpy.distutils.misc_util.Configuration method)
tofile() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
toflex() (numpy.ma.masked_array method)
(numpy.ma.MaskedArray method)
tolist() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
tomaxint() (numpy.random.RandomState method)
torecords() (numpy.ma.masked_array method)
(numpy.ma.MaskedArray method)
tostring() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.lib.user_array.container method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
trace (in module numpy.ma)
trace() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
translate() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
transpose (numpy.ma.masked_array attribute)
(numpy.ma.MaskedArray attribute)
transpose() (in module numpy)
(in module numpy.ma)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
trapz() (in module numpy)
tri() (in module numpy)
triangular() (in module numpy.random)
(numpy.random.RandomState method)
tril() (in module numpy)
tril_indices() (in module numpy)
tril_indices_from() (in module numpy)
trim() (numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
trim_zeros() (in module numpy)
triu() (in module numpy)
triu_indices() (in module numpy)
triu_indices_from() (in module numpy)
true_divide (in module numpy)
trunc (in module numpy)
truncate() (numpy.polynomial.chebyshev.Chebyshev method)
(numpy.polynomial.hermite.Hermite method)
(numpy.polynomial.hermite_e.HermiteE method)
(numpy.polynomial.laguerre.Laguerre method)
(numpy.polynomial.legendre.Legendre method)
(numpy.polynomial.polynomial.Polynomial method)
tuple
type (numpy.dtype attribute)
typename() (in module numpy)
types (numpy.ufunc attribute)

U

ufunc, [1], [2]
C-API, [1]
adding new, [1], [2], [3], [4]
attributes
casting rules
keyword arguments
methods
methods accumulate
methods reduce
methods reduceat
UFUNC_CHECK_ERROR (C function)
UFUNC_CHECK_STATUS (C function)
uniform() (in module numpy.random)
(numpy.random.RandomState method)
union1d() (in module numpy)
unique() (in module numpy)
unpackbits() (in module numpy)
unravel_index() (in module numpy)
unshare_mask() (numpy.ma.masked_array method)
(numpy.ma.MaskedArray method)
unwrap() (in module numpy)
upper() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
user_array

V

value (numpy.nditer attribute)
vander() (in module numpy)
(in module numpy.ma)
var (in module numpy.ma)
var() (in module numpy)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
variable (numpy.poly1d attribute)
vdot() (in module numpy)
vectorize (class in numpy)
view, [1]
ndarray
view() (numpy.chararray method)
(numpy.core.defchararray.chararray method)
(numpy.generic method)
(numpy.ma.MaskType method)
(numpy.ma.MaskedArray method)
(numpy.ma.masked_array method)
(numpy.matrix method)
(numpy.memmap method)
(numpy.ndarray method)
(numpy.recarray method)
(numpy.record method)
vonmises() (in module numpy.random)
(numpy.random.RandomState method)
vsplit() (in module numpy)
vstack (in module numpy.ma)
vstack() (in module numpy)

W

wald() (in module numpy.random)
(numpy.random.RandomState method)
weekmask (numpy.busdaycalendar attribute)
weibull() (in module numpy.random)
(numpy.random.RandomState method)
where() (in module numpy)
(in module numpy.ma)
window (numpy.polynomial.chebyshev.Chebyshev attribute)
(numpy.polynomial.hermite.Hermite attribute)
(numpy.polynomial.hermite_e.HermiteE attribute)
(numpy.polynomial.laguerre.Laguerre attribute)
(numpy.polynomial.legendre.Legendre attribute)
(numpy.polynomial.polynomial.Polynomial attribute)
wrapper

Y

yellow_text() (in module numpy.distutils.misc_util)

Z

zeros (in module numpy.ma)
zeros() (in module numpy)
(in module numpy.matlib)
zeros_like() (in module numpy)
zfill() (in module numpy.core.defchararray)
(numpy.chararray method)
(numpy.core.defchararray.chararray method)
zipf() (in module numpy.random)
(numpy.random.RandomState method)


Two and three dots in difference specs

Thanks to Yarik Halchenko for this explanation.

Imagine a series of commits A, B, C, D... Imagine that there are two branches, topic and master. You branched topic off master when master was at commit ‘E’. The graph of the commits looks like this:

     A---B---C topic
     /
D---E---F---G master

Then:

git diff master..topic

will output the difference from G to C (i.e. with effects of F and G), while:

git diff master...topic

would output just differences in the topic branch (i.e. only A, B, and C).


Numarray compatibility

The numarray module was removed in Numpy 1.9.


Old Numeric compatibility

The oldnumeric module was removed in Numpy 1.9.0.


numpy.broadcast.nd

broadcast.nd

Number of dimensions of broadcasted result.

Examples

>>> x = np.array([1, 2, 3])
>>> y = np.array([[4], [5], [6]])
>>> b = np.broadcast(x, y)
>>> b.nd
2


numpy.broadcast.numiter

broadcast.numiter

Number of iterators possessed by the broadcasted result.

Examples

>>> x = np.array([1, 2, 3])
>>> y = np.array([[4], [5], [6]])
>>> b = np.broadcast(x, y)
>>> b.numiter
2


numpy.chararray.all

chararray.all(axis=None, out=None)

Returns True if all elements evaluate to True.

Refer to numpy.all for full documentation.

See also

numpy.all
equivalent function


numpy.chararray.any

chararray.any(axis=None, out=None)

Returns True if any of the elements of a evaluate to True.

Refer to numpy.any for full documentation.

See also

numpy.any
equivalent function


numpy.chararray.argmax

chararray.argmax(axis=None, out=None)

Return indices of the maximum values along the given axis.

Refer to numpy.argmax for full documentation.

See also

numpy.argmax
equivalent function


numpy.chararray.argmin

chararray.argmin(axis=None, out=None)

Return indices of the minimum values along the given axis of a.

Refer to numpy.argmin for detailed documentation.

See also

numpy.argmin
equivalent function


numpy.chararray.argpartition

chararray.argpartition(kth, axis=-1, kind='introselect', order=None)

Returns the indices that would partition this array.

Refer to numpy.argpartition for full documentation.

New in version 1.8.0.

See also

numpy.argpartition
equivalent function


numpy.chararray.argsort

chararray.argsort(axis=-1, kind='quicksort', order=None) [source]


numpy.chararray.byteswap

chararray.byteswap(inplace)

Swap the bytes of the array elements

Toggle between low-endian and big-endian data representation by returning a byteswapped array, optionally swapped in-place.

Parameters:

inplace : bool, optional

If True, swap bytes in-place, default is False.
Returns:

out : ndarray

The byteswapped array. If inplace is True, this is a view to self.

Examples

>>> A = np.array([1, 256, 8755], dtype=np.int16)
>>> map(hex, A)
['0x1', '0x100', '0x2233']
>>> A.byteswap(True)
array([  256,     1, 13090], dtype=int16)
>>> map(hex, A)
['0x100', '0x1', '0x3322']

Arrays of strings are not swapped

>>> A = np.array(['ceg', 'fac'])
>>> A.byteswap()
array(['ceg', 'fac'],
      dtype='|S3')


numpy.chararray.capitalize

chararray.capitalize() [source]

Return a copy of self with only the first character of each element capitalized.

See also

char.capitalize


numpy.chararray.center

chararray.center(width, fillchar=' ') [source]

Return a copy of self with its elements centered in a string of length width.

See also

center


numpy.chararray.choose

chararray.choose(choices, out=None, mode='raise')

Use an index array to construct a new array from a set of choices.

Refer to numpy.choose for full documentation.

See also

numpy.choose
equivalent function


numpy.chararray.clip

chararray.clip(a_min, a_max, out=None)

Return an array whose values are limited to [a_min, a_max].

Refer to numpy.clip for full documentation.

See also

numpy.clip
equivalent function


numpy.chararray.compress

chararray.compress(condition, axis=None, out=None)

Return selected slices of this array along given axis.

Refer to numpy.compress for full documentation.

See also

numpy.compress
equivalent function


numpy.chararray.conj

chararray.conj()

Complex-conjugate all elements.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.chararray.conjugate

chararray.conjugate()

Return the complex conjugate, element-wise.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.chararray.cumprod

chararray.cumprod(axis=None, dtype=None, out=None)

Return the cumulative product of the elements along the given axis.

Refer to numpy.cumprod for full documentation.

See also

numpy.cumprod
equivalent function


numpy.chararray.cumsum

chararray.cumsum(axis=None, dtype=None, out=None)

Return the cumulative sum of the elements along the given axis.

Refer to numpy.cumsum for full documentation.

See also

numpy.cumsum
equivalent function


numpy.chararray.diagonal

chararray.diagonal(offset=0, axis1=0, axis2=1)

Return specified diagonals. In NumPy 1.9 the returned array is a read-only view instead of a copy as in previous NumPy versions. In NumPy 1.10 the read-only restriction will be removed.

Refer to numpy.diagonal for full documentation.

See also

numpy.diagonal
equivalent function


numpy.chararray.dot

chararray.dot(b, out=None)

Dot product of two arrays.

Refer to numpy.dot for full documentation.

See also

numpy.dot
equivalent function

Examples

>>> a = np.eye(2)
>>> b = np.ones((2, 2)) * 2
>>> a.dot(b)
array([[ 2.,  2.],
       [ 2.,  2.]])

This array method can be conveniently chained:

>>> a.dot(b).dot(b)
array([[ 8.,  8.],
       [ 8.,  8.]])


numpy.chararray.itemset

chararray.itemset(*args)

Insert scalar into an array (scalar is cast to array’s dtype, if possible)

There must be at least 1 argument, and define the last argument as item. Then, a.itemset(*args) is equivalent to but faster than a[args] = item. The item should be a scalar value and args must select a single item in the array a.

Parameters:

*args : Arguments

If one argument: a scalar, only used in case a is of size 1. If two arguments: the last argument is the value to be set and must be a scalar, the first argument specifies a single array element location. It is either an int or a tuple.

Notes

Compared to indexing syntax, itemset provides some speed increase for placing a scalar into a particular location in an ndarray, if you must do this. However, generally this is discouraged: among other problems, it complicates the appearance of the code. Also, when using itemset (and item) inside a loop, be sure to assign the methods to a local variable to avoid the attribute look-up at each loop iteration.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.itemset(4, 0)
>>> x.itemset((2, 2), 9)
>>> x
array([[3, 1, 7],
       [2, 0, 3],
       [8, 5, 9]])


numpy.chararray.max

chararray.max(axis=None, out=None)

Return the maximum along a given axis.

Refer to numpy.amax for full documentation.

See also

numpy.amax
equivalent function


numpy.chararray.mean

chararray.mean(axis=None, dtype=None, out=None)

Returns the average of the array elements along given axis.

Refer to numpy.mean for full documentation.

See also

numpy.mean
equivalent function


numpy.chararray.min

chararray.min(axis=None, out=None)

Return the minimum along a given axis.

Refer to numpy.amin for full documentation.

See also

numpy.amin
equivalent function


numpy.chararray.newbyteorder

chararray.newbyteorder(new_order='S')

Return the array with the same data viewed with a different byte order.

Equivalent to:

arr.view(arr.dtype.newbytorder(new_order))

Changes are also made in all fields and sub-arrays of the array data type.

Parameters:

new_order : string, optional

Byte order to force; a value from the byte order specifications above. new_order codes can be any of:

* 'S' - swap dtype from current to opposite endian
* {'<', 'L'} - little endian
* {'>', 'B'} - big endian
* {'=', 'N'} - native order
* {'|', 'I'} - ignore (no change to byte order)

The default value (‘S’) results in swapping the current byte order. The code does a case-insensitive check on the first letter of new_order for the alternatives above. For example, any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns:

new_arr : array

New array object with the dtype reflecting given change to the byte order.


numpy.chararray.partition

chararray.partition(sep) [source]

Partition each element in self around sep.

See also

partition


numpy.chararray.prod

chararray.prod(axis=None, dtype=None, out=None)

Return the product of the array elements over the given axis

Refer to numpy.prod for full documentation.

See also

numpy.prod
equivalent function


numpy.chararray.ptp

chararray.ptp(axis=None, out=None)

Peak to peak (maximum - minimum) value along a given axis.

Refer to numpy.ptp for full documentation.

See also

numpy.ptp
equivalent function


numpy.chararray.round

chararray.round(decimals=0, out=None)

Return a with each element rounded to the given number of decimals.

Refer to numpy.around for full documentation.

See also

numpy.around
equivalent function


numpy.chararray.rpartition

chararray.rpartition(sep) [source]

Partition each element in self around sep.

See also

rpartition


numpy.chararray.std

chararray.std(axis=None, dtype=None, out=None, ddof=0)

Returns the standard deviation of the array elements along given axis.

Refer to numpy.std for full documentation.

See also

numpy.std
equivalent function


numpy.chararray.sum

chararray.sum(axis=None, dtype=None, out=None)

Return the sum of the array elements over the given axis.

Refer to numpy.sum for full documentation.

See also

numpy.sum
equivalent function


numpy.chararray.tobytes

chararray.tobytes(order='C')

Construct Python bytes containing the raw data bytes in the array.

Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.

New in version 1.9.0.

Parameters:

order : {‘C’, ‘F’, None}, optional

Order of the data for multidimensional arrays: C, Fortran, or the same as for the original array.
Returns:

s : bytes

Python bytes exhibiting a copy of a‘s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]])
>>> x.tobytes()
b'\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x03\x00\x00\x00'


numpy.chararray.trace

chararray.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)

Return the sum along diagonals of the array.

Refer to numpy.trace for full documentation.

See also

numpy.trace
equivalent function


numpy.chararray.var

chararray.var(axis=None, dtype=None, out=None, ddof=0)

Returns the variance of the array elements, along given axis.

Refer to numpy.var for full documentation.

See also

numpy.var
equivalent function


numpy.core.defchararray.chararray.all

chararray.all(axis=None, out=None)

Returns True if all elements evaluate to True.

Refer to numpy.all for full documentation.

See also

numpy.all
equivalent function


numpy.core.defchararray.chararray.any

chararray.any(axis=None, out=None)

Returns True if any of the elements of a evaluate to True.

Refer to numpy.any for full documentation.

See also

numpy.any
equivalent function


numpy.core.defchararray.chararray.argmax

chararray.argmax(axis=None, out=None)

Return indices of the maximum values along the given axis.

Refer to numpy.argmax for full documentation.

See also

numpy.argmax
equivalent function


numpy.core.defchararray.chararray.argmin

chararray.argmin(axis=None, out=None)

Return indices of the minimum values along the given axis of a.

Refer to numpy.argmin for detailed documentation.

See also

numpy.argmin
equivalent function


numpy.core.defchararray.chararray.argpartition

chararray.argpartition(kth, axis=-1, kind='introselect', order=None)

Returns the indices that would partition this array.

Refer to numpy.argpartition for full documentation.

New in version 1.8.0.

See also

numpy.argpartition
equivalent function


numpy.core.defchararray.chararray.argsort

chararray.argsort(axis=-1, kind='quicksort', order=None) [source]


numpy.core.defchararray.chararray.byteswap

chararray.byteswap(inplace)

Swap the bytes of the array elements

Toggle between low-endian and big-endian data representation by returning a byteswapped array, optionally swapped in-place.

Parameters:

inplace : bool, optional

If True, swap bytes in-place, default is False.
Returns:

out : ndarray

The byteswapped array. If inplace is True, this is a view to self.

Examples

>>> A = np.array([1, 256, 8755], dtype=np.int16)
>>> map(hex, A)
['0x1', '0x100', '0x2233']
>>> A.byteswap(True)
array([  256,     1, 13090], dtype=int16)
>>> map(hex, A)
['0x100', '0x1', '0x3322']

Arrays of strings are not swapped

>>> A = np.array(['ceg', 'fac'])
>>> A.byteswap()
array(['ceg', 'fac'],
      dtype='|S3')


numpy.core.defchararray.chararray.capitalize

chararray.capitalize() [source]

Return a copy of self with only the first character of each element capitalized.

See also

char.capitalize


numpy.core.defchararray.chararray.center

chararray.center(width, fillchar=' ') [source]

Return a copy of self with its elements centered in a string of length width.

See also

center


numpy.core.defchararray.chararray.choose

chararray.choose(choices, out=None, mode='raise')

Use an index array to construct a new array from a set of choices.

Refer to numpy.choose for full documentation.

See also

numpy.choose
equivalent function


numpy.core.defchararray.chararray.clip

chararray.clip(a_min, a_max, out=None)

Return an array whose values are limited to [a_min, a_max].

Refer to numpy.clip for full documentation.

See also

numpy.clip
equivalent function


numpy.core.defchararray.chararray.compress

chararray.compress(condition, axis=None, out=None)

Return selected slices of this array along given axis.

Refer to numpy.compress for full documentation.

See also

numpy.compress
equivalent function


numpy.core.defchararray.chararray.conj

chararray.conj()

Complex-conjugate all elements.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.core.defchararray.chararray.conjugate

chararray.conjugate()

Return the complex conjugate, element-wise.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.core.defchararray.chararray.cumprod

chararray.cumprod(axis=None, dtype=None, out=None)

Return the cumulative product of the elements along the given axis.

Refer to numpy.cumprod for full documentation.

See also

numpy.cumprod
equivalent function


numpy.core.defchararray.chararray.cumsum

chararray.cumsum(axis=None, dtype=None, out=None)

Return the cumulative sum of the elements along the given axis.

Refer to numpy.cumsum for full documentation.

See also

numpy.cumsum
equivalent function


numpy.core.defchararray.chararray.diagonal

chararray.diagonal(offset=0, axis1=0, axis2=1)

Return specified diagonals. In NumPy 1.9 the returned array is a read-only view instead of a copy as in previous NumPy versions. In NumPy 1.10 the read-only restriction will be removed.

Refer to numpy.diagonal for full documentation.

See also

numpy.diagonal
equivalent function


numpy.core.defchararray.chararray.dot

chararray.dot(b, out=None)

Dot product of two arrays.

Refer to numpy.dot for full documentation.

See also

numpy.dot
equivalent function

Examples

>>> a = np.eye(2)
>>> b = np.ones((2, 2)) * 2
>>> a.dot(b)
array([[ 2.,  2.],
       [ 2.,  2.]])

This array method can be conveniently chained:

>>> a.dot(b).dot(b)
array([[ 8.,  8.],
       [ 8.,  8.]])


numpy.core.defchararray.chararray.itemset

chararray.itemset(*args)

Insert scalar into an array (scalar is cast to array’s dtype, if possible)

There must be at least 1 argument, and define the last argument as item. Then, a.itemset(*args) is equivalent to but faster than a[args] = item. The item should be a scalar value and args must select a single item in the array a.

Parameters:

*args : Arguments

If one argument: a scalar, only used in case a is of size 1. If two arguments: the last argument is the value to be set and must be a scalar, the first argument specifies a single array element location. It is either an int or a tuple.

Notes

Compared to indexing syntax, itemset provides some speed increase for placing a scalar into a particular location in an ndarray, if you must do this. However, generally this is discouraged: among other problems, it complicates the appearance of the code. Also, when using itemset (and item) inside a loop, be sure to assign the methods to a local variable to avoid the attribute look-up at each loop iteration.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.itemset(4, 0)
>>> x.itemset((2, 2), 9)
>>> x
array([[3, 1, 7],
       [2, 0, 3],
       [8, 5, 9]])


numpy.core.defchararray.chararray.max

chararray.max(axis=None, out=None)

Return the maximum along a given axis.

Refer to numpy.amax for full documentation.

See also

numpy.amax
equivalent function


numpy.core.defchararray.chararray.mean

chararray.mean(axis=None, dtype=None, out=None)

Returns the average of the array elements along given axis.

Refer to numpy.mean for full documentation.

See also

numpy.mean
equivalent function


numpy.core.defchararray.chararray.min

chararray.min(axis=None, out=None)

Return the minimum along a given axis.

Refer to numpy.amin for full documentation.

See also

numpy.amin
equivalent function


numpy.core.defchararray.chararray.newbyteorder

chararray.newbyteorder(new_order='S')

Return the array with the same data viewed with a different byte order.

Equivalent to:

arr.view(arr.dtype.newbytorder(new_order))

Changes are also made in all fields and sub-arrays of the array data type.

Parameters:

new_order : string, optional

Byte order to force; a value from the byte order specifications above. new_order codes can be any of:

* 'S' - swap dtype from current to opposite endian
* {'<', 'L'} - little endian
* {'>', 'B'} - big endian
* {'=', 'N'} - native order
* {'|', 'I'} - ignore (no change to byte order)

The default value (‘S’) results in swapping the current byte order. The code does a case-insensitive check on the first letter of new_order for the alternatives above. For example, any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns:

new_arr : array

New array object with the dtype reflecting given change to the byte order.


numpy.core.defchararray.chararray.partition

chararray.partition(sep) [source]

Partition each element in self around sep.

See also

partition


numpy.core.defchararray.chararray.prod

chararray.prod(axis=None, dtype=None, out=None)

Return the product of the array elements over the given axis

Refer to numpy.prod for full documentation.

See also

numpy.prod
equivalent function


numpy.core.defchararray.chararray.ptp

chararray.ptp(axis=None, out=None)

Peak to peak (maximum - minimum) value along a given axis.

Refer to numpy.ptp for full documentation.

See also

numpy.ptp
equivalent function


numpy.core.defchararray.chararray.round

chararray.round(decimals=0, out=None)

Return a with each element rounded to the given number of decimals.

Refer to numpy.around for full documentation.

See also

numpy.around
equivalent function


numpy.core.defchararray.chararray.rpartition

chararray.rpartition(sep) [source]

Partition each element in self around sep.

See also

rpartition


numpy.core.defchararray.chararray.std

chararray.std(axis=None, dtype=None, out=None, ddof=0)

Returns the standard deviation of the array elements along given axis.

Refer to numpy.std for full documentation.

See also

numpy.std
equivalent function


numpy.core.defchararray.chararray.sum

chararray.sum(axis=None, dtype=None, out=None)

Return the sum of the array elements over the given axis.

Refer to numpy.sum for full documentation.

See also

numpy.sum
equivalent function


numpy.core.defchararray.chararray.tobytes

chararray.tobytes(order='C')

Construct Python bytes containing the raw data bytes in the array.

Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.

New in version 1.9.0.

Parameters:

order : {‘C’, ‘F’, None}, optional

Order of the data for multidimensional arrays: C, Fortran, or the same as for the original array.
Returns:

s : bytes

Python bytes exhibiting a copy of a‘s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]])
>>> x.tobytes()
b'\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x03\x00\x00\x00'


numpy.core.defchararray.chararray.trace

chararray.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)

Return the sum along diagonals of the array.

Refer to numpy.trace for full documentation.

See also

numpy.trace
equivalent function


numpy.core.defchararray.chararray.var

chararray.var(axis=None, dtype=None, out=None, ddof=0)

Returns the variance of the array elements, along given axis.

Refer to numpy.var for full documentation.

See also

numpy.var
equivalent function


numpy.flatiter.base

flatiter.base

A reference to the array that is iterated over.

Examples

>>> x = np.arange(5)
>>> fl = x.flat
>>> fl.base is x
True


numpy.flatiter.index

flatiter.index

Current flat index into the array.

Examples

>>> x = np.arange(6).reshape(2, 3)
>>> fl = x.flat
>>> fl.index
0
>>> fl.next()
0
>>> fl.index
1


numpy.ma.masked_array.all

masked_array.all(axis=None, out=None) [source]

Check if all of the elements of a are true.

Performs a logical_and over the given axis and returns the result. Masked values are considered as True during computation. For convenience, the output array is masked where ALL the values along the current axis are masked: if the output would have been a scalar and that all the values are masked, then the output is masked.

Parameters:

axis : {None, integer}

Axis to perform the operation over. If None, perform over flattened array.

out : {None, array}, optional

Array into which the result can be placed. Its type is preserved and it must be of the right shape to hold the output.

See also

all
equivalent function

Examples

>>> np.ma.array([1,2,3]).all()
True
>>> a = np.ma.array([1,2,3], mask=True)
>>> (a.all() is np.ma.masked)
True


numpy.ma.masked_array.anom

masked_array.anom(axis=None, dtype=None) [source]

Compute the anomalies (deviations from the arithmetic mean) along the given axis.

Returns an array of anomalies, with the same shape as the input and where the arithmetic mean is computed along the given axis.

Parameters:

axis : int, optional

Axis over which the anomalies are taken. The default is to use the mean of the flattened array as reference.

dtype : dtype, optional

Type to use in computing the variance. For arrays of integer type

the default is float32; for arrays of float types it is the same as the array type.

See also

mean
Compute the mean of the array.

Examples

>>> a = np.ma.array([1,2,3])
>>> a.anom()
masked_array(data = [-1.  0.  1.],
             mask = False,
       fill_value = 1e+20)


numpy.ma.masked_array.any

masked_array.any(axis=None, out=None) [source]

Check if any of the elements of a are true.

Performs a logical_or over the given axis and returns the result. Masked values are considered as False during computation.

Parameters:

axis : {None, integer}

Axis to perform the operation over. If None, perform over flattened array and return a scalar.

out : {None, array}, optional

Array into which the result can be placed. Its type is preserved and it must be of the right shape to hold the output.

See also

any
equivalent function


numpy.ma.masked_array.argmax

masked_array.argmax(axis=None, fill_value=None, out=None) [source]

Returns array of indices of the maximum values along the given axis. Masked values are treated as if they had the value fill_value.

Parameters:

axis : {None, integer}

If None, the index is into the flattened array, otherwise along the specified axis

fill_value : {var}, optional

Value used to fill in the masked values. If None, the output of maximum_fill_value(self._data) is used instead.

out : {None, array}, optional

Array into which the result can be placed. Its type is preserved and it must be of the right shape to hold the output.
Returns:

index_array : {integer_array}

Examples

>>> a = np.arange(6).reshape(2,3)
>>> a.argmax()
5
>>> a.argmax(0)
array([1, 1, 1])
>>> a.argmax(1)
array([2, 2])


numpy.ma.masked_array.argmin

masked_array.argmin(axis=None, fill_value=None, out=None) [source]

Return array of indices to the minimum values along the given axis.

Parameters:

axis : {None, integer}

If None, the index is into the flattened array, otherwise along the specified axis

fill_value : {var}, optional

Value used to fill in the masked values. If None, the output of minimum_fill_value(self._data) is used instead.

out : {None, array}, optional

Array into which the result can be placed. Its type is preserved and it must be of the right shape to hold the output.
Returns:

{ndarray, scalar}

If multi-dimension input, returns a new ndarray of indices to the minimum values along the given axis. Otherwise, returns a scalar of index to the minimum values along the given axis.

Examples

>>> x = np.ma.array(arange(4), mask=[1,1,0,0])
>>> x.shape = (2,2)
>>> print x
[[-- --]
 [2 3]]
>>> print x.argmin(axis=0, fill_value=-1)
[0 0]
>>> print x.argmin(axis=0, fill_value=9)
[1 1]


numpy.ma.masked_array.argpartition

masked_array.argpartition(kth, axis=-1, kind='introselect', order=None)

Returns the indices that would partition this array.

Refer to numpy.argpartition for full documentation.

New in version 1.8.0.

See also

numpy.argpartition
equivalent function


numpy.ma.masked_array.argsort

masked_array.argsort(axis=None, kind='quicksort', order=None, fill_value=None) [source]

Return an ndarray of indices that sort the array along the specified axis. Masked values are filled beforehand to fill_value.

Parameters:

axis : int, optional

Axis along which to sort. The default is -1 (last axis). If None, the flattened array is used.

fill_value : var, optional

Value used to fill the array before sorting. The default is the fill_value attribute of the input array.

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.
Returns:

index_array : ndarray, int

Array of indices that sort a along the specified axis. In other words, a[index_array] yields a sorted a.

See also

sort
Describes sorting algorithms used.
lexsort
Indirect stable sort with multiple keys.
ndarray.sort
Inplace sort.

Notes

See sort for notes on the different sorting algorithms.

Examples

>>> a = np.ma.array([3,2,1], mask=[False, False, True])
>>> a
masked_array(data = [3 2 --],
             mask = [False False  True],
       fill_value = 999999)
>>> a.argsort()
array([1, 0, 2])


numpy.ma.masked_array.astype

masked_array.astype(newtype) [source]

Returns a copy of the MaskedArray cast to given newtype.

Returns:

output : MaskedArray

A copy of self cast to input newtype. The returned record shape matches self.shape.

Examples

>>> x = np.ma.array([[1,2,3.1],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1.0 -- 3.1]
 [-- 5.0 --]
 [7.0 -- 9.0]]
>>> print x.astype(int32)
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]


numpy.ma.masked_array.base

masked_array.base

Base object if memory is from some other object.

Examples

The base of an array that owns its memory is None:

>>> x = np.array([1,2,3,4])
>>> x.base is None
True

Slicing creates a view, whose memory is shared with x:

>>> y = x[2:]
>>> y.base is x
True


numpy.ma.masked_array.baseclass

masked_array.baseclass

Class of the underlying data (read-only).


numpy.ma.masked_array.byteswap

masked_array.byteswap(inplace)

Swap the bytes of the array elements

Toggle between low-endian and big-endian data representation by returning a byteswapped array, optionally swapped in-place.

Parameters:

inplace : bool, optional

If True, swap bytes in-place, default is False.
Returns:

out : ndarray

The byteswapped array. If inplace is True, this is a view to self.

Examples

>>> A = np.array([1, 256, 8755], dtype=np.int16)
>>> map(hex, A)
['0x1', '0x100', '0x2233']
>>> A.byteswap(True)
array([  256,     1, 13090], dtype=int16)
>>> map(hex, A)
['0x100', '0x1', '0x3322']

Arrays of strings are not swapped

>>> A = np.array(['ceg', 'fac'])
>>> A.byteswap()
array(['ceg', 'fac'],
      dtype='|S3')


numpy.ma.masked_array.choose

masked_array.choose(choices, out=None, mode='raise')

Use an index array to construct a new array from a set of choices.

Refer to numpy.choose for full documentation.

See also

numpy.choose
equivalent function


numpy.ma.masked_array.clip

masked_array.clip(a_min, a_max, out=None)

Return an array whose values are limited to [a_min, a_max].

Refer to numpy.clip for full documentation.

See also

numpy.clip
equivalent function


numpy.ma.masked_array.compress

masked_array.compress(condition, axis=None, out=None) [source]

Return a where condition is True.

If condition is a MaskedArray, missing values are considered as False.

Parameters:

condition : var

Boolean 1-d array selecting which entries to return. If len(condition) is less than the size of a along the axis, then output is truncated to length of condition array.

axis : {None, int}, optional

Axis along which the operation must be performed.

out : {None, ndarray}, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type will be cast if necessary.
Returns:

result : MaskedArray

A MaskedArray object.

Notes

Please note the difference with compressed ! The output of compress has a mask, the output of compressed does not.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]
>>> x.compress([1, 0, 1])
masked_array(data = [1 3],
      mask = [False False],
      fill_value=999999)

>>> x.compress([1, 0, 1], axis=1)
masked_array(data =
 [[1 3]
 [-- --]
 [7 9]],
      mask =
 [[False False]
 [ True  True]
 [False False]],
      fill_value=999999)


numpy.ma.masked_array.compressed

masked_array.compressed() [source]

Return all the non-masked data as a 1-D array.

Returns:

data : ndarray

A new ndarray holding the non-masked data is returned.

Notes

The result is not a MaskedArray!

Examples

>>> x = np.ma.array(np.arange(5), mask=[0]*2 + [1]*3)
>>> x.compressed()
array([0, 1])
>>> type(x.compressed())
<type 'numpy.ndarray'>


numpy.ma.masked_array.conj

masked_array.conj()

Complex-conjugate all elements.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.ma.masked_array.conjugate

masked_array.conjugate()

Return the complex conjugate, element-wise.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.ma.masked_array.copy

masked_array.copy(order='C')

Return a copy of the array.

Parameters:

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout of the copy. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible. (Note that this function and :func:numpy.copy are very similar, but have different default values for their order= arguments.)

See also

numpy.copy, numpy.copyto

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
       [0, 0, 0]])

>>> y
array([[1, 2, 3],
       [4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True


numpy.ma.masked_array.count

masked_array.count(axis=None) [source]

Count the non-masked elements of the array along the given axis.

Parameters:

axis : int, optional

Axis along which to count the non-masked elements. If axis is None, all non-masked elements are counted.
Returns:

result : int or ndarray

If axis is None, an integer count is returned. When axis is not None, an array with shape determined by the lengths of the remaining axes, is returned.

See also

count_masked
Count masked elements in array or along a given axis.

Examples

>>> import numpy.ma as ma
>>> a = ma.arange(6).reshape((2, 3))
>>> a[1, :] = ma.masked
>>> a
masked_array(data =
 [[0 1 2]
 [-- -- --]],
             mask =
 [[False False False]
 [ True  True  True]],
       fill_value = 999999)
>>> a.count()
3

When the axis keyword is specified an array of appropriate size is returned.

>>> a.count(axis=0)
array([1, 1, 1])
>>> a.count(axis=1)
array([3, 0])


numpy.ma.masked_array.ctypes

masked_array.ctypes

An object to simplify the interaction of the array with the ctypes module.

This attribute creates an object that makes it easier to use arrays when calling shared libraries with the ctypes module. The returned object has, among others, data, shape, and strides attributes (see Notes below) which themselves return ctypes objects that can be used as arguments to a shared library.

Parameters:

None
Returns:

c : Python object

Possessing attributes data, shape, strides, etc.

See also

numpy.ctypeslib

Notes

Below are the public attributes of this object which were documented in “Guide to NumPy” (we have omitted undocumented public attributes, as well as documented private attributes):

  • data: A pointer to the memory area of the array as a Python integer. This memory area may contain data that is not aligned, or not in correct byte-order. The memory area may not even be writeable. The array flags and data-type of this array should be respected when passing this attribute to arbitrary C-code to avoid trouble that can include Python crashing. User Beware! The value of this attribute is exactly the same as self._array_interface_[‘data’][0].
  • shape (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the C-integer corresponding to dtype(‘p’) on this platform. This base-type could be c_int, c_long, or c_longlong depending on the platform. The c_intp type is defined accordingly in numpy.ctypeslib. The ctypes array contains the shape of the underlying array.
  • strides (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the same as for the shape attribute. This ctypes array contains the strides information from the underlying array. This strides information is important for showing how many bytes must be jumped to get to the next element in the array.
  • data_as(obj): Return the data pointer cast to a particular c-types object. For example, calling self._as_parameter_ is equivalent to self.data_as(ctypes.c_void_p). Perhaps you want to use the data as a pointer to a ctypes array of floating-point data: self.data_as(ctypes.POINTER(ctypes.c_double)).
  • shape_as(obj): Return the shape tuple as an array of some other c-types type. For example: self.shape_as(ctypes.c_short).
  • strides_as(obj): Return the strides tuple as an array of some other c-types type. For example: self.strides_as(ctypes.c_longlong).

Be careful using the ctypes attribute - especially on temporary arrays or arrays constructed on the fly. For example, calling (a+b).ctypes.data_as(ctypes.c_void_p) returns a pointer to memory that is invalid because the array created as (a+b) is deallocated before the next Python statement. You can avoid this problem using either c=a+b or ct=(a+b).ctypes. In the latter case, ct will hold a reference to the array until ct is deleted or re-assigned.

If the ctypes module is not available, then the ctypes attribute of array objects still returns something useful, but ctypes objects are not returned and errors may be raised instead. In particular, the object will still have the as parameter attribute which will return an integer equal to the data attribute.

Examples

>>> import ctypes
>>> x
array([[0, 1],
       [2, 3]])
>>> x.ctypes.data
30439712
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long))
<ctypes.LP_c_long object at 0x01F01300>
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long)).contents
c_long(0)
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_longlong)).contents
c_longlong(4294967296L)
>>> x.ctypes.shape
<numpy.core._internal.c_long_Array_2 object at 0x01FFD580>
>>> x.ctypes.shape_as(ctypes.c_long)
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides_as(ctypes.c_longlong)
<numpy.core._internal.c_longlong_Array_2 object at 0x01F01300>


numpy.ma.masked_array.cumprod

masked_array.cumprod(axis=None, dtype=None, out=None) [source]

Return the cumulative product of the elements along the given axis. The cumulative product is taken over the flattened array by default, otherwise over the specified axis.

Masked values are set to 1 internally during the computation. However, their position is saved, and the result will be masked at the same locations.

Parameters:

axis : {None, -1, int}, optional

Axis along which the product is computed. The default (axis = None) is to compute over the flattened array.

dtype : {None, dtype}, optional

Determines the type of the returned array and of the accumulator where the elements are multiplied. If dtype has the value None and the type of a is an integer type of precision less than the default platform integer, then the default platform integer precision is used. Otherwise, the dtype is the same as that of a.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary.
Returns:

cumprod : ndarray

A new array holding the result is returned unless out is specified, in which case a reference to out is returned.

Notes

The mask is lost if out is not a valid MaskedArray !

Arithmetic is modular when using integer types, and no error is raised on overflow.


numpy.ma.masked_array.cumsum

masked_array.cumsum(axis=None, dtype=None, out=None) [source]

Return the cumulative sum of the elements along the given axis. The cumulative sum is calculated over the flattened array by default, otherwise over the specified axis.

Masked values are set to 0 internally during the computation. However, their position is saved, and the result will be masked at the same locations.

Parameters:

axis : {None, -1, int}, optional

Axis along which the sum is computed. The default (axis = None) is to compute over the flattened array. axis may be negative, in which case it counts from the last to the first axis.

dtype : {None, dtype}, optional

Type of the returned array and of the accumulator in which the elements are summed. If dtype is not specified, it defaults to the dtype of a, unless a has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary.
Returns:

cumsum : ndarray.

A new array holding the result is returned unless out is specified, in which case a reference to out is returned.

Notes

The mask is lost if out is not a valid MaskedArray !

Arithmetic is modular when using integer types, and no error is raised on overflow.

Examples

>>> marr = np.ma.array(np.arange(10), mask=[0,0,0,1,1,1,0,0,0,0])
>>> print marr.cumsum()
[0 1 3 -- -- -- 9 16 24 33]


numpy.ma.masked_array.data

masked_array.data

Return the current data, as a view of the original underlying data.


numpy.ma.masked_array.diagonal

masked_array.diagonal(offset=0, axis1=0, axis2=1)

Return specified diagonals. In NumPy 1.9 the returned array is a read-only view instead of a copy as in previous NumPy versions. In NumPy 1.10 the read-only restriction will be removed.

Refer to numpy.diagonal for full documentation.

See also

numpy.diagonal
equivalent function


numpy.ma.masked_array.dot

masked_array.dot(b, out=None)

Dot product of two arrays.

Refer to numpy.dot for full documentation.

See also

numpy.dot
equivalent function

Examples

>>> a = np.eye(2)
>>> b = np.ones((2, 2)) * 2
>>> a.dot(b)
array([[ 2.,  2.],
       [ 2.,  2.]])

This array method can be conveniently chained:

>>> a.dot(b).dot(b)
array([[ 8.,  8.],
       [ 8.,  8.]])


numpy.ma.masked_array.dtype

masked_array.dtype

Data-type of the array’s elements.

Parameters: None
Returns: d : numpy dtype object

See also

numpy.dtype

Examples

>>> x
array([[0, 1],
       [2, 3]])
>>> x.dtype
dtype('int32')
>>> type(x.dtype)
<type 'numpy.dtype'>


numpy.ma.masked_array.dump

masked_array.dump(file)

Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.

Parameters:

file : str

A string naming the dump file.


numpy.ma.masked_array.dumps

masked_array.dumps()

Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an array.

Parameters: None


numpy.ma.masked_array.fill

masked_array.fill(value)

Fill the array with a scalar value.

Parameters:

value : scalar

All elements of a will be assigned this value.

Examples

>>> a = np.array([1, 2])
>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([ 1.,  1.])


numpy.ma.masked_array.fill_value

masked_array.fill_value

Filling value.


numpy.ma.masked_array.filled

masked_array.filled(fill_value=None) [source]

Return a copy of self, with masked values filled with a given value.

Parameters:

fill_value : scalar, optional

The value to use for invalid entries (None by default). If None, the fill_value attribute of the array is used instead.
Returns:

filled_array : ndarray

A copy of self with invalid entries replaced by fill_value (be it the function argument or the attribute of self.

Notes

The result is not a MaskedArray!

Examples

>>> x = np.ma.array([1,2,3,4,5], mask=[0,0,1,0,1], fill_value=-999)
>>> x.filled()
array([1, 2, -999, 4, -999])
>>> type(x.filled())
<type 'numpy.ndarray'>

Subclassing is preserved. This means that if the data part of the masked array is a matrix, filled returns a matrix:

>>> x = np.ma.array(np.matrix([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])
>>> x.filled()
matrix([[     1, 999999],
        [999999,      4]])


numpy.ma.masked_array.flags

masked_array.flags

Information about the memory layout of the array.

Notes

The flags object can be accessed dictionary-like (as in a.flags['WRITEABLE']), or by using lowercased attribute names (as in a.flags.writeable). Short flag names are only supported in dictionary access.

Only the UPDATEIFCOPY, WRITEABLE, and ALIGNED flags can be changed by the user, via direct assignment to the attribute or dictionary entry, or by calling ndarray.setflags.

The array flags cannot be set arbitrarily:

  • UPDATEIFCOPY can only be set False.
  • ALIGNED can only be set True if the data is truly aligned.
  • WRITEABLE can only be set True if the array owns its own memory or the ultimate owner of the memory exposes a writeable buffer interface or is a string.

Arrays can be both C-style and Fortran-style contiguous simultaneously. This is clear for 1-dimensional arrays, but can also be true for higher dimensional arrays.

Even for contiguous arrays a stride for a given dimension arr.strides[dim] may be arbitrary if arr.shape[dim] == 1 or the array has no elements. It does not generally hold that self.strides[-1] == self.itemsize for C-style contiguous arrays or self.strides[0] == self.itemsize for Fortran-style contiguous arrays is true.

Attributes

C_CONTIGUOUS (C) | The data is in a single, C-style contiguous segment.
F_CONTIGUOUS (F) | The data is in a single, Fortran-style contiguous segment.
OWNDATA (O) | The array owns the memory it uses or borrows it from another object.
WRITEABLE (W) | The data area can be written to. Setting this to False locks the data, making it read-only. A view (slice, etc.) inherits WRITEABLE from its base array at creation time, but a view of a writeable array may be subsequently locked while the base array remains writeable. (The opposite is not true, in that a view of a locked array may not be made writeable. However, currently, locking a base object does not lock any views that already reference it, so under that circumstance it is possible to alter the contents of a locked array via a previously created writeable view onto it.) Attempting to change a non-writeable array raises a RuntimeError exception.
ALIGNED (A) | The data and all elements are aligned appropriately for the hardware.
UPDATEIFCOPY (U) | This array is a copy of some other array. When this array is deallocated, the base array will be updated with the contents of this array.
FNC | F_CONTIGUOUS and not C_CONTIGUOUS.
FORC | F_CONTIGUOUS or C_CONTIGUOUS (one-segment test).
BEHAVED (B) | ALIGNED and WRITEABLE.
CARRAY (CA) | BEHAVED and C_CONTIGUOUS.
FARRAY (FA) | BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS.


numpy.ma.masked_array.flat

masked_array.flat

Flat version of the array.


numpy.ma.masked_array.flatten

masked_array.flatten(order='C')

Return a copy of the array collapsed into one dimension.

Parameters:

order : {‘C’, ‘F’, ‘A’}, optional

Whether to flatten in C (row-major), Fortran (column-major) order, or preserve the C/Fortran ordering from a. The default is ‘C’.
Returns:

y : ndarray

A copy of the input array, flattened to one dimension.

See also

ravel
Return a flattened array.
flat
A 1-D flat iterator over the array.

Examples

>>> a = np.array([[1,2], [3,4]])
>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten('F')
array([1, 3, 2, 4])


numpy.ma.masked_array.get_fill_value

masked_array.get_fill_value() [source]

Return the filling value of the masked array.

Returns:

fill_value : scalar

The filling value.

Examples

>>> for dt in [np.int32, np.int64, np.float64, np.complex128]:
...     np.ma.array([0, 1], dtype=dt).get_fill_value()
...
999999
999999
1e+20
(1e+20+0j)

>>> x = np.ma.array([0, 1.], fill_value=-np.inf)
>>> x.get_fill_value()
-inf


numpy.ma.masked_array.get_imag

masked_array.get_imag() [source]

Return the imaginary part of the masked array.

The returned array is a view on the imaginary part of the MaskedArray whose get_imag method is called.

Parameters:

None
Returns:

result : MaskedArray

The imaginary part of the masked array.

See also

get_real, real, imag

Examples

>>> x = np.ma.array([1+1.j, -2j, 3.45+1.6j], mask=[False, True, False])
>>> x.get_imag()
masked_array(data = [1.0 -- 1.6],
             mask = [False  True False],
       fill_value = 1e+20)


numpy.ma.masked_array.get_real

masked_array.get_real() [source]

Return the real part of the masked array.

The returned array is a view on the real part of the MaskedArray whose get_real method is called.

Parameters:

None
Returns:

result : MaskedArray

The real part of the masked array.

See also

get_imag, real, imag

Examples

>>> x = np.ma.array([1+1.j, -2j, 3.45+1.6j], mask=[False, True, False])
>>> x.get_real()
masked_array(data = [1.0 -- 3.45],
             mask = [False  True False],
       fill_value = 1e+20)


numpy.ma.masked_array.getfield

masked_array.getfield(dtype, offset=0)

Returns a field of the given array as a certain type.

A field is a view of the array data with a given data-type. The values in the view are determined by the given type and the offset into the current array in bytes. The offset needs to be such that the view dtype fits in the array dtype; for example an array of dtype complex128 has 16-byte elements. If taking a view with a 32-bit integer (4 bytes), the offset needs to be between 0 and 12 bytes.

Parameters:

dtype : str or dtype

The data type of the view. The dtype size of the view can not be larger than that of the array itself.

offset : int

Number of bytes to skip before beginning the element view.

Examples

>>> x = np.diag([1.+1.j]*2)
>>> x[1, 1] = 2 + 4.j
>>> x
array([[ 1.+1.j,  0.+0.j],
       [ 0.+0.j,  2.+4.j]])
>>> x.getfield(np.float64)
array([[ 1.,  0.],
       [ 0.,  2.]])

By choosing an offset of 8 bytes we can select the complex part of the array for our view:

>>> x.getfield(np.float64, offset=8)
array([[ 1.,  0.],
   [ 0.,  4.]])


numpy.ma.masked_array.harden_mask

masked_array.harden_mask() [source]

Force the mask to hard.

Whether the mask of a masked array is hard or soft is determined by its hardmask property. harden_mask sets hardmask to True.

See also

hardmask


numpy.ma.masked_array.hardmask

masked_array.hardmask

Hardness of the mask


numpy.ma.masked_array.ids

masked_array.ids() [source]

Return the addresses of the data and mask areas.

Parameters: None

Examples

>>> x = np.ma.array([1, 2, 3], mask=[0, 1, 1])
>>> x.ids()
(166670640, 166659832)

If the array has no mask, the address of nomask is returned. This address is typically not close to the data in memory:

>>> x = np.ma.array([1, 2, 3])
>>> x.ids()
(166691080, 3083169284L)


numpy.ma.masked_array.imag

masked_array.imag

Imaginary part.


numpy.ma.masked_array.iscontiguous

masked_array.iscontiguous() [source]

Return a boolean indicating whether the data is contiguous.

Parameters: None

Examples

>>> x = np.ma.array([1, 2, 3])
>>> x.iscontiguous()
True

iscontiguous returns one of the flags of the masked array:

>>> x.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : True
  OWNDATA : False
  WRITEABLE : True
  ALIGNED : True
  UPDATEIFCOPY : False


numpy.ma.masked_array.item

masked_array.item(*args)

Copy an element of an array to a standard Python scalar and return it.

Parameters:

*args : Arguments (variable number and type)

  • none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.
  • int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.
  • tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.
Returns:

z : Standard Python scalar object

A copy of the specified element of the array as a suitable Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.item(3)
2
>>> x.item(7)
5
>>> x.item((0, 1))
1
>>> x.item((2, 2))
3


numpy.ma.masked_array.itemset

masked_array.itemset(*args)

Insert scalar into an array (scalar is cast to array’s dtype, if possible)

There must be at least 1 argument, and define the last argument as item. Then, a.itemset(*args) is equivalent to but faster than a[args] = item. The item should be a scalar value and args must select a single item in the array a.

Parameters:

*args : Arguments

If one argument: a scalar, only used in case a is of size 1. If two arguments: the last argument is the value to be set and must be a scalar, the first argument specifies a single array element location. It is either an int or a tuple.

Notes

Compared to indexing syntax, itemset provides some speed increase for placing a scalar into a particular location in an ndarray, if you must do this. However, generally this is discouraged: among other problems, it complicates the appearance of the code. Also, when using itemset (and item) inside a loop, be sure to assign the methods to a local variable to avoid the attribute look-up at each loop iteration.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.itemset(4, 0)
>>> x.itemset((2, 2), 9)
>>> x
array([[3, 1, 7],
       [2, 0, 3],
       [8, 5, 9]])


numpy.ma.masked_array.itemsize

masked_array.itemsize

Length of one array element in bytes.

Examples

>>> x = np.array([1,2,3], dtype=np.float64)
>>> x.itemsize
8
>>> x = np.array([1,2,3], dtype=np.complex128)
>>> x.itemsize
16


numpy.ma.masked_array.max

masked_array.max(axis=None, out=None, fill_value=None) [source]

Return the maximum along a given axis.

Parameters:

axis : {None, int}, optional

Axis along which to operate. By default, axis is None and the flattened input is used.

out : array_like, optional

Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output.

fill_value : {var}, optional

Value used to fill in the masked values. If None, use the output of maximum_fill_value().
Returns:

amax : array_like

New array holding the result. If out was specified, out is returned.

See also

maximum_fill_value
Returns the maximum filling value for a given datatype.


numpy.ma.masked_array.mean

masked_array.mean(axis=None, dtype=None, out=None) [source]

Returns the average of the array elements.

Masked entries are ignored. The average is taken over the flattened array by default, otherwise over the specified axis. Refer to numpy.mean for the full documentation.

Parameters:

a : array_like

Array containing numbers whose mean is desired. If a is not an array, a conversion is attempted.

axis : int, optional

Axis along which the means are computed. The default is to compute the mean of the flattened array.

dtype : dtype, optional

Type to use in computing the mean. For integer inputs, the default is float64; for floating point, inputs it is the same as the input dtype.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type will be cast if necessary.
Returns:

mean : ndarray, see dtype parameter above

If out=None, returns a new array containing the mean values, otherwise a reference to the output array is returned.

See also

numpy.ma.mean
Equivalent function.
numpy.mean
Equivalent function on non-masked arrays.
numpy.ma.average
Weighted average.

Examples

>>> a = np.ma.array([1,2,3], mask=[False, False, True])
>>> a
masked_array(data = [1 2 --],
             mask = [False False  True],
       fill_value = 999999)
>>> a.mean()
1.5


numpy.ma.masked_array.min

masked_array.min(axis=None, out=None, fill_value=None) [source]

Return the minimum along a given axis.

Parameters:

axis : {None, int}, optional

Axis along which to operate. By default, axis is None and the flattened input is used.

out : array_like, optional

Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output.

fill_value : {var}, optional

Value used to fill in the masked values. If None, use the output of minimum_fill_value.
Returns:

amin : array_like

New array holding the result. If out was specified, out is returned.

See also

minimum_fill_value
Returns the minimum filling value for a given datatype.


numpy.ma.masked_array.mini

masked_array.mini(axis=None) [source]

Return the array minimum along the specified axis.

Parameters:

axis : int, optional

The axis along which to find the minima. Default is None, in which case the minimum value in the whole array is returned.
Returns:

min : scalar or MaskedArray

If axis is None, the result is a scalar. Otherwise, if axis is given and the array is at least 2-D, the result is a masked array with dimension one smaller than the array on which mini is called.

Examples

>>> x = np.ma.array(np.arange(6), mask=[0 ,1, 0, 0, 0 ,1]).reshape(3, 2)
>>> print x
[[0 --]
 [2 3]
 [4 --]]
>>> x.mini()
0
>>> x.mini(axis=0)
masked_array(data = [0 3],
             mask = [False False],
       fill_value = 999999)
>>> print x.mini(axis=1)
[0 2 4]


numpy.ma.masked_array.nbytes

masked_array.nbytes

Total bytes consumed by the elements of the array.

Notes

Does not include memory consumed by non-element attributes of the array object.

Examples

>>> x = np.zeros((3,5,2), dtype=np.complex128)
>>> x.nbytes
480
>>> np.prod(x.shape) * x.itemsize
480


numpy.ma.masked_array.ndim

masked_array.ndim

Number of array dimensions.

Examples

>>> x = np.array([1, 2, 3])
>>> x.ndim
1
>>> y = np.zeros((2, 3, 4))
>>> y.ndim
3


numpy.ma.masked_array.newbyteorder

masked_array.newbyteorder(new_order='S')

Return the array with the same data viewed with a different byte order.

Equivalent to:

arr.view(arr.dtype.newbytorder(new_order))

Changes are also made in all fields and sub-arrays of the array data type.

Parameters:

new_order : string, optional

Byte order to force; a value from the byte order specifications above. new_order codes can be any of:

* 'S' - swap dtype from current to opposite endian
* {'<', 'L'} - little endian
* {'>', 'B'} - big endian
* {'=', 'N'} - native order
* {'|', 'I'} - ignore (no change to byte order)

The default value (‘S’) results in swapping the current byte order. The code does a case-insensitive check on the first letter of new_order for the alternatives above. For example, any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns:

new_arr : array

New array object with the dtype reflecting given change to the byte order.


numpy.ma.masked_array.nonzero

masked_array.nonzero() [source]

Return the indices of unmasked elements that are not zero.

Returns a tuple of arrays, one for each dimension, containing the indices of the non-zero elements in that dimension. The corresponding non-zero values can be obtained with:

a[a.nonzero()]

To group the indices by element, rather than dimension, use instead:

np.transpose(a.nonzero())

The result of this is always a 2d array, with a row for each non-zero element.

Parameters:

None
Returns:

tuple_of_arrays : tuple

Indices of elements that are non-zero.

See also

numpy.nonzero
Function operating on ndarrays.
flatnonzero
Return indices that are non-zero in the flattened version of the input array.
ndarray.nonzero
Equivalent ndarray method.
count_nonzero
Counts the number of non-zero elements in the input array.

Examples

>>> import numpy.ma as ma
>>> x = ma.array(np.eye(3))
>>> x
masked_array(data =
 [[ 1.  0.  0.]
 [ 0.  1.  0.]
 [ 0.  0.  1.]],
      mask =
 False,
      fill_value=1e+20)
>>> x.nonzero()
(array([0, 1, 2]), array([0, 1, 2]))

Masked elements are ignored.

>>> x[1, 1] = ma.masked
>>> x
masked_array(data =
 [[1.0 0.0 0.0]
 [0.0 -- 0.0]
 [0.0 0.0 1.0]],
      mask =
 [[False False False]
 [False  True False]
 [False False False]],
      fill_value=1e+20)
>>> x.nonzero()
(array([0, 2]), array([0, 2]))

Indices can also be grouped by element.

>>> np.transpose(x.nonzero())
array([[0, 0],
       [2, 2]])

A common use for nonzero is to find the indices of an array, where a condition is True. Given an array a, the condition a > 3 is a boolean array and since False is interpreted as 0, ma.nonzero(a > 3) yields the indices of the a where the condition is true.

>>> a = ma.array([[1,2,3],[4,5,6],[7,8,9]])
>>> a > 3
masked_array(data =
 [[False False False]
 [ True  True  True]
 [ True  True  True]],
      mask =
 False,
      fill_value=999999)
>>> ma.nonzero(a > 3)
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))

The nonzero method of the condition array can also be called.

>>> (a > 3).nonzero()
(array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))


numpy.ma.masked_array.partition

masked_array.partition(kth, axis=-1, kind='introselect', order=None)

Rearranges the elements in the array in such a way that value of the element in kth position is in the position it would be in a sorted array. All elements smaller than the kth element are moved before this element and all equal or greater are moved behind it. The ordering of the elements in the two partitions is undefined.

New in version 1.8.0.

Parameters:

kth : int or sequence of ints

Element index to partition by. The kth element value will be in its final sorted position and all smaller elements will be moved before it and all equal or greater elements behind it. The order all elements in the partitions is undefined. If provided with a sequence of kth it will partition all elements indexed by kth of them into their sorted position at once.

axis : int, optional

Axis along which to sort. Default is -1, which means sort along the last axis.

kind : {‘introselect’}, optional

Selection algorithm. Default is ‘introselect’.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.

See also

numpy.partition
Return a parititioned copy of an array.
argpartition
Indirect partition.
sort
Full sort.

Notes

See np.partition for notes on the different algorithms.

Examples

>>> a = np.array([3, 4, 2, 1])
>>> a.partition(a, 3)
>>> a
array([2, 1, 3, 4])

>>> a.partition((1, 3))
array([1, 2, 3, 4])


numpy.ma.masked_array.prod

masked_array.prod(axis=None, dtype=None, out=None) [source]

Return the product of the array elements over the given axis. Masked elements are set to 1 internally for computation.

Parameters:

axis : {None, int}, optional

Axis over which the product is taken. If None is used, then the product is over all the array elements.

dtype : {None, dtype}, optional

Determines the type of the returned array and of the accumulator where the elements are multiplied. If dtype has the value None and the type of a is an integer type of precision less than the default platform integer, then the default platform integer precision is used. Otherwise, the dtype is the same as that of a.

out : {None, array}, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type will be cast if necessary.
Returns:

product_along_axis : {array, scalar}, see dtype parameter above.

Returns an array whose shape is the same as a with the specified axis removed. Returns a 0d array when a is 1d or axis=None. Returns a reference to the specified output array if specified.

See also

prod
equivalent function

Notes

Arithmetic is modular when using integer types, and no error is raised on overflow.

Examples

>>> np.prod([1.,2.])
2.0
>>> np.prod([1.,2.], dtype=np.int32)
2
>>> np.prod([[1.,2.],[3.,4.]])
24.0
>>> np.prod([[1.,2.],[3.,4.]], axis=1)
array([  2.,  12.])


numpy.ma.masked_array.product

masked_array.product(axis=None, dtype=None, out=None) [source]

Return the product of the array elements over the given axis. Masked elements are set to 1 internally for computation.

Parameters:

axis : {None, int}, optional

Axis over which the product is taken. If None is used, then the product is over all the array elements.

dtype : {None, dtype}, optional

Determines the type of the returned array and of the accumulator where the elements are multiplied. If dtype has the value None and the type of a is an integer type of precision less than the default platform integer, then the default platform integer precision is used. Otherwise, the dtype is the same as that of a.

out : {None, array}, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type will be cast if necessary.
Returns:

product_along_axis : {array, scalar}, see dtype parameter above.

Returns an array whose shape is the same as a with the specified axis removed. Returns a 0d array when a is 1d or axis=None. Returns a reference to the specified output array if specified.

See also

prod
equivalent function

Notes

Arithmetic is modular when using integer types, and no error is raised on overflow.

Examples

>>> np.prod([1.,2.])
2.0
>>> np.prod([1.,2.], dtype=np.int32)
2
>>> np.prod([[1.,2.],[3.,4.]])
24.0
>>> np.prod([[1.,2.],[3.,4.]], axis=1)
array([  2.,  12.])


numpy.ma.masked_array.ptp

masked_array.ptp(axis=None, out=None, fill_value=None) [source]

Return (maximum - minimum) along the the given dimension (i.e. peak-to-peak value).

Parameters:

axis : {None, int}, optional

Axis along which to find the peaks. If None (default) the flattened array is used.

out : {None, array_like}, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary.

fill_value : {var}, optional

Value used to fill in the masked values.
Returns:

ptp : ndarray.

A new array holding the result, unless out was specified, in which case a reference to out is returned.


numpy.ma.masked_array.put

masked_array.put(indices, values, mode='raise') [source]

Set storage-indexed locations to corresponding values.

Sets self._data.flat[n] = values[n] for each n in indices. If values is shorter than indices then it will repeat. If values has some masked values, the initial mask is updated in consequence, else the corresponding values are unmasked.

Parameters:

indices : 1-D array_like

Target indices, interpreted as integers.

values : array_like

Values to place in self._data copy at target indices.

mode : {‘raise’, ‘wrap’, ‘clip’}, optional

Specifies how out-of-bounds indices will behave. ‘raise’ : raise an error. ‘wrap’ : wrap around. ‘clip’ : clip to the range.

Notes

values can be a scalar or length 1 array.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]
>>> x.put([0,4,8],[10,20,30])
>>> print x
[[10 -- 3]
 [-- 20 --]
 [7 -- 30]]

>>> x.put(4,999)
>>> print x
[[10 -- 3]
 [-- 999 --]
 [7 -- 30]]


numpy.ma.masked_array.ravel

masked_array.ravel() [source]

Returns a 1D version of self, as a view.

Returns:

MaskedArray

Output view is of shape (self.size,) (or (np.ma.product(self.shape),)).

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]
>>> print x.ravel()
[1 -- 3 -- 5 -- 7 -- 9]


numpy.ma.masked_array.real

masked_array.real

Real part


numpy.ma.masked_array.recordmask

masked_array.recordmask

Return the mask of the records. A record is masked when all the fields are masked.


numpy.ma.masked_array.repeat

masked_array.repeat(repeats, axis=None)

Repeat elements of an array.

Refer to numpy.repeat for full documentation.

See also

numpy.repeat
equivalent function


numpy.ma.masked_array.reshape

masked_array.reshape(*s, **kwargs) [source]

Give a new shape to the array without changing its data.

Returns a masked array containing the same data, but with a new shape. The result is a view on the original array; if this is not possible, a ValueError is raised.

Parameters:

shape : int or tuple of ints

The new shape should be compatible with the original shape. If an integer is supplied, then the result will be a 1-D array of that length.

order : {‘C’, ‘F’}, optional

Determines whether the array data should be viewed as in C (row-major) or FORTRAN (column-major) order.
Returns:

reshaped_array : array

A new view on the array.

See also

reshape
Equivalent function in the masked array module.
numpy.ndarray.reshape
Equivalent method on ndarray object.
numpy.reshape
Equivalent function in the NumPy module.

Notes

The reshaping operation cannot guarantee that a copy will not be made, to modify the shape in place, use a.shape = s

Examples

>>> x = np.ma.array([[1,2],[3,4]], mask=[1,0,0,1])
>>> print x
[[-- 2]
 [3 --]]
>>> x = x.reshape((4,1))
>>> print x
[[--]
 [2]
 [3]
 [--]]


numpy.ma.masked_array.resize

masked_array.resize(newshape, refcheck=True, order=False) [source]

Warning

This method does nothing, except raise a ValueError exception. A masked array does not own its data and therefore cannot safely be resized in place. Use the numpy.ma.resize function instead.

This method is difficult to implement safely and may be deprecated in future releases of NumPy.


numpy.ma.masked_array.round

masked_array.round(decimals=0, out=None) [source]

Return a with each element rounded to the given number of decimals.

Refer to numpy.around for full documentation.

See also

numpy.around
equivalent function


numpy.ma.masked_array.searchsorted

masked_array.searchsorted(v, side='left', sorter=None)

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See also

numpy.searchsorted
equivalent function


numpy.ma.masked_array.set_fill_value

masked_array.set_fill_value(value=None) [source]

Set the filling value of the masked array.

Parameters:

value : scalar, optional

The new filling value. Default is None, in which case a default based on the data type is used.

See also

ma.set_fill_value
Equivalent function.

Examples

>>> x = np.ma.array([0, 1.], fill_value=-np.inf)
>>> x.fill_value
-inf
>>> x.set_fill_value(np.pi)
>>> x.fill_value
3.1415926535897931

Reset to default:

>>> x.set_fill_value()
>>> x.fill_value
1e+20


numpy.ma.masked_array.setfield

masked_array.setfield(val, dtype, offset=0)

Put a value into a specified place in a field defined by a data-type.

Place val into a‘s field defined by dtype and beginning offset bytes into the field.

Parameters:

val : object

Value to be placed in field.

dtype : dtype object

Data-type of the field in which to place val.

offset : int, optional

The number of bytes into the field at which to place val.
Returns:

None

See also

getfield

Examples

>>> x = np.eye(3)
>>> x.getfield(np.float64)
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
>>> x.setfield(3, np.int32)
>>> x.getfield(np.int32)
array([[3, 3, 3],
       [3, 3, 3],
       [3, 3, 3]])
>>> x
array([[  1.00000000e+000,   1.48219694e-323,   1.48219694e-323],
       [  1.48219694e-323,   1.00000000e+000,   1.48219694e-323],
       [  1.48219694e-323,   1.48219694e-323,   1.00000000e+000]])
>>> x.setfield(np.eye(3), np.int32)
>>> x
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])


numpy.ma.masked_array.setflags

masked_array.setflags(write=None, align=None, uic=None)

Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively.

These Boolean-valued flags affect how numpy interprets the memory area used by a (see Notes below). The ALIGNED flag can only be set to True if the data is actually aligned according to the type. The UPDATEIFCOPY flag can never be set to True. The flag WRITEABLE can only be set to True if the array owns its own memory, or the ultimate owner of the memory exposes a writeable buffer interface, or is a string. (The exception for string is made so that unpickling can be done without copying memory.)

Parameters:

write : bool, optional

Describes whether or not a can be written to.

align : bool, optional

Describes whether or not a is aligned properly for its type.

uic : bool, optional

Describes whether or not a is a copy of another “base” array.

Notes

Array flags provide information about how the memory area used for the array is to be interpreted. There are 6 Boolean flags in use, only three of which can be changed by the user: UPDATEIFCOPY, WRITEABLE, and ALIGNED.

WRITEABLE (W) the data area can be written to;

ALIGNED (A) the data and strides are aligned appropriately for the hardware (as determined by the compiler);

UPDATEIFCOPY (U) this array is a copy of some other array (referenced by .base). When this array is deallocated, the base array will be updated with the contents of this array.

All flags can be accessed using their first (upper case) letter as well as the full name.

Examples

>>> y
array([[3, 1, 7],
       [2, 0, 0],
       [8, 5, 9]])
>>> y.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : True
  WRITEABLE : True
  ALIGNED : True
  UPDATEIFCOPY : False
>>> y.setflags(write=0, align=0)
>>> y.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : True
  WRITEABLE : False
  ALIGNED : False
  UPDATEIFCOPY : False
>>> y.setflags(uic=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: cannot set UPDATEIFCOPY flag to True


numpy.ma.masked_array.shape

masked_array.shape

Tuple of array dimensions.

Notes

May be used to “reshape” the array, as long as this would not require a change in the total number of elements

Examples

>>> x = np.array([1, 2, 3, 4])
>>> x.shape
(4,)
>>> y = np.zeros((2, 3, 4))
>>> y.shape
(2, 3, 4)
>>> y.shape = (3, 8)
>>> y
array([[ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])
>>> y.shape = (3, 6)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: total size of new array must be unchanged


numpy.ma.masked_array.sharedmask

masked_array.sharedmask

Share status of the mask (read-only).


numpy.ma.masked_array.shrink_mask

masked_array.shrink_mask() [source]

Reduce a mask to nomask when possible.

Parameters: None
Returns: None

Examples

>>> x = np.ma.array([[1,2 ], [3, 4]], mask=[0]*4)
>>> x.mask
array([[False, False],
       [False, False]], dtype=bool)
>>> x.shrink_mask()
>>> x.mask
False


numpy.ma.masked_array.size

masked_array.size

Number of elements in the array.

Equivalent to np.prod(a.shape), i.e., the product of the array’s dimensions.

Examples

>>> x = np.zeros((3, 5, 2), dtype=np.complex128)
>>> x.size
30
>>> np.prod(x.shape)
30


numpy.ma.masked_array.soften_mask

masked_array.soften_mask() [source]

Force the mask to soft.

Whether the mask of a masked array is hard or soft is determined by its hardmask property. soften_mask sets hardmask to False.

See also

hardmask


numpy.ma.masked_array.sort

masked_array.sort(axis=-1, kind='quicksort', order=None, endwith=True, fill_value=None) [source]

Sort the array, in-place

Parameters:

a : array_like

Array to be sorted.

axis : int, optional

Axis along which to sort. If None, the array is flattened before sorting. The default is -1, which sorts along the last axis.

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm. Default is ‘quicksort’.

order : list, optional

When a is a structured array, this argument specifies which fields to compare first, second, and so on. This list does not need to include all of the fields.

endwith : {True, False}, optional

Whether missing values (if any) should be forced in the upper indices (at the end of the array) (True) or lower indices (at the beginning). When the array contains unmasked values of the largest (or smallest if False) representable value of the datatype the ordering of these values and the masked values is undefined. To enforce the masked values are at the end (beginning) in this case one must sort the mask.

fill_value : {var}, optional

Value used internally for the masked values. If fill_value is not None, it supersedes endwith.
Returns:

sorted_array : ndarray

Array of the same type and shape as a.

See also

ndarray.sort
Method to sort an array in-place.
argsort
Indirect sort.
lexsort
Indirect stable sort on multiple keys.
searchsorted
Find elements in a sorted array.

Notes

See sort for notes on the different sorting algorithms.

Examples

>>> a = ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])
>>> # Default
>>> a.sort()
>>> print a
[1 3 5 -- --]

>>> a = ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])
>>> # Put missing values in the front
>>> a.sort(endwith=False)
>>> print a
[-- -- 1 3 5]

>>> a = ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])
>>> # fill_value takes over endwith
>>> a.sort(endwith=False, fill_value=3)
>>> print a
[1 -- -- 3 5]


numpy.ma.masked_array.squeeze

masked_array.squeeze(axis=None)

Remove single-dimensional entries from the shape of a.

Refer to numpy.squeeze for full documentation.

See also

numpy.squeeze
equivalent function


numpy.ma.masked_array.std

masked_array.std(axis=None, dtype=None, out=None, ddof=0) [source]

Compute the standard deviation along the specified axis.

Returns the standard deviation, a measure of the spread of a distribution, of the array elements. The standard deviation is computed for the flattened array by default, otherwise over the specified axis.

Parameters:

a : array_like

Calculate the standard deviation of these values.

axis : int, optional

Axis along which the standard deviation is computed. The default is to compute the standard deviation of the flattened array.

dtype : dtype, optional

Type to use in computing the standard deviation. For arrays of integer type the default is float64, for arrays of float types it is the same as the array type.

out : ndarray, optional

Alternative output array in which to place the result. It must have the same shape as the expected output but the type (of the calculated values) will be cast if necessary.

ddof : int, optional

Means Delta Degrees of Freedom. The divisor used in calculations is N - ddof, where N represents the number of elements. By default ddof is zero.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

standard_deviation : ndarray, see dtype parameter above.

If out is None, return a new array containing the standard deviation, otherwise return a reference to the output array.

See also

var, mean, nanmean, nanstd, nanvar

numpy.doc.ufuncs
Section “Output arguments”

Notes

The standard deviation is the square root of the average of the squared deviations from the mean, i.e., std = sqrt(mean(abs(x - x.mean())**2)).

The average squared deviation is normally calculated as x.sum() / N, where N = len(x). If, however, ddof is specified, the divisor N - ddof is used instead. In standard statistical practice, ddof=1 provides an unbiased estimator of the variance of the infinite population. ddof=0 provides a maximum likelihood estimate of the variance for normally distributed variables. The standard deviation computed in this function is the square root of the estimated variance, so even with ddof=1, it will not be an unbiased estimate of the standard deviation per se.

Note that, for complex numbers, std takes the absolute value before squaring, so that the result is always real and nonnegative.

For floating-point input, the std is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-accuracy accumulator using the dtype keyword can alleviate this issue.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> np.std(a)
1.1180339887498949
>>> np.std(a, axis=0)
array([ 1.,  1.])
>>> np.std(a, axis=1)
array([ 0.5,  0.5])

In single precision, std() can be inaccurate:

>>> a = np.zeros((2,512*512), dtype=np.float32)
>>> a[0,:] = 1.0
>>> a[1,:] = 0.1
>>> np.std(a)
0.45172946707416706

Computing the standard deviation in float64 is more accurate:

>>> np.std(a, dtype=np.float64)
0.44999999925552653


numpy.ma.masked_array.strides

masked_array.strides

Tuple of bytes to step in each dimension when traversing an array.

The byte offset of element (i[0], i[1], ..., i[n]) in an array a is:

offset = sum(np.array(i) * a.strides)

A more detailed explanation of strides can be found in the “ndarray.rst” file in the NumPy reference guide.

See also

numpy.lib.stride_tricks.as_strided

Notes

Imagine an array of 32-bit integers (each 4 bytes):

x = np.array([[0, 1, 2, 3, 4],
              [5, 6, 7, 8, 9]], dtype=np.int32)

This array is stored in memory as 40 bytes, one after the other (known as a contiguous block of memory). The strides of an array tell us how many bytes we have to skip in memory to move to the next position along a certain axis. For example, we have to skip 4 bytes (1 value) to move to the next column, but 20 bytes (5 values) to get to the same position in the next row. As such, the strides for the array x will be (20, 4).

Examples

>>> y = np.reshape(np.arange(2*3*4), (2,3,4))
>>> y
array([[[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]],
       [[12, 13, 14, 15],
        [16, 17, 18, 19],
        [20, 21, 22, 23]]])
>>> y.strides
(48, 16, 4)
>>> y[1,1,1]
17
>>> offset=sum(y.strides * np.array((1,1,1)))
>>> offset/y.itemsize
17

>>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0)
>>> x.strides
(32, 4, 224, 1344)
>>> i = np.array([3,5,2,2])
>>> offset = sum(i * x.strides)
>>> x[3,5,2,2]
813
>>> offset / x.itemsize
813


numpy.ma.masked_array.sum

masked_array.sum(axis=None, dtype=None, out=None) [source]

Return the sum of the array elements over the given axis. Masked elements are set to 0 internally.

Parameters:

axis : {None, -1, int}, optional

Axis along which the sum is computed. The default (axis = None) is to compute over the flattened array.

dtype : {None, dtype}, optional

Determines the type of the returned array and of the accumulator where the elements are summed. If dtype has the value None and the type of a is an integer type of precision less than the default platform integer, then the default platform integer precision is used. Otherwise, the dtype is the same as that of a.

out : {None, ndarray}, optional

Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary.
Returns:

sum_along_axis : MaskedArray or scalar

An array with the same shape as self, with the specified axis removed. If self is a 0-d array, or if axis is None, a scalar is returned. If an output array is specified, a reference to out is returned.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]
>>> print x.sum()
25
>>> print x.sum(axis=1)
[4 5 16]
>>> print x.sum(axis=0)
[8 5 12]
>>> print type(x.sum(axis=0, dtype=np.int64)[0])
<type 'numpy.int64'>


numpy.ma.masked_array.swapaxes

masked_array.swapaxes(axis1, axis2)

Return a view of the array with axis1 and axis2 interchanged.

Refer to numpy.swapaxes for full documentation.

See also

numpy.swapaxes
equivalent function


numpy.ma.masked_array.T

masked_array.T


numpy.ma.masked_array.take

masked_array.take(indices, axis=None, out=None, mode='raise') [source]


numpy.ma.masked_array.tobytes

masked_array.tobytes(fill_value=None, order='C') [source]

Return the array data as a string containing the raw bytes in the array.

The array is filled with a fill value before the string conversion.

New in version 1.9.0.

Parameters:

fill_value : scalar, optional

Value used to fill in the masked values. Deafult is None, in which case MaskedArray.fill_value is used.

order : {‘C’,’F’,’A’}, optional

Order of the data item in the copy. Default is ‘C’.

  • ‘C’ – C order (row major).
  • ‘F’ – Fortran order (column major).
  • ‘A’ – Any, current order of array.
  • None – Same as ‘A’.

See also

ndarray.tobytes, tolist, tofile

Notes

As for ndarray.tobytes, information about the shape, dtype, etc., but also about fill_value, will be lost.

Examples

>>> x = np.ma.array(np.array([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])
>>> x.tobytes()
'\x01\x00\x00\x00?B\x0f\x00?B\x0f\x00\x04\x00\x00\x00'


numpy.ma.masked_array.tofile

masked_array.tofile(fid, sep='', format='%s') [source]

Save a masked array to a file in binary format.

Warning

This function is not implemented yet.

Raises:

NotImplementedError

When tofile is called.


numpy.ma.masked_array.toflex

masked_array.toflex() [source]

Transforms a masked array into a flexible-type array.

The flexible type array that is returned will have two fields:

  • the _data field stores the _data part of the array.
  • the _mask field stores the _mask part of the array.
Parameters:

None
Returns:

record : ndarray

A new flexible-type ndarray with two fields: the first element containing a value, the second element containing the corresponding mask boolean. The returned record shape matches self.shape.

Notes

A side-effect of transforming a masked array into a flexible ndarray is that meta information (fill_value, ...) will be lost.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]
>>> print x.toflex()
[[(1, False) (2, True) (3, False)]
 [(4, True) (5, False) (6, True)]
 [(7, False) (8, True) (9, False)]]


numpy.ma.masked_array.tolist

masked_array.tolist(fill_value=None) [source]

Return the data portion of the masked array as a hierarchical Python list.

Data items are converted to the nearest compatible Python type. Masked values are converted to fill_value. If fill_value is None, the corresponding entries in the output list will be None.

Parameters:

fill_value : scalar, optional

The value to use for invalid entries. Default is None.
Returns:

result : list

The Python list representation of the masked array.

Examples

>>> x = np.ma.array([[1,2,3], [4,5,6], [7,8,9]], mask=[0] + [1,0]*4)
>>> x.tolist()
[[1, None, 3], [None, 5, None], [7, None, 9]]
>>> x.tolist(-999)
[[1, -999, 3], [-999, 5, -999], [7, -999, 9]]


numpy.ma.masked_array.torecords

masked_array.torecords() [source]

Transforms a masked array into a flexible-type array.

The flexible type array that is returned will have two fields:

  • the _data field stores the _data part of the array.
  • the _mask field stores the _mask part of the array.
Parameters:

None
Returns:

record : ndarray

A new flexible-type ndarray with two fields: the first element containing a value, the second element containing the corresponding mask boolean. The returned record shape matches self.shape.

Notes

A side-effect of transforming a masked array into a flexible ndarray is that meta information (fill_value, ...) will be lost.

Examples

>>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
>>> print x
[[1 -- 3]
 [-- 5 --]
 [7 -- 9]]
>>> print x.toflex()
[[(1, False) (2, True) (3, False)]
 [(4, True) (5, False) (6, True)]
 [(7, False) (8, True) (9, False)]]


numpy.ma.masked_array.tostring

masked_array.tostring(fill_value=None, order='C') [source]

This function is a compatibility alias for tobytes. Despite its name it returns bytes not strings.


numpy.ma.masked_array.trace

masked_array.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None) [source]

Return the sum along diagonals of the array.

Refer to numpy.trace for full documentation.

See also

numpy.trace
equivalent function


numpy.ma.masked_array.transpose

masked_array.transpose(*axes)

Returns a view of the array with axes transposed.

For a 1-D array, this has no effect. (To change between column and row vectors, first cast the 1-D array into a matrix object.) For a 2-D array, this is the usual matrix transpose. For an n-D array, if axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided and a.shape = (i[0], i[1], ... i[n-2], i[n-1]), then a.transpose().shape = (i[n-1], i[n-2], ... i[1], i[0]).

Parameters:

axes : None, tuple of ints, or n ints

  • None or no argument: reverses the order of the axes.
  • tuple of ints: i in the j-th place in the tuple means a‘s i-th axis becomes a.transpose()‘s j-th axis.
  • n ints: same as an n-tuple of the same ints (this form is intended simply as a “convenience” alternative to the tuple form)
Returns:

out : ndarray

View of a, with axes suitably permuted.

See also

ndarray.T
Array property returning the array transposed.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> a
array([[1, 2],
       [3, 4]])
>>> a.transpose()
array([[1, 3],
       [2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
       [2, 4]])
>>> a.transpose(1, 0)
array([[1, 3],
       [2, 4]])


numpy.ma.masked_array.unshare_mask

masked_array.unshare_mask() [source]

Copy the mask and set the sharedmask flag to False.

Whether the mask is shared between masked arrays can be seen from the sharedmask property. unshare_mask ensures the mask is not shared. A copy of the mask is only made if it was shared.

See also

sharedmask


numpy.ma.masked_array.var

masked_array.var(axis=None, dtype=None, out=None, ddof=0) [source]

Compute the variance along the specified axis.

Returns the variance of the array elements, a measure of the spread of a distribution. The variance is computed for the flattened array by default, otherwise over the specified axis.

Parameters:

a : array_like

Array containing numbers whose variance is desired. If a is not an array, a conversion is attempted.

axis : int, optional

Axis along which the variance is computed. The default is to compute the variance of the flattened array.

dtype : data-type, optional

Type to use in computing the variance. For arrays of integer type the default is float32; for arrays of float types it is the same as the array type.

out : ndarray, optional

Alternate output array in which to place the result. It must have the same shape as the expected output, but the type is cast if necessary.

ddof : int, optional

“Delta Degrees of Freedom”: the divisor used in the calculation is N - ddof, where N represents the number of elements. By default ddof is zero.

keepdims : bool, optional

If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original arr.
Returns:

variance : ndarray, see dtype parameter above

If out=None, returns a new array containing the variance; otherwise, a reference to the output array is returned.

See also

std, mean, nanmean, nanstd, nanvar

numpy.doc.ufuncs
Section “Output arguments”

Notes

The variance is the average of the squared deviations from the mean, i.e., var = mean(abs(x - x.mean())**2).

The mean is normally calculated as x.sum() / N, where N = len(x). If, however, ddof is specified, the divisor N - ddof is used instead. In standard statistical practice, ddof=1 provides an unbiased estimator of the variance of a hypothetical infinite population. ddof=0 provides a maximum likelihood estimate of the variance for normally distributed variables.

Note that for complex numbers, the absolute value is taken before squaring, so that the result is always real and nonnegative.

For floating-point input, the variance is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-accuracy accumulator using the dtype keyword can alleviate this issue.

Examples

>>> a = np.array([[1,2],[3,4]])
>>> np.var(a)
1.25
>>> np.var(a, axis=0)
array([ 1.,  1.])
>>> np.var(a, axis=1)
array([ 0.25,  0.25])

In single precision, var() can be inaccurate:

>>> a = np.zeros((2,512*512), dtype=np.float32)
>>> a[0,:] = 1.0
>>> a[1,:] = 0.1
>>> np.var(a)
0.20405951142311096

Computing the variance in float64 is more accurate:

>>> np.var(a, dtype=np.float64)
0.20249999932997387
>>> ((1-0.55)**2 + (0.1-0.55)**2)/2
0.20250000000000001


numpy.ma.masked_array.view

masked_array.view(dtype=None, type=None) [source]

New view of array with the same data.

Parameters:

dtype : data-type or ndarray sub-class, optional

Data-type descriptor of the returned view, e.g., float32 or int16. The default, None, results in the view having the same data-type as a. This argument can also be specified as an ndarray sub-class, which then specifies the type of the returned object (this is equivalent to setting the type parameter).

type : Python type, optional

Type of the returned view, e.g., ndarray or matrix. Again, the default None results in type preservation.

Notes

a.view() is used two different ways:

a.view(some_dtype) or a.view(dtype=some_dtype) constructs a view of the array’s memory with a different data-type. This can cause a reinterpretation of the bytes of memory.

a.view(ndarray_subclass) or a.view(type=ndarray_subclass) just returns an instance of ndarray_subclass that looks at the same array (same shape, dtype, etc.) This does not cause a reinterpretation of the memory.

For a.view(some_dtype), if some_dtype has a different number of bytes per entry than the previous dtype (for example, converting a regular array to a structured array), then the behavior of the view cannot be predicted just from the superficial appearance of a (shown by print(a)). It also depends on exactly how a is stored in memory. Therefore if a is C-ordered versus fortran-ordered, versus defined as a slice or transpose, etc., the view may give different results.

Examples

>>> x = np.array([(1, 2)], dtype=[('a', np.int8), ('b', np.int8)])

Viewing array data using a different type and dtype:

>>> y = x.view(dtype=np.int16, type=np.matrix)
>>> y
matrix([[513]], dtype=int16)
>>> print type(y)
<class 'numpy.matrixlib.defmatrix.matrix'>

Creating a view on a structured array so it can be used in calculations

>>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)])
>>> xv = x.view(dtype=np.int8).reshape(-1,2)
>>> xv
array([[1, 2],
       [3, 4]], dtype=int8)
>>> xv.mean(0)
array([ 2.,  3.])

Making changes to the view changes the underlying array

>>> xv[0,1] = 20
>>> print x
[(1, 20) (3, 4)]

Using a view to convert an array to a record array:

>>> z = x.view(np.recarray)
>>> z.a
array([1], dtype=int8)

Views share data:

>>> x[0] = (9, 10)
>>> z[0]
(9, 10)

Views that change the dtype size (bytes per entry) should normally be avoided on arrays defined by slices, transposes, fortran-ordering, etc.:

>>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16)
>>> y = x[:, 0:2]
>>> y
array([[1, 2],
       [4, 5]], dtype=int16)
>>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: new type not compatible with array.
>>> z = y.copy()
>>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
array([[(1, 2)],
       [(4, 5)]], dtype=[('width', '<i2'), ('length', '<i2')])


numpy.ma.MaskType.all

MaskType.all()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.any

MaskType.any()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.argmax

MaskType.argmax()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.argmin

MaskType.argmin()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.argsort

MaskType.argsort()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.astype

MaskType.astype()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.base

MaskType.base

base object


numpy.ma.MaskType.byteswap

MaskType.byteswap()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.choose

MaskType.choose()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.clip

MaskType.clip()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.compress

MaskType.compress()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.conj

MaskType.conj()


numpy.ma.MaskType.conjugate

MaskType.conjugate()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.copy

MaskType.copy()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.cumprod

MaskType.cumprod()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.cumsum

MaskType.cumsum()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.data

MaskType.data

pointer to start of data


numpy.ma.MaskType.diagonal

MaskType.diagonal()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.dtype

MaskType.dtype

get array data-descriptor


numpy.ma.MaskType.dump

MaskType.dump()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.dumps

MaskType.dumps()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.fill

MaskType.fill()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.flags

MaskType.flags

integer value of flags


numpy.ma.MaskType.flat

MaskType.flat

a 1-d view of scalar


numpy.ma.MaskType.flatten

MaskType.flatten()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.getfield

MaskType.getfield()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.imag

MaskType.imag

imaginary part of scalar


numpy.ma.MaskType.item

MaskType.item()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.itemset

MaskType.itemset()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.itemsize

MaskType.itemsize

length of one element in bytes


numpy.ma.MaskType.max

MaskType.max()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.mean

MaskType.mean()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.min

MaskType.min()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.nbytes

MaskType.nbytes

length of item in bytes


numpy.ma.MaskType.ndim

MaskType.ndim

number of array dimensions


numpy.ma.MaskType.newbyteorder

MaskType.newbyteorder(new_order='S')

Return a new dtype with a different byte order.

Changes are also made in all fields and sub-arrays of the data type.

The new_order code can be any from the following:

  • {‘<’, ‘L’} - little endian
  • {‘>’, ‘B’} - big endian
  • {‘=’, ‘N’} - native order
  • ‘S’ - swap dtype from current to opposite endian
  • {‘|’, ‘I’} - ignore (no change to byte order)
Parameters:

new_order : str, optional

Byte order to force; a value from the byte order specifications above. The default value (‘S’) results in swapping the current byte order. The code does a case-insensitive check on the first letter of new_order for the alternatives above. For example, any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns:

new_dtype : dtype

New dtype object with the given change to the byte order.


numpy.ma.MaskType.nonzero

MaskType.nonzero()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.prod

MaskType.prod()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.ptp

MaskType.ptp()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.put

MaskType.put()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.ravel

MaskType.ravel()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.real

MaskType.real

real part of scalar


numpy.ma.MaskType.repeat

MaskType.repeat()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.reshape

MaskType.reshape()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.resize

MaskType.resize()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.round

MaskType.round()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.searchsorted

MaskType.searchsorted()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.setfield

MaskType.setfield()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.setflags

MaskType.setflags()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.shape

MaskType.shape

tuple of array dimensions


numpy.ma.MaskType.size

MaskType.size

number of elements in the gentype


numpy.ma.MaskType.sort

MaskType.sort()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.squeeze

MaskType.squeeze()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.std

MaskType.std()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.strides

MaskType.strides

tuple of bytes steps in each dimension


numpy.ma.MaskType.sum

MaskType.sum()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.swapaxes

MaskType.swapaxes()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.T

MaskType.T

transpose


numpy.ma.MaskType.take

MaskType.take()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.tobytes

MaskType.tobytes()


numpy.ma.MaskType.tofile

MaskType.tofile()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.tolist

MaskType.tolist()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.tostring

MaskType.tostring()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.trace

MaskType.trace()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.transpose

MaskType.transpose()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.var

MaskType.var()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.ma.MaskType.view

MaskType.view()

Not implemented (virtual attribute)

Class generic exists solely to derive numpy scalars from, and possesses, albeit unimplemented, all the attributes of the ndarray class so as to provide a uniform API.

See also

The


numpy.memmap.all

memmap.all(axis=None, out=None)

Returns True if all elements evaluate to True.

Refer to numpy.all for full documentation.

See also

numpy.all
equivalent function


numpy.memmap.any

memmap.any(axis=None, out=None)

Returns True if any of the elements of a evaluate to True.

Refer to numpy.any for full documentation.

See also

numpy.any
equivalent function


numpy.memmap.argmax

memmap.argmax(axis=None, out=None)

Return indices of the maximum values along the given axis.

Refer to numpy.argmax for full documentation.

See also

numpy.argmax
equivalent function


numpy.memmap.argmin

memmap.argmin(axis=None, out=None)

Return indices of the minimum values along the given axis of a.

Refer to numpy.argmin for detailed documentation.

See also

numpy.argmin
equivalent function


numpy.memmap.argpartition

memmap.argpartition(kth, axis=-1, kind='introselect', order=None)

Returns the indices that would partition this array.

Refer to numpy.argpartition for full documentation.

New in version 1.8.0.

See also

numpy.argpartition
equivalent function


numpy.memmap.argsort

memmap.argsort(axis=-1, kind='quicksort', order=None)

Returns the indices that would sort this array.

Refer to numpy.argsort for full documentation.

See also

numpy.argsort
equivalent function


numpy.memmap.astype

memmap.astype(dtype, order='K', casting='unsafe', subok=True, copy=True)

Copy of the array, cast to a specified type.

Parameters:

dtype : str or dtype

Typecode or data-type to which the array is cast.

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout order of the result. ‘C’ means C order, ‘F’ means Fortran order, ‘A’ means ‘F’ order if all the arrays are Fortran contiguous, ‘C’ order otherwise, and ‘K’ means as close to the order the array elements appear in memory as possible. Default is ‘K’.

casting : {‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

Controls what kind of data casting may occur. Defaults to ‘unsafe’ for backwards compatibility.

  • ‘no’ means the data types should not be cast at all.
  • ‘equiv’ means only byte-order changes are allowed.
  • ‘safe’ means only casts which can preserve values are allowed.
  • ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed.
  • ‘unsafe’ means any data conversions may be done.

subok : bool, optional

If True, then sub-classes will be passed-through (default), otherwise the returned array will be forced to be a base-class array.

copy : bool, optional

By default, astype always returns a newly allocated array. If this is set to false, and the dtype, order, and subok requirements are satisfied, the input array is returned instead of a copy.
Returns:

arr_t : ndarray

Unless copy is False and the other conditions for returning the input array are satisfied (see description for copy input paramter), arr_t is a new array of the same shape as the input array, with dtype, order given by dtype, order.
Raises:

ComplexWarning

When casting from complex to float or int. To avoid this, one should use a.real.astype(t).

Notes

Starting in NumPy 1.9, astype method now returns an error if the string dtype to cast to is not long enough in ‘safe’ casting mode to hold the max value of integer/float array that is being casted. Previously the casting was allowed even if the result was truncated.

Examples

>>> x = np.array([1, 2, 2.5])
>>> x
array([ 1. ,  2. ,  2.5])

>>> x.astype(int)
array([1, 2, 2])


numpy.memmap.base

memmap.base

Base object if memory is from some other object.

Examples

The base of an array that owns its memory is None:

>>> x = np.array([1,2,3,4])
>>> x.base is None
True

Slicing creates a view, whose memory is shared with x:

>>> y = x[2:]
>>> y.base is x
True


numpy.memmap.byteswap

memmap.byteswap(inplace)

Swap the bytes of the array elements

Toggle between low-endian and big-endian data representation by returning a byteswapped array, optionally swapped in-place.

Parameters:

inplace : bool, optional

If True, swap bytes in-place, default is False.
Returns:

out : ndarray

The byteswapped array. If inplace is True, this is a view to self.

Examples

>>> A = np.array([1, 256, 8755], dtype=np.int16)
>>> map(hex, A)
['0x1', '0x100', '0x2233']
>>> A.byteswap(True)
array([  256,     1, 13090], dtype=int16)
>>> map(hex, A)
['0x100', '0x1', '0x3322']

Arrays of strings are not swapped

>>> A = np.array(['ceg', 'fac'])
>>> A.byteswap()
array(['ceg', 'fac'],
      dtype='|S3')


numpy.memmap.choose

memmap.choose(choices, out=None, mode='raise')

Use an index array to construct a new array from a set of choices.

Refer to numpy.choose for full documentation.

See also

numpy.choose
equivalent function


numpy.memmap.clip

memmap.clip(a_min, a_max, out=None)

Return an array whose values are limited to [a_min, a_max].

Refer to numpy.clip for full documentation.

See also

numpy.clip
equivalent function


numpy.memmap.compress

memmap.compress(condition, axis=None, out=None)

Return selected slices of this array along given axis.

Refer to numpy.compress for full documentation.

See also

numpy.compress
equivalent function


numpy.memmap.conj

memmap.conj()

Complex-conjugate all elements.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.memmap.conjugate

memmap.conjugate()

Return the complex conjugate, element-wise.

Refer to numpy.conjugate for full documentation.

See also

numpy.conjugate
equivalent function


numpy.memmap.copy

memmap.copy(order='C')

Return a copy of the array.

Parameters:

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout of the copy. ‘C’ means C-order, ‘F’ means F-order, ‘A’ means ‘F’ if a is Fortran contiguous, ‘C’ otherwise. ‘K’ means match the layout of a as closely as possible. (Note that this function and :func:numpy.copy are very similar, but have different default values for their order= arguments.)

See also

numpy.copy, numpy.copyto

Examples

>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
       [0, 0, 0]])

>>> y
array([[1, 2, 3],
       [4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True


numpy.memmap.ctypes

memmap.ctypes

An object to simplify the interaction of the array with the ctypes module.

This attribute creates an object that makes it easier to use arrays when calling shared libraries with the ctypes module. The returned object has, among others, data, shape, and strides attributes (see Notes below) which themselves return ctypes objects that can be used as arguments to a shared library.

Parameters:

None
Returns:

c : Python object

Possessing attributes data, shape, strides, etc.

See also

numpy.ctypeslib

Notes

Below are the public attributes of this object which were documented in “Guide to NumPy” (we have omitted undocumented public attributes, as well as documented private attributes):

  • data: A pointer to the memory area of the array as a Python integer. This memory area may contain data that is not aligned, or not in correct byte-order. The memory area may not even be writeable. The array flags and data-type of this array should be respected when passing this attribute to arbitrary C-code to avoid trouble that can include Python crashing. User Beware! The value of this attribute is exactly the same as self._array_interface_[‘data’][0].
  • shape (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the C-integer corresponding to dtype(‘p’) on this platform. This base-type could be c_int, c_long, or c_longlong depending on the platform. The c_intp type is defined accordingly in numpy.ctypeslib. The ctypes array contains the shape of the underlying array.
  • strides (c_intp*self.ndim): A ctypes array of length self.ndim where the basetype is the same as for the shape attribute. This ctypes array contains the strides information from the underlying array. This strides information is important for showing how many bytes must be jumped to get to the next element in the array.
  • data_as(obj): Return the data pointer cast to a particular c-types object. For example, calling self._as_parameter_ is equivalent to self.data_as(ctypes.c_void_p). Perhaps you want to use the data as a pointer to a ctypes array of floating-point data: self.data_as(ctypes.POINTER(ctypes.c_double)).
  • shape_as(obj): Return the shape tuple as an array of some other c-types type. For example: self.shape_as(ctypes.c_short).
  • strides_as(obj): Return the strides tuple as an array of some other c-types type. For example: self.strides_as(ctypes.c_longlong).

Be careful using the ctypes attribute - especially on temporary arrays or arrays constructed on the fly. For example, calling (a+b).ctypes.data_as(ctypes.c_void_p) returns a pointer to memory that is invalid because the array created as (a+b) is deallocated before the next Python statement. You can avoid this problem using either c=a+b or ct=(a+b).ctypes. In the latter case, ct will hold a reference to the array until ct is deleted or re-assigned.

If the ctypes module is not available, then the ctypes attribute of array objects still returns something useful, but ctypes objects are not returned and errors may be raised instead. In particular, the object will still have the as parameter attribute which will return an integer equal to the data attribute.

Examples

>>> import ctypes
>>> x
array([[0, 1],
       [2, 3]])
>>> x.ctypes.data
30439712
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long))
<ctypes.LP_c_long object at 0x01F01300>
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long)).contents
c_long(0)
>>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_longlong)).contents
c_longlong(4294967296L)
>>> x.ctypes.shape
<numpy.core._internal.c_long_Array_2 object at 0x01FFD580>
>>> x.ctypes.shape_as(ctypes.c_long)
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides
<numpy.core._internal.c_long_Array_2 object at 0x01FCE620>
>>> x.ctypes.strides_as(ctypes.c_longlong)
<numpy.core._internal.c_longlong_Array_2 object at 0x01F01300>


numpy.memmap.cumprod

memmap.cumprod(axis=None, dtype=None, out=None)

Return the cumulative product of the elements along the given axis.

Refer to numpy.cumprod for full documentation.

See also

numpy.cumprod
equivalent function


numpy.memmap.cumsum

memmap.cumsum(axis=None, dtype=None, out=None)

Return the cumulative sum of the elements along the given axis.

Refer to numpy.cumsum for full documentation.

See also

numpy.cumsum
equivalent function


numpy.memmap.data

memmap.data

Python buffer object pointing to the start of the array’s data.


numpy.memmap.diagonal

memmap.diagonal(offset=0, axis1=0, axis2=1)

Return specified diagonals. In NumPy 1.9 the returned array is a read-only view instead of a copy as in previous NumPy versions. In NumPy 1.10 the read-only restriction will be removed.

Refer to numpy.diagonal for full documentation.

See also

numpy.diagonal
equivalent function


numpy.memmap.dot

memmap.dot(b, out=None)

Dot product of two arrays.

Refer to numpy.dot for full documentation.

See also

numpy.dot
equivalent function

Examples

>>> a = np.eye(2)
>>> b = np.ones((2, 2)) * 2
>>> a.dot(b)
array([[ 2.,  2.],
       [ 2.,  2.]])

This array method can be conveniently chained:

>>> a.dot(b).dot(b)
array([[ 8.,  8.],
       [ 8.,  8.]])


numpy.memmap.dtype

memmap.dtype

Data-type of the array’s elements.

Parameters: None
Returns: d : numpy dtype object

See also

numpy.dtype

Examples

>>> x
array([[0, 1],
       [2, 3]])
>>> x.dtype
dtype('int32')
>>> type(x.dtype)
<type 'numpy.dtype'>


numpy.memmap.dump

memmap.dump(file)

Dump a pickle of the array to the specified file. The array can be read back with pickle.load or numpy.load.

Parameters:

file : str

A string naming the dump file.


numpy.memmap.dumps

memmap.dumps()

Returns the pickle of the array as a string. pickle.loads or numpy.loads will convert the string back to an array.

Parameters: None


numpy.memmap.fill

memmap.fill(value)

Fill the array with a scalar value.

Parameters:

value : scalar

All elements of a will be assigned this value.

Examples

>>> a = np.array([1, 2])
>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([ 1.,  1.])


numpy.memmap.flags

memmap.flags

Information about the memory layout of the array.

Notes

The flags object can be accessed dictionary-like (as in a.flags['WRITEABLE']), or by using lowercased attribute names (as in a.flags.writeable). Short flag names are only supported in dictionary access.

Only the UPDATEIFCOPY, WRITEABLE, and ALIGNED flags can be changed by the user, via direct assignment to the attribute or dictionary entry, or by calling ndarray.setflags.

The array flags cannot be set arbitrarily:

  • UPDATEIFCOPY can only be set False.
  • ALIGNED can only be set True if the data is truly aligned.
  • WRITEABLE can only be set True if the array owns its own memory or the ultimate owner of the memory exposes a writeable buffer interface or is a string.

Arrays can be both C-style and Fortran-style contiguous simultaneously. This is clear for 1-dimensional arrays, but can also be true for higher dimensional arrays.

Even for contiguous arrays a stride for a given dimension arr.strides[dim] may be arbitrary if arr.shape[dim] == 1 or the array has no elements. It does not generally hold that self.strides[-1] == self.itemsize for C-style contiguous arrays or self.strides[0] == self.itemsize for Fortran-style contiguous arrays is true.

Attributes

C_CONTIGUOUS (C) | The data is in a single, C-style contiguous segment.
F_CONTIGUOUS (F) | The data is in a single, Fortran-style contiguous segment.
OWNDATA (O) | The array owns the memory it uses or borrows it from another object.
WRITEABLE (W) | The data area can be written to. Setting this to False locks the data, making it read-only. A view (slice, etc.) inherits WRITEABLE from its base array at creation time, but a view of a writeable array may be subsequently locked while the base array remains writeable. (The opposite is not true, in that a view of a locked array may not be made writeable. However, currently, locking a base object does not lock any views that already reference it, so under that circumstance it is possible to alter the contents of a locked array via a previously created writeable view onto it.) Attempting to change a non-writeable array raises a RuntimeError exception.
ALIGNED (A) | The data and all elements are aligned appropriately for the hardware.
UPDATEIFCOPY (U) | This array is a copy of some other array. When this array is deallocated, the base array will be updated with the contents of this array.
FNC | F_CONTIGUOUS and not C_CONTIGUOUS.
FORC | F_CONTIGUOUS or C_CONTIGUOUS (one-segment test).
BEHAVED (B) | ALIGNED and WRITEABLE.
CARRAY (CA) | BEHAVED and C_CONTIGUOUS.
FARRAY (FA) | BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS.


numpy.memmap.flat

memmap.flat

A 1-D iterator over the array.

This is a numpy.flatiter instance, which acts similarly to, but is not a subclass of, Python’s built-in iterator object.

See also

flatten
Return a copy of the array collapsed into one dimension.

flatiter

Examples

>>> x = np.arange(1, 7).reshape(2, 3)
>>> x
array([[1, 2, 3],
       [4, 5, 6]])
>>> x.flat[3]
4
>>> x.T
array([[1, 4],
       [2, 5],
       [3, 6]])
>>> x.T.flat[3]
5
>>> type(x.flat)
<type 'numpy.flatiter'>

An assignment example:

>>> x.flat = 3; x
array([[3, 3, 3],
       [3, 3, 3]])
>>> x.flat[[1,4]] = 1; x
array([[3, 1, 3],
       [3, 1, 3]])


numpy.memmap.flatten

memmap.flatten(order='C')

Return a copy of the array collapsed into one dimension.

Parameters:

order : {‘C’, ‘F’, ‘A’}, optional

Whether to flatten in C (row-major), Fortran (column-major) order, or preserve the C/Fortran ordering from a. The default is ‘C’.
Returns:

y : ndarray

A copy of the input array, flattened to one dimension.

See also

ravel
Return a flattened array.
flat
A 1-D flat iterator over the array.

Examples

>>> a = np.array([[1,2], [3,4]])
>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten('F')
array([1, 3, 2, 4])


numpy.memmap.getfield

memmap.getfield(dtype, offset=0)

Returns a field of the given array as a certain type.

A field is a view of the array data with a given data-type. The values in the view are determined by the given type and the offset into the current array in bytes. The offset needs to be such that the view dtype fits in the array dtype; for example an array of dtype complex128 has 16-byte elements. If taking a view with a 32-bit integer (4 bytes), the offset needs to be between 0 and 12 bytes.

Parameters:

dtype : str or dtype

The data type of the view. The dtype size of the view can not be larger than that of the array itself.

offset : int

Number of bytes to skip before beginning the element view.

Examples

>>> x = np.diag([1.+1.j]*2)
>>> x[1, 1] = 2 + 4.j
>>> x
array([[ 1.+1.j,  0.+0.j],
       [ 0.+0.j,  2.+4.j]])
>>> x.getfield(np.float64)
array([[ 1.,  0.],
       [ 0.,  2.]])

By choosing an offset of 8 bytes we can select the complex part of the array for our view:

>>> x.getfield(np.float64, offset=8)
array([[ 1.,  0.],
   [ 0.,  4.]])


numpy.memmap.imag

memmap.imag

The imaginary part of the array.

Examples

>>> x = np.sqrt([1+0j, 0+1j])
>>> x.imag
array([ 0.        ,  0.70710678])
>>> x.imag.dtype
dtype('float64')


numpy.memmap.item

memmap.item(*args)

Copy an element of an array to a standard Python scalar and return it.

Parameters:

*args : Arguments (variable number and type)

  • none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.
  • int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.
  • tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.
Returns:

z : Standard Python scalar object

A copy of the specified element of the array as a suitable Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.item(3)
2
>>> x.item(7)
5
>>> x.item((0, 1))
1
>>> x.item((2, 2))
3


numpy.memmap.itemset

memmap.itemset(*args)

Insert scalar into an array (scalar is cast to array’s dtype, if possible)

There must be at least 1 argument, and define the last argument as item. Then, a.itemset(*args) is equivalent to but faster than a[args] = item. The item should be a scalar value and args must select a single item in the array a.

Parameters:

*args : Arguments

If one argument: a scalar, only used in case a is of size 1. If two arguments: the last argument is the value to be set and must be a scalar, the first argument specifies a single array element location. It is either an int or a tuple.

Notes

Compared to indexing syntax, itemset provides some speed increase for placing a scalar into a particular location in an ndarray, if you must do this. However, generally this is discouraged: among other problems, it complicates the appearance of the code. Also, when using itemset (and item) inside a loop, be sure to assign the methods to a local variable to avoid the attribute look-up at each loop iteration.

Examples

>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[3, 1, 7],
       [2, 8, 3],
       [8, 5, 3]])
>>> x.itemset(4, 0)
>>> x.itemset((2, 2), 9)
>>> x
array([[3, 1, 7],
       [2, 0, 3],
       [8, 5, 9]])


numpy.memmap.itemsize

memmap.itemsize

Length of one array element in bytes.

Examples

>>> x = np.array([1,2,3], dtype=np.float64)
>>> x.itemsize
8
>>> x = np.array([1,2,3], dtype=np.complex128)
>>> x.itemsize
16


numpy.memmap.max

memmap.max(axis=None, out=None)

Return the maximum along a given axis.

Refer to numpy.amax for full documentation.

See also

numpy.amax
equivalent function


numpy.memmap.mean

memmap.mean(axis=None, dtype=None, out=None)

Returns the average of the array elements along given axis.

Refer to numpy.mean for full documentation.

See also

numpy.mean
equivalent function


numpy.memmap.min

memmap.min(axis=None, out=None)

Return the minimum along a given axis.

Refer to numpy.amin for full documentation.

See also

numpy.amin
equivalent function


numpy.memmap.nbytes

memmap.nbytes

Total bytes consumed by the elements of the array.

Notes

Does not include memory consumed by non-element attributes of the array object.

Examples

>>> x = np.zeros((3,5,2), dtype=np.complex128)
>>> x.nbytes
480
>>> np.prod(x.shape) * x.itemsize
480


numpy.memmap.ndim

memmap.ndim

Number of array dimensions.

Examples

>>> x = np.array([1, 2, 3])
>>> x.ndim
1
>>> y = np.zeros((2, 3, 4))
>>> y.ndim
3


numpy.memmap.newbyteorder

memmap.newbyteorder(new_order='S')

Return the array with the same data viewed with a different byte order.

Equivalent to:

arr.view(arr.dtype.newbytorder(new_order))

Changes are also made in all fields and sub-arrays of the array data type.

Parameters:

new_order : string, optional

Byte order to force; a value from the byte order specifications above. new_order codes can be any of:

* 'S' - swap dtype from current to opposite endian
* {'<', 'L'} - little endian
* {'>', 'B'} - big endian
* {'=', 'N'} - native order
* {'|', 'I'} - ignore (no change to byte order)

The default value (‘S’) results in swapping the current byte order. The code does a case-insensitive check on the first letter of new_order for the alternatives above. For example, any of ‘B’ or ‘b’ or ‘biggish’ are valid to specify big-endian.
Returns:

new_arr : array

New array object with the dtype reflecting given change to the byte order.


numpy.memmap.nonzero

memmap.nonzero()

Return the indices of the elements that are non-zero.

Refer to numpy.nonzero for full documentation.

See also

numpy.nonzero
equivalent function


numpy.memmap.partition

memmap.partition(kth, axis=-1, kind='introselect', order=None)

Rearranges the elements in the array in such a way that value of the element in kth position is in the position it would be in a sorted array. All elements smaller than the kth element are moved before this element and all equal or greater are moved behind it. The ordering of the elements in the two partitions is undefined.

New in version 1.8.0.

Parameters:

kth : int or sequence of ints

Element index to partition by. The kth element value will be in its final sorted position and all smaller elements will be moved before it and all equal or greater elements behind it. The order all elements in the partitions is undefined. If provided with a sequence of kth it will partition all elements indexed by kth of them into their sorted position at once.

axis : int, optional

Axis along which to sort. Default is -1, which means sort along the last axis.

kind : {‘introselect’}, optional

Selection algorithm. Default is ‘introselect’.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.

See also

numpy.partition
Return a parititioned copy of an array.
argpartition
Indirect partition.
sort
Full sort.

Notes

See np.partition for notes on the different algorithms.

Examples

>>> a = np.array([3, 4, 2, 1])
>>> a.partition(a, 3)
>>> a
array([2, 1, 3, 4])

>>> a.partition((1, 3))
array([1, 2, 3, 4])


numpy.memmap.prod

memmap.prod(axis=None, dtype=None, out=None)

Return the product of the array elements over the given axis

Refer to numpy.prod for full documentation.

See also

numpy.prod
equivalent function


numpy.memmap.ptp

memmap.ptp(axis=None, out=None)

Peak to peak (maximum - minimum) value along a given axis.

Refer to numpy.ptp for full documentation.

See also

numpy.ptp
equivalent function


numpy.memmap.put

memmap.put(indices, values, mode='raise')

Set a.flat[n] = values[n] for all n in indices.

Refer to numpy.put for full documentation.

See also

numpy.put
equivalent function


numpy.memmap.ravel

memmap.ravel([order])

Return a flattened array.

Refer to numpy.ravel for full documentation.

See also

numpy.ravel
equivalent function
ndarray.flat
a flat iterator on the array.


numpy.memmap.real

memmap.real

The real part of the array.

See also

numpy.real
equivalent function

Examples

>>> x = np.sqrt([1+0j, 0+1j])
>>> x.real
array([ 1.        ,  0.70710678])
>>> x.real.dtype
dtype('float64')


numpy.memmap.repeat

memmap.repeat(repeats, axis=None)

Repeat elements of an array.

Refer to numpy.repeat for full documentation.

See also

numpy.repeat
equivalent function


numpy.memmap.reshape

memmap.reshape(shape, order='C')

Returns an array containing the same data with a new shape.

Refer to numpy.reshape for full documentation.

See also

numpy.reshape
equivalent function


numpy.memmap.resize

memmap.resize(new_shape, refcheck=True)

Change shape and size of array in-place.

Parameters:

new_shape : tuple of ints, or n ints

Shape of resized array.

refcheck : bool, optional

If False, reference count will not be checked. Default is True.
Returns:

None
Raises:

ValueError

If a does not own its own data or references or views to it exist, and the data memory must be changed.

SystemError

If the order keyword argument is specified. This behaviour is a bug in NumPy.

See also

resize
Return a new array with the specified shape.

Notes

This reallocates space for the data area if necessary.

Only contiguous arrays (data elements consecutive in memory) can be resized.

The purpose of the reference count check is to make sure you do not use this array as a buffer for another Python object and then reallocate the memory. However, reference counts can increase in other ways so if you are sure that you have not shared the memory for this array with another Python object, then you may safely set refcheck to False.

Examples

Shrinking an array: array is flattened (in the order that the data are stored in memory), resized, and reshaped:

>>> a = np.array([[0, 1], [2, 3]], order='C')
>>> a.resize((2, 1))
>>> a
array([[0],
       [1]])

>>> a = np.array([[0, 1], [2, 3]], order='F')
>>> a.resize((2, 1))
>>> a
array([[0],
       [2]])

Enlarging an array: as above, but missing entries are filled with zeros:

>>> b = np.array([[0, 1], [2, 3]])
>>> b.resize(2, 3) # new_shape parameter doesn't have to be a tuple
>>> b
array([[0, 1, 2],
       [3, 0, 0]])

Referencing an array prevents resizing...

>>> c = a
>>> a.resize((1, 1))
Traceback (most recent call last):
...
ValueError: cannot resize an array that has been referenced ...

Unless refcheck is False:

>>> a.resize((1, 1), refcheck=False)
>>> a
array([[0]])
>>> c
array([[0]])


numpy.memmap.round

memmap.round(decimals=0, out=None)

Return a with each element rounded to the given number of decimals.

Refer to numpy.around for full documentation.

See also

numpy.around
equivalent function


numpy.memmap.searchsorted

memmap.searchsorted(v, side='left', sorter=None)

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See also

numpy.searchsorted
equivalent function


numpy.memmap.setfield

memmap.setfield(val, dtype, offset=0)

Put a value into a specified place in a field defined by a data-type.

Place val into a‘s field defined by dtype and beginning offset bytes into the field.

Parameters:

val : object

Value to be placed in field.

dtype : dtype object

Data-type of the field in which to place val.

offset : int, optional

The number of bytes into the field at which to place val.
Returns:

None

See also

getfield

Examples

>>> x = np.eye(3)
>>> x.getfield(np.float64)
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
>>> x.setfield(3, np.int32)
>>> x.getfield(np.int32)
array([[3, 3, 3],
       [3, 3, 3],
       [3, 3, 3]])
>>> x
array([[  1.00000000e+000,   1.48219694e-323,   1.48219694e-323],
       [  1.48219694e-323,   1.00000000e+000,   1.48219694e-323],
       [  1.48219694e-323,   1.48219694e-323,   1.00000000e+000]])
>>> x.setfield(np.eye(3), np.int32)
>>> x
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])


numpy.memmap.setflags

memmap.setflags(write=None, align=None, uic=None)

Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively.

These Boolean-valued flags affect how numpy interprets the memory area used by a (see Notes below). The ALIGNED flag can only be set to True if the data is actually aligned according to the type. The UPDATEIFCOPY flag can never be set to True. The flag WRITEABLE can only be set to True if the array owns its own memory, or the ultimate owner of the memory exposes a writeable buffer interface, or is a string. (The exception for string is made so that unpickling can be done without copying memory.)

Parameters:

write : bool, optional

Describes whether or not a can be written to.

align : bool, optional

Describes whether or not a is aligned properly for its type.

uic : bool, optional

Describes whether or not a is a copy of another “base” array.

Notes

Array flags provide information about how the memory area used for the array is to be interpreted. There are 6 Boolean flags in use, only three of which can be changed by the user: UPDATEIFCOPY, WRITEABLE, and ALIGNED.

WRITEABLE (W) the data area can be written to;

ALIGNED (A) the data and strides are aligned appropriately for the hardware (as determined by the compiler);

UPDATEIFCOPY (U) this array is a copy of some other array (referenced by .base). When this array is deallocated, the base array will be updated with the contents of this array.

All flags can be accessed using their first (upper case) letter as well as the full name.

Examples

>>> y
array([[3, 1, 7],
       [2, 0, 0],
       [8, 5, 9]])
>>> y.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : True
  WRITEABLE : True
  ALIGNED : True
  UPDATEIFCOPY : False
>>> y.setflags(write=0, align=0)
>>> y.flags
  C_CONTIGUOUS : True
  F_CONTIGUOUS : False
  OWNDATA : True
  WRITEABLE : False
  ALIGNED : False
  UPDATEIFCOPY : False
>>> y.setflags(uic=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: cannot set UPDATEIFCOPY flag to True


numpy.memmap.shape

memmap.shape

Tuple of array dimensions.

Notes

May be used to “reshape” the array, as long as this would not require a change in the total number of elements

Examples

>>> x = np.array([1, 2, 3, 4])
>>> x.shape
(4,)
>>> y = np.zeros((2, 3, 4))
>>> y.shape
(2, 3, 4)
>>> y.shape = (3, 8)
>>> y
array([[ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])
>>> y.shape = (3, 6)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: total size of new array must be unchanged


numpy.memmap.size

memmap.size

Number of elements in the array.

Equivalent to np.prod(a.shape), i.e., the product of the array’s dimensions.

Examples

>>> x = np.zeros((3, 5, 2), dtype=np.complex128)
>>> x.size
30
>>> np.prod(x.shape)
30


numpy.memmap.sort

memmap.sort(axis=-1, kind='quicksort', order=None)

Sort an array, in-place.

Parameters:

axis : int, optional

Axis along which to sort. Default is -1, which means sort along the last axis.

kind : {‘quicksort’, ‘mergesort’, ‘heapsort’}, optional

Sorting algorithm. Default is ‘quicksort’.

order : list, optional

When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. Not all fields need be specified.

See also

numpy.sort
Return a sorted copy of an array.
argsort
Indirect sort.
lexsort
Indirect stable sort on multiple keys.
searchsorted
Find elements in sorted array.
partition
Partial sort.

Notes

See sort for notes on the different sorting algorithms.

Examples

>>> a = np.array([[1,4], [3,1]])
>>> a.sort(axis=1)
>>> a
array([[1, 4],
       [1, 3]])
>>> a.sort(axis=0)
>>> a
array([[1, 3],
       [1, 4]])

Use the order keyword to specify a field to use when sorting a structured array:

>>> a = np.array([('a', 2), ('c', 1)], dtype=[('x', 'S1'), ('y', int)])
>>> a.sort(order='y')
>>> a
array([('c', 1), ('a', 2)],
      dtype=[('x', '|S1'), ('y', '<i4')])


numpy.memmap.squeeze

memmap.squeeze(axis=None)

Remove single-dimensional entries from the shape of a.

Refer to numpy.squeeze for full documentation.

See also

numpy.squeeze
equivalent function


numpy.memmap.std

memmap.std(axis=None, dtype=None, out=None, ddof=0)

Returns the standard deviation of the array elements along given axis.

Refer to numpy.std for full documentation.

See also

numpy.std
equivalent function


numpy.memmap.strides

memmap.strides

Tuple of bytes to step in each dimension when traversing an array.

The byte offset of element (i[0], i[1], ..., i[n]) in an array a is:

offset = sum(np.array(i) * a.strides)

A more detailed explanation of strides can be found in the “ndarray.rst” file in the NumPy reference guide.

See also

numpy.lib.stride_tricks.as_strided

Notes

Imagine an array of 32-bit integers (each 4 bytes):

x = np.array([[0, 1, 2, 3, 4],
              [5, 6, 7, 8, 9]], dtype=np.int32)

This array is stored in memory as 40 bytes, one after the other (known as a contiguous block of memory). The strides of an array tell us how many bytes we have to skip in memory to move to the next position along a certain axis. For example, we have to skip 4 bytes (1 value) to move to the next column, but 20 bytes (5 values) to get to the same position in the next row. As such, the strides for the array x will be (20, 4).

Examples

>>> y = np.reshape(np.arange(2*3*4), (2,3,4))
>>> y
array([[[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]],
       [[12, 13, 14, 15],
        [16, 17, 18, 19],
        [20, 21, 22, 23]]])
>>> y.strides
(48, 16, 4)
>>> y[1,1,1]
17
>>> offset=sum(y.strides * np.array((1,1,1)))
>>> offset/y.itemsize
17

>>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0)
>>> x.strides
(32, 4, 224, 1344)
>>> i = np.array([3,5,2,2])
>>> offset = sum(i * x.strides)
>>> x[3,5,2,2]
813
>>> offset / x.itemsize
813


numpy.memmap.sum

memmap.sum(axis=None, dtype=None, out=None)

Return the sum of the array elements over the given axis.

Refer to numpy.sum for full documentation.

See also

numpy.sum
equivalent function


numpy.memmap.swapaxes

memmap.swapaxes(axis1, axis2)

Return a view of the array with axis1 and axis2 interchanged.

Refer to numpy.swapaxes for full documentation.

See also

numpy.swapaxes
equivalent function


numpy.memmap.T

memmap.T

Same as self.transpose(), except that self is returned if self.ndim < 2.

Examples

>>> x = np.array([[1.,2.],[3.,4.]])
>>> x
array([[ 1.,  2.],
       [ 3.,  4.]])
>>> x.T
array([[ 1.,  3.],
       [ 2.,  4.]])
>>> x = np.array([1.,2.,3.,4.])
>>> x
array([ 1.,  2.,  3.,  4.])
>>> x.T
array([ 1.,  2.,  3.,  4.])


numpy.memmap.take

memmap.take(indices, axis=None, out=None, mode='raise')

Return an array formed from the elements of a at the given indices.

Refer to numpy.take for full documentation.

See also

numpy.take
equivalent function


numpy.memmap.tobytes

memmap.tobytes(order='C')

Construct Python bytes containing the raw data bytes in the array.

Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.

New in version 1.9.0.

Parameters:

order : {‘C’, ‘F’, None}, optional

Order of the data for multidimensional arrays: C, Fortran, or the same as for the original array.
Returns:

s : bytes

Python bytes exhibiting a copy of a‘s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]])
>>> x.tobytes()
b'\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x03\x00\x00\x00'


numpy.memmap.tofile

memmap.tofile(fid, sep="", format="%s")

Write array to a file as text or binary (default).

Data is always written in ‘C’ order, independent of the order of a. The data produced by this method can be recovered using the function fromfile().

Parameters:

fid : file or str

An open file object, or a string containing a filename.

sep : str

Separator between array items for text output. If “” (empty), a binary file is written, equivalent to file.write(a.tobytes()).

format : str

Format string for text file output. Each entry in the array is formatted to text by first converting it to the closest Python type, and then using “format” % item.

Notes

This is a convenience function for quick storage of array data. Information on endianness and precision is lost, so this method is not a good choice for files intended to archive data or transport data between machines with different endianness. Some of these problems can be overcome by outputting the data as text files, at the expense of speed and file size.


numpy.memmap.tolist

memmap.tolist()

Return the array as a (possibly nested) list.

Return a copy of the array data as a (nested) Python list. Data items are converted to the nearest compatible Python type.

Parameters:

none
Returns:

y : list

The possibly nested list of array elements.

Notes

The array may be recreated, a = np.array(a.tolist()).

Examples

>>> a = np.array([1, 2])
>>> a.tolist()
[1, 2]
>>> a = np.array([[1, 2], [3, 4]])
>>> list(a)
[array([1, 2]), array([3, 4])]
>>> a.tolist()
[[1, 2], [3, 4]]


numpy.memmap.tostring

memmap.tostring(order='C')

Construct Python bytes containing the raw data bytes in the array.

Constructs Python bytes showing a copy of the raw contents of data memory. The bytes object can be produced in either ‘C’ or ‘Fortran’, or ‘Any’ order (the default is ‘C’-order). ‘Any’ order means C-order unless the F_CONTIGUOUS flag in the array is set, in which case it means ‘Fortran’ order.

This function is a compatibility alias for tobytes. Despite its name it returns bytes not strings.

Parameters:

order : {‘C’, ‘F’, None}, optional

Order of the data for multidimensional arrays: C, Fortran, or the same as for the original array.
Returns:

s : bytes

Python bytes exhibiting a copy of a‘s raw data.

Examples

>>> x = np.array([[0, 1], [2, 3]])
>>> x.tobytes()
b'\x00\x00\x00\x00\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00'
>>> x.tobytes('C') == x.tobytes()
True
>>> x.tobytes('F')
b'\x00\x00\x00\x00\x02\x00\x00\x00\x01\x00\x00\x00\x03\x00\x00\x00'


numpy.memmap.trace

memmap.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None)

Return the sum along diagonals of the array.

Refer to numpy.trace for full documentation.

See also

numpy.trace
equivalent function


numpy.memmap.transpose

memmap.transpose(*axes)

Returns a view of the array with axes transposed.

For a 1-D array, this has no effect. (To change between column and row vectors, first cast the 1-D array into a matrix object.) For a 2-D array, this is the usual matrix transpose. For an n-D array, if axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided and a.shape = (i[0], i[1], ... i[n-2], i[n-1]), then a.transpose().shape = (i[n-1], i[n-2], ... i[1], i[0]).

Parameters:

axes : None, tuple of ints, or n ints

  • None or no argument: reverses the order of the axes.
  • tuple of ints: i in the j-th place in the tuple means a‘s i-th axis becomes a.transpose()‘s j-th axis.
  • n ints: same as an n-tuple of the same ints (this form is intended simply as a “convenience” alternative to the tuple form)
Returns:

out : ndarray

View of a, with axes suitably permuted.

See also

ndarray.T
Array property returning the array transposed.

Examples

>>> a = np.array([[1, 2], [3, 4]])
>>> a
array([[1, 2],
       [3, 4]])
>>> a.transpose()
array([[1, 3],
       [2, 4]])
>>> a.transpose((1, 0))
array([[1, 3],
       [2, 4]])
>>> a.transpose(1, 0)
array([[1, 3],
       [2, 4]])


numpy.memmap.var

memmap.var(axis=None, dtype=None, out=None, ddof=0)

Returns the variance of the array elements, along given axis.

Refer to numpy.var for full documentation.

See also

numpy.var
equivalent function


numpy.memmap.view

memmap.view(dtype=None, type=None)

New view of array with the same data.

Parameters:

dtype : data-type or ndarray sub-class, optional

Data-type descriptor of the returned view, e.g., float32 or int16. The default, None, results in the view having the same data-type as a. This argument can also be specified as an ndarray sub-class, which then specifies the type of the returned object (this is equivalent to setting the type parameter).

type : Python type, optional

Type of the returned view, e.g., ndarray or matrix. Again, the default None results in type preservation.

Notes

a.view() is used two different ways:

a.view(some_dtype) or a.view(dtype=some_dtype) constructs a view of the array’s memory with a different data-type. This can cause a reinterpretation of the bytes of memory.

a.view(ndarray_subclass) or a.view(type=ndarray_subclass) just returns an instance of ndarray_subclass that looks at the same array (same shape, dtype, etc.) This does not cause a reinterpretation of the memory.

For a.view(some_dtype), if some_dtype has a different number of bytes per entry than the previous dtype (for example, converting a regular array to a structured array), then the behavior of the view cannot be predicted just from the superficial appearance of a (shown by print(a)). It also depends on exactly how a is stored in memory. Therefore if a is C-ordered versus fortran-ordered, versus defined as a slice or transpose, etc., the view may give different results.

Examples

>>> x = np.array([(1, 2)], dtype=[('a', np.int8), ('b', np.int8)])

Viewing array data using a different type and dtype:

>>> y = x.view(dtype=np.int16, type=np.matrix)
>>> y
matrix([[513]], dtype=int16)
>>> print type(y)
<class 'numpy.matrixlib.defmatrix.matrix'>

Creating a view on a structured array so it can be used in calculations

>>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)])
>>> xv = x.view(dtype=np.int8).reshape(-1,2)
>>> xv
array([[1, 2],
       [3, 4]], dtype=int8)
>>> xv.mean(0)
array([ 2.,  3.])

Making changes to the view changes the underlying array

>>> xv[0,1] = 20
>>> print x
[(1, 20) (3, 4)]

Using a view to convert an array to a record array:

>>> z = x.view(np.recarray)
>>> z.a
array([1], dtype=int8)

Views share data:

>>> x[0] = (9, 10)
>>> z[0]
(9, 10)

Views that change the dtype size (bytes per entry) should normally be avoided on arrays defined by slices, transposes, fortran-ordering, etc.:

>>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16)
>>> y = x[:, 0:2]
>>> y
array([[1, 2],
       [4, 5]], dtype=int16)
>>> y.view(dtype=[('width', np.int16), ('length', np.int16)])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: new type not compatible with array.
>>> z = y.copy()
>>> z.view(dtype=[('width', np.int16), ('length', np.int16)])
array([[(1, 2)],
       [(4, 5)]], dtype=[('width', '<i2'), ('length', '<i2')])


numpy.nditer.dtypes

nditer.dtypes


numpy.nditer.finished

nditer.finished


numpy.nditer.has_delayed_bufalloc

nditer.has_delayed_bufalloc


numpy.nditer.has_index

nditer.has_index


numpy.nditer.has_multi_index

nditer.has_multi_index


numpy.nditer.index

nditer.index


numpy.nditer.iterationneedsapi

nditer.iterationneedsapi


numpy.nditer.iterindex

nditer.iterindex


numpy.nditer.iterrange

nditer.iterrange


numpy.nditer.itersize

nditer.itersize


numpy.nditer.itviews

nditer.itviews


numpy.nditer.multi_index

nditer.multi_index


numpy.nditer.ndim

nditer.ndim


numpy.nditer.nop

nditer.nop


numpy.nditer.operands

nditer.operands


numpy.nditer.shape

nditer.shape


numpy.nditer.value

nditer.value


numpy.poly1d.coeffs

poly1d.coeffs = None


numpy.poly1d.order

poly1d.order = None


numpy.poly1d.variable

poly1d.variable = None


numpy.polynomial.chebyshev.Chebyshev.domain

Chebyshev.domain = array([-1, 1])


numpy.polynomial.chebyshev.Chebyshev.maxpower

Chebyshev.maxpower = 100


numpy.polynomial.chebyshev.Chebyshev.nickname

Chebyshev.nickname = 'cheb'


numpy.polynomial.chebyshev.Chebyshev.window

Chebyshev.window = array([-1, 1])


numpy.polynomial.hermite.Hermite.domain

Hermite.domain = array([-1, 1])


numpy.polynomial.hermite.Hermite.maxpower

Hermite.maxpower = 100


numpy.polynomial.hermite.Hermite.nickname

Hermite.nickname = 'herm'


numpy.polynomial.hermite.Hermite.window

Hermite.window = array([-1, 1])


numpy.polynomial.hermite_e.HermiteE.domain

HermiteE.domain = array([-1, 1])


numpy.polynomial.hermite_e.HermiteE.maxpower

HermiteE.maxpower = 100


numpy.polynomial.hermite_e.HermiteE.nickname

HermiteE.nickname = 'herme'


numpy.polynomial.hermite_e.HermiteE.window

HermiteE.window = array([-1, 1])


numpy.polynomial.laguerre.Laguerre.domain

Laguerre.domain = array([0, 1])


numpy.polynomial.laguerre.Laguerre.maxpower

Laguerre.maxpower = 100


numpy.polynomial.laguerre.Laguerre.nickname

Laguerre.nickname = 'lag'


numpy.polynomial.laguerre.Laguerre.window

Laguerre.window = array([0, 1])


numpy.polynomial.legendre.Legendre.domain

Legendre.domain = array([-1, 1])


numpy.polynomial.legendre.Legendre.maxpower

Legendre.maxpower = 100


numpy.polynomial.legendre.Legendre.nickname

Legendre.nickname = 'leg'


numpy.polynomial.legendre.Legendre.window

Legendre.window = array([-1, 1])


numpy.polynomial.polynomial.Polynomial.domain

Polynomial.domain = array([-1, 1])


numpy.polynomial.polynomial.Polynomial.maxpower

Polynomial.maxpower = 100


numpy.polynomial.polynomial.Polynomial.nickname

Polynomial.nickname = 'poly'


numpy.polynomial.polynomial.Polynomial.window

Polynomial.window = array([-1, 1])


numpy.random.RandomState.poisson_lam_max

RandomState.poisson_lam_max = 2147020237.4999895


numpy.testing.Tester.bench

Tester.bench(label='fast', verbose=1, extra_argv=None) [source]

Run benchmarks for module using nose.

Parameters:

label : {‘fast’, ‘full’, ‘’, attribute identifier}, optional

Identifies the benchmarks to run. This can be a string to pass to the nosetests executable with the ‘-A’ option, or one of several special values. Special values are: * ‘fast’ - the default - which corresponds to the nosetests -A

option of ‘not slow’.

  • ‘full’ - fast (as above) and slow benchmarks as in the ‘no -A’ option to nosetests - this is the same as ‘’.
  • None or ‘’ - run all tests.

attribute_identifier - string passed directly to nosetests as ‘-A’.

verbose : int, optional

Verbosity value for benchmark outputs, in the range 1-10. Default is 1.

extra_argv : list, optional

List with any extra arguments to pass to nosetests.
Returns:

success : bool

Returns True if running the benchmarks works, False if an error occurred.

Notes

Benchmarks are like tests, but have names starting with “bench” instead of “test”, and can be found under the “benchmarks” sub-directory of the module.

Each NumPy module exposes bench in its namespace to run all benchmarks for it.

Examples

>>> success = np.lib.bench()
Running benchmarks for numpy.lib
...
using 562341 items:
unique:
0.11
unique1d:
0.11
ratio: 1.0
nUnique: 56230 == 56230
...
OK

>>> success
True


numpy.testing.Tester.excludes

Tester.excludes = ['f2py_ext', 'f2py_f90_ext', 'gen_ext', 'pyrex_ext', 'swig_ext']


numpy.testing.Tester.prepare_test_args

Tester.prepare_test_args(label='fast', verbose=1, extra_argv=None, doctests=False, coverage=False) [source]

Run tests for module using nose.

This method does the heavy lifting for the test method. It takes all the same arguments, for details see test.

See also

test


numpy.testing.Tester.test

Tester.test(label='fast', verbose=1, extra_argv=None, doctests=False, coverage=False, raise_warnings=None) [source]

Run tests for module using nose.

Parameters:

label : {‘fast’, ‘full’, ‘’, attribute identifier}, optional

Identifies the tests to run. This can be a string to pass to the nosetests executable with the ‘-A’ option, or one of several special values. Special values are: * ‘fast’ - the default - which corresponds to the nosetests -A

option of ‘not slow’.

  • ‘full’ - fast (as above) and slow tests as in the ‘no -A’ option to nosetests - this is the same as ‘’.
  • None or ‘’ - run all tests.

attribute_identifier - string passed directly to nosetests as ‘-A’.

verbose : int, optional

Verbosity value for test outputs, in the range 1-10. Default is 1.

extra_argv : list, optional

List with any extra arguments to pass to nosetests.

doctests : bool, optional

If True, run doctests in module. Default is False.

coverage : bool, optional

If True, report coverage of NumPy code. Default is False. (This requires the `coverage module:

<http://nedbatchelder.com/code/modules/coverage.html>`_).

raise_warnings : str or sequence of warnings, optional

This specifies which warnings to configure as ‘raise’ instead of ‘warn’ during the test execution. Valid strings are:

  • “develop” : equals (DeprecationWarning, RuntimeWarning)
  • “release” : equals (), don’t raise on any warnings.
Returns:

result : object

Returns the result of running the tests as a nose.result.TextTestResult object.

Notes

Each NumPy module exposes test in its namespace to run all tests for it. For example, to run all tests for numpy.lib:

>>> np.lib.test()

Examples

>>> result = np.lib.test()
Running unit tests for numpy.lib
...
Ran 976 tests in 3.933s

OK

>>> result.errors
[]
>>> result.knownfail
[]