BooksAudiobooksComicsSheet Music### Categories

### Categories

### Categories

Editors' Picks Books

Hand-picked favorites from

our editors

our editors

Editors' Picks Audiobooks

Hand-picked favorites from

our editors

our editors

Editors' Picks Comics

Hand-picked favorites from

our editors

our editors

Editors' Picks Sheet Music

Hand-picked favorites from

our editors

our editors

Top Books

What's trending, bestsellers,

award-winners & more

award-winners & more

Top Audiobooks

What's trending, bestsellers,

award-winners & more

award-winners & more

Top Comics

What's trending, bestsellers,

award-winners & more

award-winners & more

Top Sheet Music

What's trending, bestsellers,

award-winners & more

award-winners & more

Welcome to Scribd! Start your free trial and access books, documents and more.Find out more

Release 0.10.0.dev6665

Written by the SciPy community

February 28, 2011

CONTENTS

1

SciPy Tutorial 1.1 Introduction . . . . . . . . . . . . . . . . . . . 1.2 Basic functions in Numpy (and top-level scipy) . 1.3 Special functions (scipy.special) . . . . . 1.4 Integration (scipy.integrate) . . . . . . . 1.5 Optimization (optimize) . . . . . . . . . . . . . 1.6 Interpolation (scipy.interpolate) . . . . 1.7 Fourier Transforms (scipy.fftpack) . . . . 1.8 Signal Processing (signal) . . . . . . . . . . . . 1.9 Linear Algebra . . . . . . . . . . . . . . . . . . 1.10 Statistics . . . . . . . . . . . . . . . . . . . . . 1.11 Multi-dimensional image processing (ndimage) 1.12 File IO (scipy.io) . . . . . . . . . . . . . . . 1.13 Weave . . . . . . . . . . . . . . . . . . . . . . Release Notes 2.1 SciPy 0.9.0 Release Notes 2.2 SciPy 0.8.0 Release Notes 2.3 SciPy 0.7.2 Release Notes 2.4 SciPy 0.7.1 Release Notes 2.5 SciPy 0.7.0 Release Notes

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

3 3 6 10 11 15 29 41 43 50 61 69 91 97 133 133 136 141 141 143 149 149 189 204 216 231 259 267 300 320 340 401 416 460 503 552 576

2

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

3

Reference 3.1 Clustering package (scipy.cluster) . . . . . . . . . . 3.2 Constants (scipy.constants) . . . . . . . . . . . . . . 3.3 Fourier transforms (scipy.fftpack) . . . . . . . . . . 3.4 Integration and ODEs (scipy.integrate) . . . . . . . 3.5 Interpolation (scipy.interpolate) . . . . . . . . . . 3.6 Input and output (scipy.io) . . . . . . . . . . . . . . . . 3.7 Linear algebra (scipy.linalg) . . . . . . . . . . . . . 3.8 Maximum entropy models (scipy.maxentropy) . . . . 3.9 Miscellaneous routines (scipy.misc) . . . . . . . . . . 3.10 Multi-dimensional image processing (scipy.ndimage) . 3.11 Orthogonal distance regression (scipy.odr) . . . . . . . 3.12 Optimization and root ﬁnding (scipy.optimize) . . . . 3.13 Signal processing (scipy.signal) . . . . . . . . . . . . 3.14 Sparse matrices (scipy.sparse) . . . . . . . . . . . . . 3.15 Sparse linear algebra (scipy.sparse.linalg) . . . . 3.16 Spatial algorithms and data structures (scipy.spatial)

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

i

3.17 3.18 3.19 3.20

Distance computations (scipy.spatial.distance) Special functions (scipy.special) . . . . . . . . . . Statistical functions (scipy.stats) . . . . . . . . . . C/C++ integration (scipy.weave) . . . . . . . . . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

595 611 637 903 909 917 919

Bibliography Python Module Index Index

ii

SciPy Reference Guide, Release 0.10.0.dev6665

Release 0.10.dev6665 Date February 28, 2011 SciPy (pronounced “Sigh Pie”) is open-source software for mathematics, science, and engineering.

CONTENTS

1

SciPy Reference Guide, Release 0.10.0.dev6665

2

CONTENTS

CHAPTER

ONE

SCIPY TUTORIAL

1.1 Introduction

Contents • Introduction – SciPy Organization – Finding Documentation SciPy is a collection of mathematical algorithms and convenience functions built on the Numpy extension for Python. It adds signiﬁcant power to the interactive Python session by exposing the user to high-level commands and classes for the manipulation and visualization of data. With SciPy, an interactive Python session becomes a data-processing and system-prototyping environment rivaling sytems such as MATLAB, IDL, Octave, R-Lab, and SciLab. The additional power of using SciPy within Python, however, is that a powerful programming language is also available for use in developing sophisticated programs and specialized applications. Scientiﬁc applications written in SciPy beneﬁt from the development of additional modules in numerous niche’s of the software landscape by developers across the world. Everything from parallel programming to web and data-base subroutines and classes have been made available to the Python programmer. All of this power is available in addition to the mathematical libraries in SciPy. This document provides a tutorial for the ﬁrst-time user of SciPy to help get started with some of the features available in this powerful package. It is assumed that the user has already installed the package. Some general Python facility is also assumed such as could be acquired by working through the Tutorial in the Python distribution. For further introductory help the user is directed to the Numpy documentation. For brevity and convenience, we will often assume that the main packages (numpy, scipy, and matplotlib) have been imported as:

>>> >>> >>> >>> import import import import numpy as np scipy as sp matplotlib as mpl matplotlib.pyplot as plt

These are the import conventions that our community has adopted after discussion on public mailing lists. You will see these conventions used throughout NumPy and SciPy source code and documentation. While we obviously don’t require you to follow these conventions in your own code, it is highly recommended.

3

SciPy Reference Guide, Release 0.10.0.dev6665

1.1.1 SciPy Organization

SciPy is organized into subpackages covering different scientiﬁc computing domains. These are summarized in the following table: Subpackage cluster constants fftpack integrate interpolate io linalg maxentropy ndimage odr optimize signal sparse spatial special stats weave Description Clustering algorithms Physical and mathematical constants Fast Fourier Transform routines Integration and ordinary differential equation solvers Interpolation and smoothing splines Input and Output Linear algebra Maximum entropy methods N-dimensional image processing Orthogonal distance regression Optimization and root-ﬁnding routines Signal processing Sparse matrices and associated routines Spatial data structures and algorithms Special functions Statistical distributions and functions C/C++ integration

**Scipy sub-packages need to be imported separately, for example:
**

>>> from scipy import linalg, optimize

Because of their ubiquitousness, some of the functions in these subpackages are also made available in the scipy namespace to ease their use in interactive sessions and programs. In addition, many basic array functions from numpy are also available at the top-level of the scipy package. Before looking at the sub-packages individually, we will ﬁrst look at some of these common functions.

1.1.2 Finding Documentation

Scipy and Numpy have HTML and PDF versions of their documentation available at http://docs.scipy.org/, which currently details nearly all available functionality. However, this documentation is still work-in-progress, and some parts may be incomplete or sparse. As we are a volunteer organization and depend on the community for growth, your participation - everything from providing feedback to improving the documentation and code - is welcome and actively encouraged. Python also provides the facility of documentation strings. The functions and classes available in SciPy use this method for on-line documentation. There are two methods for reading these messages and getting help. Python provides the command help in the pydoc module. Entering this command with no arguments (i.e. >>> help ) launches an interactive help session that allows searching through the keywords and modules available to all of Python. Running the command help with an object as the argument displays the calling signature, and the documentation string of the object. The pydoc method of help is sophisticated but uses a pager to display the text. Sometimes this can interfere with the terminal you are running the interactive session within. A scipy-speciﬁc help system is also available under the command sp.info. The signature and documentation string for the object passed to the help command are printed to standard output (or to a writeable object passed as the third argument). The second keyword argument of sp.info deﬁnes the maximum width of the line for printing. If a module is passed as the argument to help than a list of the functions and classes deﬁned in that module is printed. For example:

4

Chapter 1. SciPy Tutorial

SciPy Reference Guide, Release 0.10.0.dev6665

>>> sp.info(optimize.fmin) fmin(func, x0, args=(), xtol=0.0001, ftol=0.0001, maxiter=None, maxfun=None, full_output=0, disp=1, retall=0, callback=None) Minimize a function using the downhill simplex algorithm. Parameters ---------func : callable func(x,*args) The objective function to be minimized. x0 : ndarray Initial guess. args : tuple Extra arguments passed to func, i.e. ‘‘f(x,*args)‘‘. callback : callable Called after each iteration, as callback(xk), where xk is the current parameter vector. Returns ------xopt : ndarray Parameter that minimizes function. fopt : float Value of function at minimum: ‘‘fopt = func(xopt)‘‘. iter : int Number of iterations performed. funcalls : int Number of function calls made. warnflag : int 1 : Maximum number of function evaluations made. 2 : Maximum number of iterations reached. allvecs : list Solution at each iteration. Other parameters ---------------xtol : float Relative error ftol : number Relative error maxiter : int Maximum number maxfun : number Maximum number full_output : bool Set to True if disp : bool Set to True to retall : bool Set to True to

in xopt acceptable for convergence. in func(xopt) acceptable for convergence. of iterations to perform. of function evaluations to make. fopt and warnflag outputs are desired. print convergence messages. return list of solutions at each iteration.

Notes ----Uses a Nelder-Mead simplex algorithm to find the minimum of function of one or more variables.

Another useful command is source. When given a function written in Python as an argument, it prints out a listing of the source code for that function. This can be helpful in learning about an algorithm or understanding exactly what

1.1. Introduction

5

SciPy Reference Guide, Release 0.10.0.dev6665

a function is doing with its arguments. Also don’t forget about the Python command dir which can be used to look at the namespace of a module or package.

**1.2 Basic functions in Numpy (and top-level scipy)
**

Contents • Basic functions in Numpy (and top-level scipy) – Interaction with Numpy – Top-level scipy routines * Type handling * Index Tricks * Shape manipulation * Polynomials * Vectorizing functions (vectorize) * Other useful functions – Common functions

**1.2.1 Interaction with Numpy
**

To begin with, all of the Numpy functions have been subsumed into the scipy namespace so that all of those functions are available without additionally importing Numpy. In addition, the universal functions (addition, subtraction, division) have been altered to not raise exceptions if ﬂoating-point errors are encountered; instead, NaN’s and Inf’s are returned in the arrays. To assist in detection of these events, several functions (sp.isnan, sp.isfinite, sp.isinf) are available. Finally, some of the basic functions like log, sqrt, and inverse trig functions have been modiﬁed to return complex numbers instead of NaN’s where appropriate (i.e. sp.sqrt(-1) returns 1j).

**1.2.2 Top-level scipy routines
**

The purpose of the top level of scipy is to collect general-purpose routines that the other sub-packages can use and to provide a simple replacement for Numpy. Anytime you might think to import Numpy, you can import scipy instead and remove yourself from direct dependence on Numpy. These routines are divided into several ﬁles for organizational purposes, but they are all available under the numpy namespace (and the scipy namespace). There are routines for type handling and type checking, shape and matrix manipulation, polynomial processing, and other useful functions. Rather than giving a detailed description of each of these functions (which is available in the Numpy Reference Guide or by using the help, info and source commands), this tutorial will discuss some of the more useful commands which require a little introduction to use to their full potential. Type handling Note the difference between sp.iscomplex/sp.isreal and sp.iscomplexobj/sp.isrealobj. The former command is array based and returns byte arrays of ones and zeros providing the result of the element-wise test. The latter command is object based and returns a scalar describing the result of the test on the entire object. Often it is required to get just the real and/or imaginary part of a complex number. While complex numbers and arrays have attributes that return those values, if one is not sure whether or not the object will be complex-valued, it is better to use the functional forms sp.real and sp.imag . These functions succeed for anything that can be turned into

6

Chapter 1. SciPy Tutorial

SciPy Reference Guide, Release 0.10.0.dev6665

a Numpy array. Consider also the function sp.real_if_close which transforms a complex-valued number with tiny imaginary part into a real number. Occasionally the need to check whether or not a number is a scalar (Python (long)int, Python ﬂoat, Python complex, or rank-0 array) occurs in coding. This functionality is provided in the convenient function sp.isscalar which returns a 1 or a 0. Finally, ensuring that objects are a certain Numpy type occurs often enough that it has been given a convenient interface in SciPy through the use of the sp.cast dictionary. The dictionary is keyed by the type it is desired to cast to and the dictionary stores functions to perform the casting. Thus, sp.cast[’f’](d) returns an array of sp.float32 from d. This function is also useful as an easy way to get a scalar of a certain type:

>>> sp.cast[’f’](sp.pi) array(3.1415927410125732, dtype=float32)

Index Tricks There are some class instances that make special use of the slicing functionality to provide efﬁcient means for array construction. This part will discuss the operation of sp.mgrid , sp.ogrid , sp.r_ , and sp.c_ for quickly constructing arrays. One familiar with MATLAB (R) may complain that it is difﬁcult to construct arrays from the interactive session with Python. Suppose, for example that one wants to construct an array that begins with 3 followed by 5 zeros and then contains 10 numbers spanning the range -1 to 1 (inclusive on both ends). Before SciPy, you would need to enter something like the following

>>> concatenate(([3],[0]*5,arange(-1,1.002,2/9.0)))

**With the r_ command one can enter this as
**

>>> r_[3,[0]*5,-1:1:10j]

which can ease typing and make for more readable code. Notice how objects are concatenated, and the slicing syntax is (ab)used to construct ranges. The other term that deserves a little explanation is the use of the complex number 10j as the step size in the slicing syntax. This non-standard use allows the number to be interpreted as the number of points to produce in the range rather than as a step size (note we would have used the long integer notation, 10L, but this notation may go away in Python as the integers become uniﬁed). This non-standard usage may be unsightly to some, but it gives the user the ability to quickly construct complicated vectors in a very readable fashion. When the number of points is speciﬁed in this way, the end- point is inclusive. The “r” stands for row concatenation because if the objects between commas are 2 dimensional arrays, they are stacked by rows (and thus must have commensurate columns). There is an equivalent command c_ that stacks 2d arrays by columns but works identically to r_ for 1d arrays. Another very useful class instance which makes use of extended slicing notation is the function mgrid. In the simplest case, this function can be used to construct 1d ranges as a convenient substitute for arange. It also allows the use of complex-numbers in the step-size to indicate the number of points to place between the (inclusive) end-points. The real purpose of this function however is to produce N, N-d arrays which provide coordinate arrays for an N-dimensional volume. The easiest way to understand this is with an example of its usage:

>>> mgrid[0:5,0:5] array([[[0, 0, 0, 0, [1, 1, 1, 1, [2, 2, 2, 2, [3, 3, 3, 3, [4, 4, 4, 4, [[0, 1, 2, 3, [0, 1, 2, 3, 0], 1], 2], 3], 4]], 4], 4],

1.2. Basic functions in Numpy (and top-level scipy)

7

SciPy Reference Guide, Release 0.10.0.dev6665

[0, 1, 2, 3, 4], [0, 1, 2, 3, 4], [0, 1, 2, 3, 4]]]) >>> mgrid[0:5:4j,0:5:4j] array([[[ 0. , 0. , [ 1.6667, 1.6667, [ 3.3333, 3.3333, [ 5. , 5. , [[ 0. , 1.6667, [ 0. , 1.6667, [ 0. , 1.6667, [ 0. , 1.6667,

0. , 1.6667, 3.3333, 5. , 3.3333, 3.3333, 3.3333, 3.3333,

0. ], 1.6667], 3.3333], 5. ]], 5. ], 5. ], 5. ], 5. ]]])

Having meshed arrays like this is sometimes very useful. However, it is not always needed just to evaluate some N-dimensional function over a grid due to the array-broadcasting rules of Numpy and SciPy. If this is the only purpose for generating a meshgrid, you should instead use the function ogrid which generates an “open “grid using NewAxis judiciously to create N, N-d arrays where only one dimension in each array has length greater than 1. This will save memory and create the same result if the only purpose for the meshgrid is to generate sample points for evaluation of an N-d function. Shape manipulation In this category of functions are routines for squeezing out length- one dimensions from N-dimensional arrays, ensuring that an array is at least 1-, 2-, or 3-dimensional, and stacking (concatenating) arrays by rows, columns, and “pages “(in the third dimension). Routines for splitting arrays (roughly the opposite of stacking arrays) are also available. Polynomials There are two (interchangeable) ways to deal with 1-d polynomials in SciPy. The ﬁrst is to use the poly1d class from Numpy. This class accepts coefﬁcients or polynomial roots to initialize a polynomial. The polynomial object can then be manipulated in algebraic expressions, integrated, differentiated, and evaluated. It even prints like a polynomial:

>>> p = poly1d([3,4,5]) >>> print p 2 3 x + 4 x + 5 >>> print p*p 4 3 2 9 x + 24 x + 46 x + 40 x + 25 >>> print p.integ(k=6) 3 2 x + 2 x + 5 x + 6 >>> print p.deriv() 6 x + 4 >>> p([4,5]) array([ 69, 100])

The other way to handle polynomials is as an array of coefﬁcients with the ﬁrst element of the array giving the coefﬁcient of the highest power. There are explicit functions to add, subtract, multiply, divide, integrate, differentiate, and evaluate polynomials represented as sequences of coefﬁcients. Vectorizing functions (vectorize) One of the features that NumPy provides is a class vectorize to convert an ordinary Python function which accepts scalars and returns scalars into a “vectorized-function” with the same broadcasting rules as other Numpy functions 8 Chapter 1. SciPy Tutorial

SciPy Reference Guide, Release 0.10.0.dev6665

(i.e. the Universal functions, or ufuncs). For example, suppose you have a Python function named addsubtract deﬁned as:

>>> def addsubtract(a,b): ... if a > b: ... return a - b ... else: ... return a + b

which deﬁnes a function of two scalar variables and returns a scalar result. The class vectorize can be used to “vectorize “this function so that

>>> vec_addsubtract = vectorize(addsubtract)

**returns a function which takes array arguments and returns an array result:
**

>>> vec_addsubtract([0,3,6,9],[1,3,5,7]) array([1, 6, 1, 2])

This particular function could have been written in vector form without the use of vectorize . But, what if the function you have written is the result of some optimization or integration routine. Such functions can likely only be vectorized using vectorize. Other useful functions There are several other functions in the scipy_base package including most of the other functions that are also in the Numpy package. The reason for duplicating these functions is to allow SciPy to potentially alter their original interface and make it easier for users to know how to get access to functions

>>> from scipy import *

Functions which should be mentioned are mod(x,y) which can replace x % y when it is desired that the result take the sign of y instead of x . Also included is fix which always rounds to the nearest integer towards zero. For doing phase processing, the functions angle, and unwrap are also useful. Also, the linspace and logspace functions return equally spaced samples in a linear or log scale. Finally, it’s useful to be aware of the indexing capabilities of Numpy. Mention should be made of the new function select which extends the functionality of where to include multiple conditions and multiple choices. The calling convention is select(condlist,choicelist,default=0). select is a vectorized form of the multiple if-statement. It allows rapid construction of a function which returns an array of results based on a list of conditions. Each element of the return array is taken from the array in a choicelist corresponding to the ﬁrst condition in condlist that is true. For example

>>> x = r_[-2:3] >>> x array([-2, -1, 0, 1, 2]) >>> select([x > 3, x >= 0],[0,x+2]) array([0, 0, 2, 3, 4])

1.2.3 Common functions

Some functions depend on sub-packages of SciPy but should be available from the top-level of SciPy due to their common use. These are functions that might have been placed in scipy_base except for their dependence on other sub-packages of SciPy. For example the factorial and comb functions compute n! and n!/k!(n − k)! using either exact integer arithmetic (thanks to Python’s Long integer object), or by using ﬂoating-point precision and the gamma function. The functions rand and randn are used so often that they warranted a place at the top level. There are

1.2. Basic functions in Numpy (and top-level scipy)

9

SciPy Reference Guide, Release 0.10.0.dev6665

convenience functions for the interactive use: disp (similar to print), and who (returns a list of deﬁned variables and memory consumption–upper bounded). Another function returns a common image used in image processing: lena. Finally, two functions are provided that are useful for approximating derivatives of functions using discrete-differences. The function central_diff_weights returns weighting coefﬁcients for an equally-spaced N -point approximation to the derivative of order o. These weights must be multiplied by the function corresponding to these points and the results added to obtain the derivative approximation. This function is intended for use when only samples of the function are avaiable. When the function is an object that can be handed to a routine and evaluated, the function derivative can be used to automatically evaluate the object at the correct points to obtain an N-point approximation to the o-th derivative at a given point.

**1.3 Special functions (scipy.special)
**

The main feature of the scipy.special package is the deﬁnition of numerous special functions of mathematical physics. Available functions include airy, elliptic, bessel, gamma, beta, hypergeometric, parabolic cylinder, mathieu, spheroidal wave, struve, and kelvin. There are also some low-level stats functions that are not intended for general use as an easier interface to these functions is provided by the stats module. Most of these functions can take array arguments and return array results following the same broadcasting rules as other math functions in Numerical Python. Many of these functions also accept complex numbers as input. For a complete list of the available functions with a one-line description type >>> help(special). Each function also has its own documentation accessible using help. If you don’t see a function you need, consider writing it and contributing it to the library. You can write the function in either C, Fortran, or Python. Look in the source code of the library for examples of each of these kinds of functions.

**1.3.1 Bessel functions of real order(jn, jn_zeros)
**

Bessel functions are a family of solutions to Bessel’s differential equation with real or complex order alpha: x2 d2 y dy +x + (x2 − α2 )y = 0 2 dx dx

Among other uses, these functions arise in wave propagation problems such as the vibrational modes of a thin drum head. Here is an example of a circular drum head anchored at the edge:

>>> >>> >>> ... ... >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> from scipy import * from scipy.special import jn, jn_zeros def drumhead_height(n, k, distance, angle, t): nth_zero = jn_zeros(n, k) return cos(t)*cos(n*angle)*jn(n, distance*nth_zero) theta = r_[0:2*pi:50j] radius = r_[0:1:50j] x = array([r*cos(theta) for r in radius]) y = array([r*sin(theta) for r in radius]) z = array([drumhead_height(1, 1, r, theta, 0.5) for r in radius]) import pylab from mpl_toolkits.mplot3d import Axes3D from matplotlib import cm fig = pylab.figure() ax = Axes3D(fig) ax.plot_surface(x, y, z, rstride=1, cstride=1, cmap=cm.jet) ax.set_xlabel(’X’) ax.set_ylabel(’Y’)

10

Chapter 1. SciPy Tutorial

SciPy Reference Guide, Release 0.10.0.dev6665

>>> ax.set_zlabel(’Z’) >>> pylab.show()

0.4 0.2 Z 0.0 0.2 0.4 0.5 0.0 Y

0.5

0.0

X

0.5

0.5

**1.4 Integration (scipy.integrate)
**

The scipy.integrate sub-package provides several integration techniques including an ordinary differential equation integrator. An overview of the module is provided by the help command:

>>> help(integrate) Methods for Integrating Functions given function object. quad dblquad tplquad fixed_quad quadrature romberg ------General purpose integration. General purpose double integration. General purpose triple integration. Integrate func(x) using Gaussian quadrature of order n. Integrate with given tolerance using Gaussian quadrature. Integrate func using Romberg integration.

Methods for Integrating Functions given fixed samples. trapz cumtrapz simps romb ----Use trapezoidal rule to compute integral from samples. Use trapezoidal rule to cumulatively compute integral. Use Simpson’s rule to compute integral from samples. Use Romberg Integration to compute integral from (2**k + 1) evenly-spaced samples.

See the special module’s orthogonal polynomials (special) for Gaussian quadrature roots and weights for other weighting factors and regions. Interface to numerical integrators of ODE systems. odeint ode -- General integration of ordinary differential equations. -- Integrate ODE using VODE and ZVODE routines.

1.4. Integration (scipy.integrate)

11

SciPy Reference Guide, Release 0.10.0.dev6665

**1.4.1 General integration (quad)
**

The function quad is provided to integrate a function of one variable between two points. The points can be ±∞ (± inf) to indicate inﬁnite limits. For example, suppose you wish to integrate a bessel function jv(2.5,x) along the interval [0, 4.5].

4.5

I=

0

J2.5 (x) dx.

**This could be computed using quad:
**

>>> result = integrate.quad(lambda x: special.jv(2.5,x), 0, 4.5) >>> print result (1.1178179380783249, 7.8663172481899801e-09) >>> I = sqrt(2/pi)*(18.0/27*sqrt(2)*cos(4.5)-4.0/27*sqrt(2)*sin(4.5)+ sqrt(2*pi)*special.fresnel(3/sqrt(pi))[0]) >>> print I 1.117817938088701 >>> print abs(result[0]-I) 1.03761443881e-11

The ﬁrst argument to quad is a “callable” Python object (i.e a function, method, or class instance). Notice the use of a lambda- function in this case as the argument. The next two arguments are the limits of integration. The return value is a tuple, with the ﬁrst element holding the estimated value of the integral and the second element holding an upper bound on the error. Notice, that in this case, the true value of this integral is I= where Si (x) =

0

2 π

**√ 18 √ 4√ 2 cos (4.5) − 2 sin (4.5) + 2πSi 27 27
**

x

3 √ π

,

sin

π 2 t dt. 2

is the Fresnel sine integral. Note that the numerically-computed integral is within 1.04 × 10−11 of the exact result — well below the reported error bound. Inﬁnite inputs are also allowed in quad by using ± inf as one of the arguments. For example, suppose that a numerical value for the exponential integral:

∞

En (x) =

1

e−xt dt. tn

is desired (and the fact that this integral can be computed as special.expn(n,x) is forgotten). The functionality of the function special.expn can be replicated by deﬁning a new function vec_expint based on the routine quad:

>>> from scipy.integrate import quad >>> def integrand(t,n,x): ... return exp(-x*t) / t**n >>> def expint(n,x): ... return quad(integrand, 1, Inf, args=(n, x))[0] >>> vec_expint = vectorize(expint) >>> vec_expint(3,arange(1.0,4.0,0.5)) array([ 0.1097, 0.0567, 0.0301, 0.0163, >>> special.expn(3,arange(1.0,4.0,0.5)) array([ 0.1097, 0.0567, 0.0301, 0.0163,

0.0089, 0.0089,

0.0049]) 0.0049])

12

Chapter 1. SciPy Tutorial

SciPy Reference Guide, Release 0.10.0.dev6665

The function which is integrated can even use the quad argument (though the error bound may underestimate the error due to possible numerical error in the integrand from the use of quad ). The integral in this case is

∞ ∞ 1

In =

0

1 e−xt dt dx = . n t n

>>> result = quad(lambda x: expint(3, x), 0, inf) >>> print result (0.33333333324560266, 2.8548934485373678e-09) >>> I3 = 1.0/3.0 >>> print I3 0.333333333333 >>> print I3 - result[0] 8.77306560731e-11

This last example shows that multiple integration can be handled using repeated calls to quad. The mechanics of this for double and triple integration have been wrapped up into the functions dblquad and tplquad. The function, dblquad performs double integration. Use the help function to be sure that the arguments are deﬁned in the correct order. In addition, the limits on all inner integrals are actually functions which can be constant functions. An example of using double integration to compute several values of In is shown below:

>>> from scipy.integrate import quad, dblquad >>> def I(n): ... return dblquad(lambda t, x: exp(-x*t)/t**n, 0, Inf, lambda x: 1, lambda x: Inf) >>> print I(4) (0.25000000000435768, 1.0518245707751597e-09) >>> print I(3) (0.33333333325010883, 2.8604069919261191e-09) >>> print I(2) (0.49999999999857514, 1.8855523253868967e-09)

**1.4.2 Gaussian quadrature (integrate.gauss_quadtol)
**

A few functions are also provided in order to perform simple Gaussian quadrature over a ﬁxed interval. The ﬁrst is fixed_quad which performs ﬁxed-order Gaussian quadrature. The second function is quadrature which performs Gaussian quadrature of multiple orders until the difference in the integral estimate is beneath some tolerance supplied by the user. These functions both use the module special.orthogonal which can calculate the roots and quadrature weights of a large variety of orthogonal polynomials (the polynomials themselves are available as special functions returning instances of the polynomial class — e.g. special.legendre).

**1.4.3 Integrating using samples
**

There are three functions for computing integrals given only samples: trapz , simps, and romb . The ﬁrst two functions use Newton-Coates formulas of order 1 and 2 respectively to perform integration. These two functions can handle, non-equally-spaced samples. The trapezoidal rule approximates the function as a straight line between adjacent points, while Simpson’s rule approximates the function between three adjacent points as a parabola. If the samples are equally-spaced and the number of samples available is 2k + 1 for some integer k, then Romberg integration can be used to obtain high-precision estimates of the integral using the available samples. Romberg integration uses the trapezoid rule at step-sizes related by a power of two and then performs Richardson extrapolation on these estimates to approximate the integral with a higher-degree of accuracy. (A different interface to Romberg integration useful when the function can be provided is also available as romberg). 1.4. Integration (scipy.integrate) 13

SciPy Reference Guide, Release 0.10.0.dev6665

**1.4.4 Ordinary differential equations (odeint)
**

Integrating a set of ordinary differential equations (ODEs) given initial conditions is another useful example. The function odeint is available in SciPy for integrating a ﬁrst-order vector differential equation: dy = f (y, t) , dt given initial conditions y (0) = y0 , where y is a length N vector and f is a mapping from RN to RN . A higher-order ordinary differential equation can always be reduced to a differential equation of this type by introducing intermediate derivatives into the y vector. For example suppose it is desired to ﬁnd the solution to the following second-order differential equation: d2 w − zw(z) = 0 dz 2

1 = − √3Γ 1 . It is known that the solution to this differential 3 (3) equation with these boundary conditions is the Airy function

with initial conditions w (0) =

√ 1 2 3 2 3 Γ( 3 )

and

dw dz z=0

w = Ai (z) , which gives a means to check the integrator using special.airy. First, convert this ODE into standard form by setting y = dy = dt In other words, f (y, t) = A (t) y. As an interesting reminder, if A (t) commutes with 0 A (τ ) dτ under matrix multiplication, then this linear differential equation has an exact solution using the matrix exponential:

t t dw dz , w

and t = z. Thus, the differential equation becomes = 0 1 t 0 y.

ty1 y0

=

0 1

t 0

y0 y1

y (t) = exp

0

A (τ ) dτ

y (0) ,

However, in this case, A (t) and its integral do not commute. There are many optional inputs and outputs available when using odeint which can help tune the solver. These additional inputs and outputs are not needed much of the time, however, and the three required input arguments and the output solution sufﬁce. The required inputs are the function deﬁning the derivative, fprime, the initial conditions vector, y0, and the time points to obtain a solution, t, (with the initial value point as the ﬁrst element of this sequence). The output to odeint is a matrix where each row contains the solution vector at each requested time point (thus, the initial conditions are given in the ﬁrst output row). The following example illustrates the use of odeint including the usage of the Dfun option which allows the user to specify a gradient (with respect to y ) of the function, f (y, t).

>>> >>> >>> >>> >>> >>> ... from scipy.integrate import odeint from scipy.special import gamma, airy y1_0 = 1.0/3**(2.0/3.0)/gamma(2.0/3.0) y0_0 = -1.0/3**(1.0/3.0)/gamma(1.0/3.0) y0 = [y0_0, y1_0] def func(y, t): return [t*y[1],y[0]]

14

Chapter 1. SciPy Tutorial

t. leastsq: Levenberg-Marquardt. An detailed listing is available: scipy.324067 0.355028 0.. Global (brute-force) optimization routines (e.308763 0. return [[0.t): . Multivariate equation system solvers (fsolve) 6.324068 >>> print y[:36:6. This minimum can be found using the fmin routine as shown in the example below: 1.1 Nelder-Mead Simplex algorithm (fmin) The simplex algorithm is probably the simplest way to minimize a fairly well-behaved function. newton_krylov) Below. 1.optimize (can also be found by help(scipy..339511 0. it may take longer to ﬁnd the minimum. Brent’s method fminbound. anneal) 3.. fmin_cobyla: COBYLA). Optimization (optimize) 15 .339511 0. several examples demonstrate their basic usage. 2 The minimum value of this function is 0 which is achieved when xi = 1.optimize package provides several commonly used optimization algorithms. t) y2 = odeint(func.g. because it does not use any gradient evaluations.g. fmin_ncg: Newton Conjugate Gradient.g.355028 0.. y0.0]] >>> >>> >>> >>> >>> x = arange(0.278806] 1.278806] >>> print y2[:36:6. and newton) 5.355028 0. 0. However.293658 0. The simplex algorithm requires only function evaluations and is a good choice for simple minimization problems.g. The module contains: 1. Large-scale multivariate equation system solvers (e. To demonstrate the minimization function consider the problem of minimizing the Rosenbrock function of N variables: N −1 f (x) = i=1 100 xi − x2 i−1 2 + (1 − xi−1 ) .1] [ 0.[1. Dfun=gradient) >>> print ychk[:36:6] [ 0.5.4.293658 0.293658 0.. fmin_bfgs: BFGS.324067 0.308763 0.SciPy Reference Guide.1] [ 0.0. fmin: Nelder-Mead simplex. 2. Scalar function minimizers and root ﬁnders (e.optimize)).278806] 0.01) t = x ychk = airy(x)[0] y = odeint(func.5. Curve ﬁtting (curve_fit) 4.0.t].dev6665 >>> def gradient(y.339511 0. Release 0.5 Optimization (optimize) The scipy. y0.308763 0. Unconstrained and constrained minimization and least-squares algorithms (e.10.

= This expression is valid for the interior derivatives. If the gradient is not given by the user. To demonstrate this algorithm. SciPy Tutorial .2*(1-xm) . this routine uses the gradient of the objective function.. der = zeros_like(x) . 1. The Broyden-Fletcher-Goldfarb-Shanno (BFGS) method typically requires fewer function calls than the simplex algorithm even when the gradient must be estimated. xm_m1 = x[:-2] . 1. Current function value: 0. x0... 1. 1.0) >>> x0 = [1..0 + (1-x[:-1])**2.. 0 = 200 xN −1 − x2 −2 . N A Python function which computes this gradient is constructed by the code-segment: >>> def rosen_der(x): . xm_p1 = x[2:] .j − 2xi−1 δi−1.0.7. der[1:-1] = 200*(xm-xm_m1**2) .5.SciPy Reference Guide..j .. xm = x[1:-1] .0*(x[1:]-x[:-1]**2. >>> from scipy. 1...400*(xm_p1 . xtol=1e-8) Optimization terminated successfully. """The Rosenbrock function""" .optimize import fmin >>> def rosen(x): .] Another optimization algorithm that needs only function calls to ﬁnd the minimum is Powell’s method available as fmin_powell.10. return sum(100. An example usage of fmin_bfgs is shown in the following example which minimizes the Rosenbrock function. the Rosenbrock function is again used....9....xm**2)*xm .2] >>> xopt = fmin(rosen.2 Broyden-Fletcher-Goldfarb-Shanno algorithm (fmin_bfgs) In order to converge more quickly to the solution.. The gradient of the Rosenbrock function is the vector: ∂f ∂xj N = i=1 200 xi − x2 i−1 (δi.2*(1-x[0]) . 0.. 0. then it is estimated using ﬁrst-differences. return der The calling signature for the BFGS minimization algorithm is similar to fmin with the addition of the fprime argument. 2 200 xj − x2 j−1 − 400xj xj+1 − xj − 2 (1 − xj ) .dev6665 >>> from scipy.8..3. der[-1] = 200*(x[-1]-x[-2]**2) .. Special cases are ∂f ∂x0 ∂f ∂xN −1 = −400x0 x1 − x2 − 2 (1 − x0 ) . der[0] = -400*x[0]*(x[1]-x[0]**2) ..000000 Iterations: 339 Function evaluations: 571 >>> print xopt [ 1.0)**2. Release 0. 1.optimize import fmin_bfgs 16 Chapter 1.j ) − 2 (1 − xi−1 ) δi−1. 1.

N − 1] deﬁning the N × N matrix. This method is a modiﬁed Newton’s method and uses a conjugate gradient algorithm to (approximately) invert the local Hessian.3 Newton-Conjugate-Gradient (fmin_ncg) The method which requires the fewest function calls and is therefore often the fastest method to minimize functions of many variables is fmin_ncg.j ) − 400xi (δi+1. 1. Release 0. j ∈ [1. 1. the user can provide either a function to compute the Hessian matrix. Hij = i ∂xi ∂xj = 202 + 1200x2 − 400xi+1 δi.j − 400xi−1 δi−1.7. 1. fprime=rosen_der) Optimization terminated successfully. j ∈ [0. As a result.j .j ) − 400δi. N − 2] with i. To take full advantage of the NewtonCG method.5.3. or a function to compute the product of the Hessian with an arbitrary vector. 1. .000000 Iterations: 53 Function evaluations: 65 Gradient evaluations: 65 >>> print xopt [ 1. 2 where H (x0 ) is a matrix of second-derivatives (the Hessian).] 1.j xi+1 − x2 + 2δi. = 200. only a vector which is the product of the Hessian with an arbitrary vector needs to be available to the minimization routine. 0. 0. Current function value: 0.j − 400xi δi+1. 0 −400x1 202 + 1200x2 − 400x3 2 −400x2 0 0 0 −400x2 202 + 1200x2 − 400x4 3 −400x3 0 0 0 −400x3 200 17 . Optimization (optimize) if i.10.9. the Hessian when N = 5 is 1200x2 − 400x1 + 2 −400x0 0 −400x0 202 + 1200x2 − 400x2 1 0 −400x1 H= 0 0 0 1. The Hessian matrix itself does not need to be constructed.2] >>> xopt = fmin_bfgs(rosen.j .SciPy Reference Guide.0.j − 2xi−1 δi−1.5. The inverse of the Hessian is evaluted using the conjugate-gradient method. resulting in xopt = x0 − H−1 f. Other non-zero entries of the matrix are = 1200x2 − 400x1 + 2. 0 = −400x0 . Full Hessian example: The Hessian of the Rosenbrock function is ∂2f = 200 (δi.8. i ∂2f ∂x2 0 2 2 ∂ f ∂ f = ∂x0 ∂x1 ∂x1 ∂x0 ∂2f ∂2f = ∂xN −1 ∂xN −2 ∂xN −2 ∂xN −1 ∂2f ∂x2 −1 N For example.j − 2xi δi. Newton’s method is based on ﬁtting the function locally to a quadratic form: 1 T f (x) ≈ f (x0 ) + f (x0 ) · (x − x0 ) + (x − x0 ) H (x0 ) (x − x0 ) . a function which computes the Hessian must be provided. x0. 1. An example of employing this method to minimizing the Rosenbrock function is given below. = −400xN −2 . If the Hessian is positive deﬁnite then the local minimum of this function can be found by setting the gradient of the quadratic form to zero. 1.dev6665 >>> x0 = [1.

9.. fhess=rosen_hess. Hp = zeros_like(x) .optimize import fmin_ncg >>> def rosen_hess(x): .....0. Any extra arguments passed to the function to be minimized will also be passed to this function. In this case. the user can supply code to compute this product rather than the full Hessian by setting the fhess_p keyword to the desired function. SciPy Tutorial . 1. storing the entire Hessian matrix can consume considerable time and memory. diagonal[1:-1] = 202 + 1200*x[1:-1]**2 .. 0.. −400xN −2 pN −2 + 200pN −1 Code which makes use of the fhess_p keyword to minimize the Rosenbrock function using fmin_ncg follows: >>> from scipy.. then H (x) p has elements: 1200x2 − 400x1 + 2 p0 − 400x0 p1 0 . The Newton-CG algorithm only needs the product of the Hessian times an arbitrary vector.-1) .1) . x0.7.optimize import fmin_ncg >>> def rosen_hess_p(x.10.2] >>> xopt = fmin_ncg(rosen. .SciPy Reference Guide.. 18 Chapter 1. If p is the . . −400xi−1 pi−1 + 202 + 1200x2 − 400xi+1 pi − 400xi pi+1 H (x) p = i ..400*x[0]*p[1] .diag(400*x[:-1]..dev6665 The code which computes this Hessian along with the code to minimize the function using fmin_ncg is shown in the following example: >>> from scipy.. diagonal[-1] = 200 . return H >>> x0 = [1.. .. 1. 1. diagonal = zeros_like(x) . If possible. Hp[0] = (1200*x[0]**2 . using Newton-CG with the hessian product option is probably the fastest way to minimize the function. . rosen_der.. x = asarray(x) .. 1. return Hp compute. diagonal[0] = 1200*x[0]-400*x[1]+2 ... Release 0.400*x[2:] . Hp[1:-1] = -400*x[:-2]*p[:-2]+(202+1200*x[1:-1]**2-400*x[2:])*p[1:-1] \ . -400*x[1:-1]*p[2:] .400*x[1] + 2)*p[0] . avextol=1e-8) Optimization terminated successfully. the product of the Rosenbrock Hessian with an arbitrary vector is not difﬁcult to arbitrary vector... H = diag(-400*x[:-1]. Current function value: 0.. 1..3. 0. H = H + diag(diagonal) ... As a result.p): .... 1..] Hessian product example: For larger minimization problems... x = asarray(x) .8. Hp[-1] = -400*x[-2]*p[-2] + 200*p[-1] . The fhess_p function should take the minimization vector as the ﬁrst argument and the arbitrary vector as the second argument.000000 Iterations: 23 Function evaluations: 26 Gradient evaluations: 23 Hessian evaluations: 23 >>> print xopt [ 1.

k.0/3e-2.5. N −1 J (p) = i=0 e2 (p) . yi . It takes as an input argument the vector function e (p) and returns the value of p which minimizes J (p) = eT e directly.theta = p ..10. A common method for determining which parameter vector gives the best ﬁt to the data is to minimize the sum of squares of the residuals. 1.3.k.] 1. 1. The residual is usually deﬁned for each observed data-point as ei (p. This is shown in the following example: >>> >>> >>> >>> >>> from numpy import * x = arange(0. pi/6 y_true = A*sin(2*pi*k*x+theta) y_meas = y_true + 2*random.. 1. An example should clarify the usage.randn(len(x)) >>> def residuals(p. and θ are unknown..4 Least-square ﬁtting (leastsq) All of the previously-explained minimization procedures can be used to solve a least-squares problem provided the appropriate objective function is constructed.. k . x): .theta = 10.9. By deﬁning a function to compute the residuals and (selecting an appropriate starting position). suppose it is desired to ﬁt a set of data {xi . y.. it is estimated. p): . Current function value: 0. 1. For example.SciPy Reference Guide. Optimization (optimize) 19 .0. Release 0. 0. yi } to a known model.5. A. The residual vector is ei = |yi − A sin (2πkxi + θ)| .2] >>> xopt = fmin_ncg(rosen. Suppose it is believed some measured data follow a sinusoidal pattern yi = A sin (2πkxi + θ) where the parameters A. 1.6e-2/30) A.7.6e-2. return p[0]*sin(2*pi*p[1]*x+p[2]) 1. 1. the least-squares ﬁt ˆ ˆ ˆ routine can be used to ﬁnd the best-ﬁt parameters A. 1.8. The user is also encouraged to provide the Jacobian matrix of the function (with derivatives down the columns or across the rows). p) where p is a vector of parameters for the model that need to be found. i The leastsq algorithm performs this squaring and summing of the residuals automatically. p) . avextol=1e-8) Optimization terminated successfully. k. xi ) = yi − f (xi . If the Jacobian is not provided.. θ. x0..000000 Iterations: 22 Function evaluations: 25 Gradient evaluations: 22 Hessian evaluations: 54 >>> print xopt [ 1. err = y-A*sin(2*pi*k*x+theta) . fhess_p=rosen_hess_p. rosen_der. y = f (x. 0. An objective function to pass to any of the previous minization algorithms to obtain a least-squares ﬁt is.dev6665 >>> x0 = [1. return err >>> def peval(x..

M XL ≤ x ≤ XU. .4 from Numerical Methods for Engineers by Steven Chapra and Raymond Canale.peval(x.01 Least-squares fit to noisy data Fit Noisy True 0.00 0.plot(x.02 0.pyplot as plt plt.title(’Least-squares fit to noisy data’) plt. 1/2. pi/3] >>> print array(p0) [ 8.show() 15 10 5 0 5 10 15 0.y_true) plt..optimize import fmin_slsqp 20 Chapter 1. Release 0.3605 0. The following script shows examples for how constraints can be speciﬁed.04 0.. """ from scipy..3333 0. min F (x) subject to Cj (X) = 0.legend([’Fit’..x**2 .. args=(y_meas.2*y**2.5834] >>> print array([A.4783 1.5236] >>> >>> >>> >>> >>> import matplotlib.. which has a maximum at x=2.plsq[0]). N. Cj (x) ≥ 0.10. SciPy Tutorial .y_meas. ’True’]) plt.9437 33.0.5. I = 1. theta]) [ 10.0472] >>> from scipy.. MEQ j = MEQ + 1. x)) >>> print plsq[0] [ 10..y=1. j = 1. 33.x.5 Sequential Least-square ﬁtting with constraints (fmin_slsqp) This module implements the Sequential Least SQuares Programming optimization algorithm (SLSQP).optimize import leastsq >>> plsq = leastsq(residuals.’o’. . """ This script tests fmin_slsqp using Example 14.05 0. 43. k.x. This example maximizes the function f(x) = 2*x*y + 2*x . ’Noisy’.. . p0.03 0.3e-2.SciPy Reference Guide.dev6665 >>> p0 = [8.06 1.

[-1.). sign : float A multiplier for f.4*y) return array([ dfdx. Derivatives approximated.1. iprint=2. args=(-1.10. Optimization (optimize) 21 . 1000*(time()-t0).2*y**2) def testfunc_deriv(d. full_output=1) print "Elapsed time:".ones.0. *args): """ Parameters ---------d : list A list of two elements.x**2 .).5.0]. sqrt. args=(-1. "ms" print "Results".1.SciPy Reference Guide.0.0. where d[0] represents x and d[1] represents y in the following equation." t0 = time() x = fmin_slsqp(testfunc. finfo.0. [-1. Derivatives provided.0 x = d[0] y = d[1] return sign*(2*x*y + 2*x . iprint=2. """ try: sign = args[0] except: sign = 1. full_output=1) 1. equal to ‘‘2*x*y + 2*x . Since we want to optimize it.*args): """ This is the derivative of testfunc.dev6665 from numpy import array.2*y**2‘‘. dfdy ].x print "\n\n" print "Unbounded optimization. asfarray. Release 0.0 x = d[0] y = d[1] dfdx = sign*(-2*x + 2*y + 2) dfdy = sign*(2*x . Returns ------res : float The result. zeros def testfunc(d.0].float) from time import time print ’\n\n’ print "Unbounded optimization.0." t0 = time() x = fmin_slsqp(testfunc.x**2 . we need to multiply it by -1 to achieve the desired solution. and the scipy optimizers can only minimize functions. returning a numpy array representing df/dx and df/dy """ try: sign = args[0] except: sign = 1.

fprime=testfunc_deriv. "ms" print "Results". y: x[0]-x[1] ].x print "\n\n" print "Bound optimization (equality constraints).0.0].[-1. f_eqcons=test_eqcons. "ms" 22 Chapter 1. "ms" print "Results". eqcons=[lambda x." print "Derivatives provided via functions. full_output=1) print "Elapsed time:"." t0 = time() x = fmin_slsqp(testfunc. [-1. full_output=1) print "Elapsed time:". 1000*(time()-t0). iprint=2. SciPy Tutorial .0]." t0 = time() x = fmin_slsqp(testfunc. iprint=2.0. Derivatives approximated.0.x print "\n\n" def test_eqcons(d.0]. "ms" print "Results". 1000*(time()-t0).x print "\n\n" print "Bound optimization (equality and inequality constraints).).*args): try: sign = args[0] except: sign = 1. 1000*(time()-t0).0].0 x = d[0] y = d[1] return array([ x**3-y ]) def test_ieqcons(d.1.10.).1." print "Derivatives provided.). y: x[0]-x[1] ]. fprime=testfunc_deriv.0." t0 = time() x = fmin_slsqp(testfunc. 1000*(time()-t0)." t0 = time() x = fmin_slsqp(testfunc. full_output=1) print "Elapsed time:". eqcons=[lambda x. Derivatives provided. full_output=1) print "Elapsed time:". [-1. args=(-1. args=(-1.dev6665 print "Elapsed time:". f_ieqcons=test_ieqcons. y: x[0]-. iprint=2. y: x[0]-x[1] ]. args=(-1.5].0.SciPy Reference Guide. Release 0.0. eqcons=[lambda x. 1000*(time()-t0).0 x = d[0] y = d[1] return array([ y-1 ]) print "Bound optimization (equality and inequality constraints).0. iprint=2.x print "\n\n" print "Bound optimization. [-1. fprime=testfunc_deriv.0.1. "ms" print "Results".0.1.*args): try: sign = args[0] except: sign = 1.). args=(-1. ieqcons=[lambda x.

f_eqcons=test_eqcons. A bracket is a triple (a. Unconstrained minimization (brent) There are actually two methods that can be used to minimize a scalar function (brent and golden).1. but golden is included only for academic purposes and should rarely be used.SciPy Reference Guide. fprime_eqcons=test_fprime_eqcons. full_output=1) print "Elapsed time:".0 ]) print "Bound optimization (equality and inequality constraints). Optimization (optimize) 23 .x print "\n\n" 1.[-1.). Release 0.6 Scalar function minimizers Often only the minimum of a scalar function is needed (a scalar function is one that takes a scalar as input and returns a scalar output). In these circumstances. Optimally a bracket should be given which contains the minimum desired. The fminbound 1. b. there are constraints that can be placed on the solution space before minimization occurs.0.10.0.5. fprime=testfunc_deriv. then alternatively two starting points can be chosen and a bracket will be found from these points using a simple marching algorithm.0. The brent method uses Brent’s algorithm for locating a minimum. args=(-1. 1000*(time()-t0)." print "Constraint jacobians provided via functions" t0 = time() x = fmin_slsqp(testfunc.0 ]) def test_fprime_ieqcons(d. 1.0*(x**2. iprint=2. however.5. If this is not given. "ms" print "Results". fprime_ieqcons=test_fprime_ieqcons.0 x = d[0] y = d[1] return array([ 0.0 x = d[0] y = d[1] return array([ 3.0).0.dev6665 print "Results".*args): try: sign = args[0] except: sign = 1. c) such that f (a) > f (b) < f (c) and a < b < c . other optimization techniques have been developed that can work faster.0]. -1. Very often. Bounded minimization (fminbound) Thus far all of the minimization routines described have been unconstrained minimization routines.*args): try: sign = args[0] except: sign = 1." print "Derivatives provided via functions.x print "\n\n" def test_fprime_eqcons(d. If these two starting points are not provided 0 and 1 will be used (this may not be the right choice for your function and result in an unexpected minimum being returned). f_ieqcons=test_ieqcons.

x[1] .SciPy Reference Guide. For example. the command roots is useful.5041.50409711 0. 5. the following example ﬁnds the roots of the single-variable transcendental equation x + 2 cos (x) = 0.special import j1 >>> from scipy. Each of these root ﬁnding algorithms requires the endpoints of an interval where a root is suspected (because the function changes signs). The results are x = −1. out. fminbound can be called using the interval [4.7 Root ﬁnding Sets of equations To ﬁnd the roots of a polynomial. return x + 2*cos(x) >>> def func2(x): . 24 Chapter 1.. For example.3314 : >>> from scipy. return out >>> from scipy. the command fsolve is needed..9084 . The result is xmin = 5.. 1]) >>> print x02 [ 6. [1.append(x[1]*x[0] . 7) >>> print xmin 5... out = [x[0]*cos(x[1]) .3) >>> print x0 -1.. 0.optimize import fsolve >>> x0 = fsolve(func.optimize import fminbound >>> xmin = fminbound(j1. but the other methods may be useful in certain circumstances or for academic purposes.90841421] Scalar function root ﬁnding If one has a single-variable equation. In general brentq is the best choice. and the set of non-linear equations x0 cos (x1 ) x0 x1 − x1 = = 4.0299 and x0 = 6. To ﬁnd a root of a set of non-linear equations.0.dev6665 function is an example of a constrained minimization procedure that provides a rudimentary interval constraint for scalar functions. The interval constraint allows the minimization to occur only between two ﬁxed endpoints. x1 = 0. there are four different root ﬁnder algorithms that can be tried.4] .5.02986652932 >>> x02 = fsolve(func2. SciPy Tutorial . to ﬁnd the minimum of J1 (x) near x = 5 . 4.33144184241 1. >>> def func(x): . Release 0. 7] as a constraint..10.5) ..

-2])/hy/hy return d2x + d2y + 5*cosh(P).2*P[:. This becomes rather inefﬁcent when N grows. because Nx Ny can be large.5. with a small 2 grid spacing h.0] + P_bottom)/hy/hy d2y[:. mgrid./(ny-1) P_left.8 Root ﬁnding: Large problems The fsolve function cannot deal with a very large number of variables (N).2*P[-1] + P[-2])/hx/hx d2y[:. broyden2. P_bottom = 1. The problem is then equivalent to ﬁnding the root of some function residual(P).optimize import newton_krylov from numpy import cosh.1:-1] = (P[:.1] .5. ny = 75. 1] × [0. Optimization (optimize) 25 .-1] = (P_top . The problem we have can now be solved as follows: import numpy as np from scipy.2*P[0] + P_left)/hx/hx d2x[-1] = (P_right .m ≈ P (nh. Pn. 0 def residual(P): d2x = zeros_like(P) d2y = zeros_like(P) d2x[1:-1] = (P[2:] . 1. zeros_like.0] = (P[:.-1] + P[:.2:] . The solution can however be found using one of the large-scale solvers in scipy. 1]: 1 2 2 (∂x + ∂y )P + 5 0 0 1 2 cosh(P ) dx dy =0 with the boundary condition P (x. Consider for instance the following problem: we need to solve the following integrodifferential equation on the square [0. The derivatives and integrals can then be approximated. zeros # parameters nx.:-2])/hy/hy d2y[:. Release 0. as it needs to calculate and invert a dense N x N Jacobian matrix on every Newton step. 1. for instance ∂x P (x. 1) = 1 on the upper edge and P = 0 elsewhere on the boundary of the square. or anderson./(nx-1). The routine fixed_point provides a simple iterative method using Aitkens sequence acceleration to estimate the ﬁxed point of g given a starting point.2*P[:.10. P_right = 0. hy = 1.0. fsolve will take a long time to solve this problem. Clearly the ﬁxed point of g is the root of f (x) = g (x) − x. Now.SciPy Reference Guide. Equivalently.mean()**2 1.optimize. mh). 0 P_top. the root of f is the ﬁxed_point of g (x) = f (x) + x.2*P[1:-1] + P[:-2]) / hx/hx d2x[0] = (P[1] . for example newton_krylov. These use what is known as the inexact Newton method. A ﬁxed point of a function is the point at which evaluation of the function returns the point: g (x) = x. where P is a vector of length Nx Ny . which instead of computing the Jacobian matrix exactly.dev6665 Fixed-point solving A problem closely related to ﬁnding the zeros of a function is the problem of ﬁnding a ﬁxed-point of a function. y) − 2 2P (x. y) ≈ (P (x + h. y))/h .2*P[:. This can be done by approximating the continuous function P by its values on a grid. y) + P (x − h.1:-1] + P[:. forms an approximation for it. 75 hx.

. ny). guess. When looking for the zero of the functions fi (x) = 0.SciPy Reference Guide. For the problem in the previous section.15 Still too slow? Preconditioning..LinearOperator instance. . ∂xj If you have an approximation for the inverse matrix M ≈ J −1 .60 0. and the second is the integral. max_rank=50. verbose=1) #sol = anderson(residual.2 0.0 0. Jij = ∂fi .45 0.dev6665 # solve guess = zeros((nx.6 0.pyplot as plt x.8 1.0 0.90 0. SciPy Tutorial .sparse. guess. sol) plt.0. y. We can actually easily compute the 26 Chapter 1. 2.pcolor(x. M=10. guess.show() 1. The idea is that instead of solving Js = y one solves M Js = M y: since matrix M J is “closer” to the identity matrix than J is. the equation should be easier for the Krylov method to deal with.linalg. verbose=1) #sol = broyden2(residual.4 0.30 0.8 0.0 0. [∂x + ∂y ]P . y = mgrid[0:1:(nx*1j). abs(residual(sol)).max() # visualize import matplotlib.10. we note that the function to solve consists of two parts: the ﬁrst one is 2 2 application of the Laplace operator..colorbar() plt. 0:1:(ny*1j)] plt. verbose=1) print ’Residual’. float) sol = newton_krylov(residual. It can be a (sparse) matrix or a scipy. the newton_krylov solver spends most of its time inverting the Jacobian matrix. i = 1.6 0.75 0.4 0. Release 0.0 0.2 0. The matrix M can be passed to newton_krylov as the inner_M parameter. you can use it for preconditioning the linear inversion problem. N.

spilu). P_right = 0.sparse. eye(ny)) + spkron(eye(nx).1]. nx) diags_y = zeros((3. [-1. We need to wrap it into # a LinearOperator before it can be passed to the Krylov methods: M = LinearOperator(shape=(nx*ny. matvec=J1_ilu. 0 P_top. mgrid. 0 def get_preconditioner(): """Compute the preconditioner M""" diags_x = zeros((3. Ly) # Now we have the matrix ‘J_1‘.:] = 1/hx/hx diags_x[1.linalg import spilu.optimize import newton_krylov from scipy. 1. nx.SciPy Reference Guide.:] = -2/hx/hx diags_x[2. it will be difﬁcult to invert. we can use # the *incomplete LU* decomposition J1_ilu = spilu(J1) # This returns an object with a method .. LinearOperator from numpy import cosh. so that the whole 2-D operator is represented by 2 2 J1 = ∂x + ∂y we know that in one dimension 1 0 0··· −2 1 0 · · · = h−2 L x 1 −2 1 · · · h−2 L ⊗ I + h−2 I ⊗ L x y The matrix J2 of the Jacobian corresponding to the integral is more difﬁcult to calculate. since an approximate inverse is enough.0.10. zeros./(nx-1). ny. spkron from scipy. Release 0.:] = 1/hx/hx Lx = spdiags(diags_x.1].dev6665 Jacobian corresponding to the Laplace operator part: −2 1 1 2 ∂x ≈ 2 hx 0 . ny = 75. P_bottom = 1.:] = -2/hy/hy diags_y[2. Optimization (optimize) 27 . J1 on the other hand is a relatively simple matrix.linalg./(ny-1) P_left.:] = 1/hy/hy Ly = spdiags(diags_y.sparse import spdiags. We need to find its inverse ‘M‘ -# however. hy = 1. nx)) diags_x[0. and since all of it entries are nonzero. −1 So we are content to take M ≈ J1 and hope for the best. 75 hx.linalg. ny)) diags_y[0.solve() that evaluates # the corresponding matrix-vector product.sparse. and can be inverted by scipy. import numpy as np from scipy. ny) J1 = spkron(Lx.solve) return M 1.sparse. we use the preconditioner M = J1 . eye # parameters nx.:] = 1/hy/hy diags_y[1.0. −1 In the example below. zeros_like. [-1.. nx*ny).splu (or the inverse can be approximated by scipy.0.5.

2*P[:. verbose=1. tol 0.2*P[:.:-2])/hy/hy d2y[:.colorbar() plt. 1) plt. step 1.0348109 1. count[0] return sol def main(): sol = solve(preconditioning=True) # visualize import matplotlib.clf() plt.614.-1] = (P_top .2*P[:. float) sol = newton_krylov(residual.-2])/hy/hy return d2x + d2y + 5*cosh(P).pyplot as plt x.03303.2*P[0] + P_left)/hx/hx d2x[-1] = (P_right . Release 0.3682. SciPy Tutorial .10. step 1.2*P[-1] + P[-2])/hx/hx d2y[:.912.1:-1] = (P[:. tol 0. y = mgrid[0:1:(nx*1j). y. 0:1:(ny*1j)] plt. abs(residual(sol)).1:-1] + P[:. sol) plt. step 1.0] = (P[:. step 1.159.clim(0.2*P[1:-1] + P[:-2])/hx/hx d2x[1:-1] = (P[2:] d2x[0] = (P[1] .0] + P_bottom)/hy/hy d2y[:. tol 0.1] .pcolor(x.0406634. tol 0.000257947 345. ﬁrst without preconditioning: 0: 1: 2: 3: 4: 5: |F(x)| |F(x)| |F(x)| |F(x)| |F(x)| |F(x)| = = = = = = 803.00128227 0.00139451 28 Chapter 1.mean()**2 # preconditioner if preconditioning: M = get_preconditioner() else: M = None # solve guess = zeros((nx. ny). tol 0. tol 0.2:] .max() print ’Evaluations’.0.-1] + P[:.show() if __name__ == "__main__": main() Resulting run.SciPy Reference Guide.145657 27. inner_M=M) print ’Residual’. step 1.166755 139.dev6665 def solve(preconditioning=True): """Compute the solution""" count = [0] def residual(P): count[0] += 1 d2x = zeros_like(P) d2y = zeros_like(P) . step 1. guess.

00698e-09..993. tol 0.80983. tol 0. step 1. 2. 4.00645373 7: |F(x)| = 0. Object-oriented interface for the underlying routines is also available.00179246 8: |F(x)| = 6.00173256 Residual 3.195942. References Some further reading and related software: 1.interpolate) Contents • Interpolation (scipy. 1. good preconditioning can be crucial — it can even decide whether the problem is solvable in practice or not. tol 0. tol 0.49599e-06 1: |F(x)| = 4.44604e-06 4: |F(x)| = 1.000153671. tol 2.00149362 3: |F(x)| = 0. offering several interpolation methods. • Interpolation using Radial Basis Functions.interpolate) 29 . step 1. Interpolation (scipy.00110945 2: |F(x)| = 0. step 1. Release 0. tol 7.dev6665 6: |F(x)| = 0.SciPy Reference Guide.6. There are both procedural and object-oriented interfaces for the FITPACK library. step 1..00344341.and 2-dimensional (smoothed) cubic-spline interpolation. step 1. step 1.splXXX) * Spline interpolation in 1-d: Object-oriented (UnivariateSpline) * Two-dimensional spline representation: Procedural (bisplrep) * Two-dimensional spline representation: Object-oriented (BivariateSpline) – Using radial basis functions for smoothing/interpolation * 1-d Example * 2-d Example There are several general interpolation facilities available in SciPy.10. and higher dimensions: • A class representing an interpolant (interp1d) in 1-D. tol 0. • Convenience function griddata offering a simple interface to interpolation in N dimensions (N = 1.6 Interpolation (scipy. science.0. for data in 1. Here. we were lucky in making a simple choice that worked reasonably well. 3.000563597. Preconditioning is an art. based on the FORTRAN library FITPACK. but there is a lot more depth to this topic than is shown here.interpolate) – 1-D interpolation (interp1d) – Multivariate data interpolation (griddata) – Spline interpolation * Spline interpolation in 1-d: Procedural (interpolate.87308e-12 Residual 9. For problems where the residual is expensive to compute. and industry.29603061195e-11 Evaluations 77 Using a preconditioner reduced the number of evaluations of the residual function by a factor of 4.). tol 7. step 1. 2. step 1. • Functions for 1.57078908664e-07 Evaluations 317 and then with preconditioning: 0: |F(x)| = 136.7424e-06. .

pi*y**2)**2 on a grid in [0.plot(x. for instance for an underlying function f(x. Behavior at the boundary can be speciﬁed at instantiation time. kind=’cubic’) xnew = np.6 0. 10. f2(xnew).2 Multivariate data interpolation (griddata) Suppose you have multidimensional data.’-’.0 0. 40) import matplotlib. xnew.2 0.’--’) plt.interpolate import interp1d >>> >>> >>> >>> >>> >>> >>> >>> >>> x = np.1 1-D interpolation (interp1d) The interp1d class in scipy.pyplot as plt plt. Suppose we want to interpolate the 2-D function >>> def func(x.cos(4*np. for linear and cubic spline interpolation: >>> from scipy. The instance of this class deﬁnes a __call__ method and can therefore by treated like a function which interpolates between known data values to obtain unknown values (it also has a docstring for help).linspace(0.10. ’linear’.4 0. y) f2 = interp1d(x. Release 0.exp(-x/3.xnew. y. grid_y = np. loc=’best’) plt.legend([’data’.8 0.6.interpolate is a convenient method to create a function based on ﬁxed data points which can be evaluated anywhere within the domain deﬁned by the given data using linear interpolation. 10) y = np. ’cubic’]. 1] >>> grid_x.pi*x) * np. The following example demonstrates its use.6.0. SciPy Tutorial .0) f = interp1d(x.show() 1. y): >>> return x*(1-x)*np.SciPy Reference Guide. 0:1:200j] but we only know its values at 1000 data points: 30 Chapter 1.0 0 2 4 6 8 data linear cubic 10 1.linspace(0. 10.dev6665 1. 1]x[0. y[i]) that do not form a regular grid. An instance of this class is created by passing the 1-d vectors comprising the data.f(xnew).’o’.mgrid[0:1:100j.y.sin(4*np. y) you only know the values at points (x[i].

6) plt. origin=’lower’) plt.title(’Cubic’) plt.1).10.0.T. points[:.title(’Linear’) plt. extent=(0.interpolate) 31 .0]. origin=’lower’) plt.imshow(func(grid_x. method=’nearest’) grid_z1 = griddata(points. (grid_x. but for this smooth function the piecewise cubic interpolant gives the best results: >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> import matplotlib.pyplot as plt plt.imshow(grid_z2.1. values. points[:.0.interpolate import griddata grid_z0 = griddata(points.subplot(222) plt. grid_y). extent=(0.1.set_size_inches(6.1.1).0.subplot(221) plt.plot(points[:.subplot(224) plt. ms=1) plt. (grid_x. method=’cubic’) One can see that the exact result is reproduced by all of the methods to some degree. grid_y).gcf().0. Interpolation (scipy.1).1.T.1]) This can be done with griddata – below we try out all of the interpolation methods: >>> >>> >>> >>> from scipy.0].1).SciPy Reference Guide.imshow(grid_z0. (grid_x. values. extent=(0.T. values.title(’Nearest’) plt.show() 1.rand(1000.0. method=’linear’) grid_z2 = griddata(points.1].’. grid_y).dev6665 >>> points = np. grid_y).subplot(223) plt. extent=(0. origin=’lower’) plt.title(’Original’) plt.random. ’k.T. 2) >>> values = func(points[:.6. Release 0.imshow(grid_z1. origin=’lower’) plt.

0 0.splXXX) Spline interpolation requires two essential steps: (1) a spline representation of the curve is computed.2 Original 1.0 0.8 1.0 0.2 0. and each array provides one component of the N -dimensional data point.0 0.0 Cubic 1. Release 0.2 0. (t.4 0.0 0. k) .2 0. The ﬁrst two arguments are the only ones required. The default spline order is cubic.2 0.8 0. The parameter variable is given with the keword argument.6 0. The normal output is a 3-tuple.3 Spline interpolation Spline interpolation in 1-d: Procedural (interpolate. u.6 0.8 0. c.6 0.0. k.2 Nearest 0.0 0. In order to ﬁnd the spline representation.dimensional plane using the function splrep. but this can be changed with the input keyword.6 0. and these provide the x and y components of the curve.2 0.0 0. t .4 0.0 0.8 1.6 0.0 0. The direct method ﬁnds the spline representation of a curve in a two.6.4 0.8 1.0 0.4 0.dev6665 1.8 1. which defaults to an equally-spaced monotonic 32 Chapter 1. containing the knot-points.8 0.0 0. there are two different ways to represent a curve and obtain (smoothing) spline coefﬁcients: directly and parametrically. For this function only 1 input argument is required. the coefﬁcients c and the order k of the spline.0 1.4 0.6 0.10. and (2) the spline is evaluated at the desired points.4 0. The length of each array is the number of curve points.SciPy Reference Guide.0 Linear 1. SciPy Tutorial .0 0.2 0.4 0. This input is a list of N -arrays representing the curve in N -dimensional space.6 0.4 0.6 0.0 0. For curves in N -dimensional space the function splprep allows deﬁning the curve parametrically.8 0.

sin(xnew). s . The default output consists of two objects: a 3-tuple. functions are available for evaluating the spline (splev) and its derivatives (splev.x.2*np. These functions are demonstrated in the example that follows.pi/8) y = np.33.05.-1.arange(0.interpolate) 33 .2*np.’x’. Once the spline representation of the data has been determined. containing the spline representation and the parameter variable u.plot(x. k) .der=0) plt.pi+np.axis([-0.plot(xnew. (t.5 1.s=0) xnew = np.05.6. is used to specify the amount of smoothing to perform during the spline ﬁt. the roots of the spline can be estimated ( sproot).10.show() 1.yder. if no smoothing is desired a value of s = 0 should be passed to the routines.legend([’Linear’.der=1) plt.05. ’True’]) plt.33.6.0.sin(x) tck = interpolate.y.05]) plt.tck.figure() plt.0 0.y.np.tck.splev(xnew.6.splev(xnew. Interpolation (scipy.xnew.xnew. The keyword argument. c.axis([-0.pi/50) ynew = interpolate.y.arange(0.np.’--’) plt.title(’Derivative estimation from spline’) 1. >>> import numpy as np >>> import matplotlib.dev6665 sequence between 0 and 1 .cos(xnew). Therefore.splrep(x. ’True’]) plt.1.figure() plt. spalde) at any point and the integral of the spline between any two points ( splint).0 0. Release 0. for cubic splines ( k = 3 ) with 8 or more knots.np.legend([’Cubic Spline’.05.5 0.SciPy Reference Guide. The default √ value of s is s = m − 2m where m is the number of data-points being ﬁt.pyplot as plt >>> from scipy import interpolate Cubic-spline >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> x = np.pi/4.title(’Cubic-spline interpolation’) plt. In addition.xnew.’b’) plt.0 0 1 Cubic-spline interpolation Linear Cubic Spline True 2 3 4 5 6 Derivative of spline >>> >>> >>> >>> >>> >>> yder = interpolate.1.05]) plt.pi.-1.ynew.’Cubic Spline’.2*np.

SciPy Tutorial .constant=-1): x = np. Release 0.05.-1.05.figure() plt.0 0.6.yint.tck) plt.xnew.SciPy Reference Guide.dtype) for n in xrange(len(out)): out[n] = interpolate.05]) plt.title(’Integral estimation from spline’) plt.33.show() 34 Chapter 1.’--’) plt.atleast_1d(x) out = np.legend([’Cubic Spline’.0 0 1 Derivative estimation from spline Cubic Spline True 2 3 4 5 6 Integral of spline >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> def integ(x.1.0.0 0.-np.zeros(x. ’True’]) plt.shape.axis([-0.plot(xnew.tck) out += constant return out yint = integ(xnew.dev6665 >>> plt.splint(0.tck.10. dtype=x.show() 1.cos(xnew).5 1.5 0.x[n].

interpolate) 35 .np.’Cubic Spline’. ’True’]) plt.pi*t) y = np.0 0.tck) plt.s=0) unew = np.pi*unew).1.1.sin(2*np.0.sproot(tck) [ 0.0.10. Release 0.dev6665 1.y.01) out = interpolate.np.sin(2*np.05]) plt.out[0]..cos(2*np.1.SciPy Reference Guide.5 1.arange(0.title(’Spline of parametrically-defined curve’) plt.-1.05.0 0 1 Integral estimation from spline Cubic Spline True 2 3 4 5 6 Roots of spline >>> print interpolate.5 0.1.splprep([x.splev(unew.pi*unew).pi*t) tck.05.05.y].show() 1.arange(0.figure() plt.’x’.1) x = np.1.1416] Parametric spline >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> t = np.axis([-1.x.’b’) plt.cos(2*np.legend([’Linear’.out[1].01.plot(x.u = interpolate. 3.0 0.y.6. Interpolation (scipy.

x.SciPy Reference Guide.’x’.sin(xnew). derivatives. This is shown in the example below for the subclass InterpolatedUnivariateSpline. The LSQUnivarateSpline is the other subclass of UnivarateSpline. The one dimensional splines are objects of the UnivariateSpline class. The UnivariateSpline class can also be used to smooth data by providing a non-zero value of the smoothing parameter s. This results in a spline that has fewer knots than the number of data points. to interpolate in some domains and smooth in others.0 Spline of parametrically-defined curve Linear Cubic Spline True 0.5 0. but rather a smoothing spline.dev6665 1. returning the interpolated y-values.1.np.legend([’Linear’.’InterpolatedUnivariateSpline’.’b’) plt.pi/8) y = np.2*np. derivatives. and hence is no longer strictly an interpolating spline.xnew. and are created with the x and y components of the curve provided as arguments to the constructor. and roots to be computed for the spline. If this is not desired.05]) 36 Chapter 1. ’True’]) plt.pi/50) ynew = s(xnew) plt.0 Spline interpolation in 1-d: Object-oriented (UnivariateSpline) The spline-ﬁtting capabilities described above are also available via an objected-oriented interface.05.-1. allowing the object to be called with the x-axis values at which the spline should be evaluated.pi/4. >>> import numpy as np >>> import matplotlib.10. with the same meaning as the s keyword of the splrep function described above.2*np. allowing deﬁnite integrals. This allows creation of customized splines with non-linear spacing. and roots methods are also available on UnivariateSpline objects.y. It allows the user to specify the number and location of internal knots as explicitly with the parameter t. The class deﬁnes __call__.0 0. or change the character of the spline.6.pi+np. It is a subclass of UnivariateSpline that always passes through all points (equivalent to forcing the smoothing parameter to 0).0 0.05.InterpolatedUnivariateSpline(x. SciPy Tutorial .5 1.ynew.np.arange(0.plot(x. the InterpolatedUnivariateSpline class is available.figure() plt.5 0. Release 0.0.y.xnew.2*np.0 0.y) xnew = np.5 1.sin(x) s = interpolate.pyplot as plt >>> from scipy import interpolate InterpolatedUnivariateSpline >>> >>> >>> >>> >>> >>> >>> >>> >>> x = np. This class is demonstrated in the example below.arange(0.0 1.axis([-0. The methods integral.pi.33.

t. ’True’]) plt.xnew.10.0.0 0 1 InterpolatedUnivariateSpline Linear InterpolatedUnivariateSpline True 2 3 4 5 6 LSQUnivarateSpline with non-uniform knots >>> t = [np.x.pi/2+.y.1] >>> s = interpolate.0 0.05.axis([-0.k=2) >>> ynew = s(xnew) >>> >>> >>> >>> >>> >>> plt.np.1.np.SciPy Reference Guide.6.05.legend([’Linear’.title(’Spline with Specified Interior Knots’) plt.LSQUnivariateSpline(x.33.05]) plt.pi/2-.3*np.5 1.’x’. Release 0.y.sin(xnew).show() 1.dev6665 >>> plt.plot(x.0 0 1 Spline with Specified Interior Knots Linear LSQUnivariateSpline True 2 3 4 5 6 1.0 0.5 1.1.figure() plt.ynew.’b’) plt.pi/2+.interpolate) 37 . Interpolation (scipy.5 0.show() 1.5 0.1.1.’LSQUnivariateSpline’.3*np.0 0.y.pi/2-.xnew.title(’InterpolatedUnivariateSpline’) >>> plt.6.0 0.-1.

The keyword.pcolor(x. SciPy Tutorial .figure() plt.title("Sparsely sampled function. tck. Release 0.05 0.0.00 0. This function takes as required inputs the 1-D arrays x. c. This example uses the numpy. ky] whose entries represent respectively.0 0. It is convenient to hold this list in a single object. can be used to change the amount of smoothing √ performed on the data while determining the appropriate spline. and the order of the spline in each coordinate. As a result. the components of the knot positions. The default output is a list [tx.colorbar() plt. To evaluate the two-dimensional spline and it’s partial derivatives (up to the order of the spline). This function takes as the ﬁrst two arguments two 1-D arrays whose cross-product speciﬁes the domain over which to evaluate the spline.z) plt. The default value is s = m − 2m where m is the number of data points in the x.pyplot as plt Deﬁne function over sparse 20x20 grid >>> x. If desired.10.mgrid command in SciPy which is useful for deﬁning a “mesh-grid “in many dimensions.15 0.-1:1:20j] >>> z = (x+y)*np.y = np. >>> import numpy as np >>> from scipy import interpolate >>> import matplotlib. the fourth and ﬁfth arguments provide the orders of the partial derivative in the x and y direction respectively. so that it can be passed easily to the function bisplev. It is important to note that two dimensional interpolation should not be used to ﬁnd the spline representation of images. the function bisplev is required. ty. The two dimensional interpolation commands are intended for use when interpolating a two dimensional function as shown in the example that follows.0 1. y. if no smoothing is desired.mgrid[-1:1:20j.mgrid. the function bisplrep is available.0 Sparsely sampled function. The algorithm used is not amenable to large numbers of input points.0 0.y.10 0.20 0. y) .20 0.0 38 Chapter 1.5 0.ogrid command if the full-mesh is not needed).show() 1. The third argument is the tck list returned from bisplrep.0*(x*x+y*y)) >>> >>> >>> >>> >>> plt. the coefﬁcients of the spline.5 1.5 0.exp(-6. s . 0. The number of output arguments and the number of dimensions of each argument is determined by the number of indexing objects passed in numpy. then s = 0 should be passed to bisplrep . The signal processing toolbox contains more appropriate algorithms for ﬁnding the spline representation of an image. and z which represent points on the surface z = f (x.10 0.05 0.15 0. (See also the numpy.SciPy Reference Guide.0 0. kx.") plt.5 1.dev6665 Two-dimensional spline representation: Procedural (bisplrep) For (smooth) spline-ﬁtting to a two dimensional surface. and z vectors. y.

05 0.0 0.5 0.y. 10.dev6665 Interpolate function over new 70x70 grid >>> xnew.show() 1. 10.0].0.10 0.20 0.z.interpolate module.interpolate import Rbf.05 0.20 0.ynew.") plt.interpolate) 39 . InterpolatedUnivariateSpline >>> import matplotlib. but should be used with caution for extrapolation outside of the observed data range.bisplrep(x. >>> import numpy as np >>> from scipy. Interpolation (scipy.figure() plt. It and its subclasses implement the FITPACK functions described above in an object oriented fashion. 1.colorbar() plt.SciPy Reference Guide.00 0.15 0.0 Interpolated function.6.4 Using radial basis functions for smoothing/interpolation Radial basis functions can be used for smoothing/interpolating scattered data in n-dimensions.0 0.tck) >>> >>> >>> >>> >>> plt.:]. Release 0.ynew = np.linspace(0.znew) plt.s=0) >>> znew = interpolate.0 0.bisplev(xnew[:.6.mgrid[-1:1:70j.sin(x) xi = np.5 1. 101) 1.10.-1:1:70j] >>> tck = interpolate.title("Interpolated function.pyplot as plt >>> >>> >>> >>> # setup data x = np.10 0.pcolor(xnew.ynew[0. 9) y = np.5 0. allowing objects to be instantiated that can be called to compute the spline value by passing in the two coordinates as the two arguments.5 1. 0.linspace(0. 1-d Example This example compares the usage of the Rbf and UnivariateSpline classes from the scipy.15 0.0 Two-dimensional spline representation: Object-oriented (BivariateSpline) The BivariateSpline class is the 2-dimensional analog of the UnivariateSpline class.0 1.

setup scattered data x = np. 1.rand(100)*4. ’r’) plt. 2) plt.sin(xi). y.0 0. SciPy Tutorial .0-2. 1.5 1.plot(xi.0 0 Interpolation using univariate spline Interpolation4 using RBF . ’g’) plt.10.show() 1.5 0.plot(xi.random.linspace(-2.0 1.plot(x. np. ’g’) plt.plot(xi. y) >>> yi = ius(xi) >>> >>> >>> >>> >>> plt.subplot(2.multiquadrics’) plt.interpolate import Rbf import matplotlib.random. ’bo’) plt. 2.sin(xi).5 1. y.0 0 0.0 0.plot(xi. fi.exp(-x**2-y**2) ti = np. ’r’) plt.meshgrid(ti. yi.dev6665 >>> # use fitpack2 method >>> ius = InterpolatedUnivariateSpline(x. ’bo’) plt.0.0.0 y = np.rand(100)*4.5 0. np. 100) XI. y) >>> fi = rbf(xi) >>> >>> >>> >>> >>> >>> plt.pyplot as plt from matplotlib import cm # 2-d tests .title(’Interpolation using RBF . >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> import numpy as np from scipy.subplot(2. 1) plt.6 multiquadrics 2 8 10 2 4 6 8 10 2-d Example This example shows how to interpolate scattered 2d data.0-2.SciPy Reference Guide. Release 0. ti) 40 Chapter 1.plot(x.0 z = x*np.0 0. YI = np.title(’Interpolation using univariate spline’) >>> # use RBF method >>> rbf = Rbf(x.0.

0 0.3 0.1 0.fftpack) Warning: This is currently a stub page Contents • Fourier Transforms (scipy.) plt.SciPy Reference Guide. cmap=cm.0 RBF interpolation .1 0.0 1.10.fftpack) 41 . cmap=cm.multiquadrics’) plt. Release 0.7.normalize(-2. epsilon=2) >>> ZI = rbf(XI.dev6665 >>> # use RBF >>> rbf = Rbf(x. y. 1. y. 100.5 1. z. Fourier Transforms (scipy.colorbar() 2.5 1.5 2.0 0. 1) plt.pcolor(XI.0 1.0 1. 2.ylim(-2.0 0. z.2 0. ZI.7 Fourier Transforms (scipy.4 0.multiquadrics 2.0 0. 2) plt.5 0.jet) plt.jet) plt.title(’RBF interpolation .5 2.5 0.3 0.5 1.xlim(-2..scatter(x.0 1.0.subplot(1.fftpack) – Fast Fourier transforms – One dimensional discrete Fourier transforms – Two and n dimensional discrete Fourier transforms – Discrete Cosine Transforms * type I * type II * type III * References – FFT convolution 1. YI. YI) >>> >>> >>> >>> >>> >>> >>> >>> >>> # plot the result n = plt.0 0. 2) plt.4 1.2 0.5 1.0 0.

1 Fast Fourier transforms 1. There are theoretically 8 types of the DCT [WP]. only the ﬁrst 3 types are implemented in scipy. called the Fast Fourier Transform (FFT). rfft. type I There are several deﬁnitions of the DCT-I. and ‘the’ Inverse DCT generally refers to DCT type 3.7. SciPy Tutorial . Only None is supported as normalization mode for DCT-I.7. ‘The’ DCT generally refers to DCT type 2.0. we use the following (for norm=None): N −1 yk = 2 n=0 xn cos π(2n + 1)k 2N 0 ≤ k < N.SciPy Reference Guide.3 Two and n dimensional discrete Fourier transforms fft in more than one dimension 1. Press et al. otherwise Which makes the corresponding matrix of coefﬁcients orthonormal (OO’ = Id). The DFT has become a mainstay of numerical computing in part because of a very fast algorithm for computing it.7. 0 ≤ k < N.2 One dimensional discrete Fourier transforms fft. When both the function and its Fourier transform are replaced with discretized counterparts. norm=’ortho’) is equal to MATLAB dct(x).dev6665 Fourier analysis is fundamentally a method for expressing a function as a sum of periodic components. and for recovering the signal from those components.4 Discrete Cosine Transforms Return the Discrete Cosine Transform [Mak] of arbitrary type sequence x. irfft 1. Release 0.7. Note also that the DCT-I is only supported for input size > 1 type II There are several deﬁnitions of the DCT-II. which was known to Gauss (1805) and was brought to light in its current form by Cooley and Tukey [CT]. dct(x.10. we use the following (for norm=None): N −2 yk = x0 + (−1)k xN −1 + 2 n=1 xn cos πnk N −1 . [NR] provide an accessible introduction to Fourier analysis and its applications. If norm=’ortho’. ifft. if k = 0 1/(2N ). it is called the discrete Fourier transform (DFT). For a single dimension array x. 42 Chapter 1. 1. yk is multiplied by a scaling factor f : f= 1/(4N ).

The orthonormalized DCT-III is exactly the inverse of the orthonormalized DCT-II. x y (x) ≈ cj β o −j . o . integral. Signal Processing (signal) 43 . they are included here because they only work with equally-spaced data and make heavy use of ﬁlter-theory and transfer-function formalism to provide a fast B-spline transform. cj .10. or. the function representation is z (x.SciPy Reference Guide. 1. Release 0. allows the development of fast (inverse-ﬁltering) algorithms for determining the coefﬁcients. ∆y In these expressions. y) ≈ j k cjk β o x − j βo ∆x y −k . References 1.8 Signal Processing (signal) The signal processing toolbox currently contains some ﬁltering functions.sampling. To understand this section you will need to understand that a signal in SciPy is an array of real or complex numbers. etc.) which assume that the data samples are drawn from an underlying continuous function can be computed with relative ease from the spline coefﬁcients. 1.8.domain in terms of B-spline coefﬁcients and knot points. While the B-spline algorithms could technically be placed under the interpolation category.5 FFT convolution scipy.convolve performs a convolution of two one-dimensional arrays in frequency domain. the second-derivative of a spline is 1 x y (x) = cj β o −j .dev6665 type III There are several deﬁnitions. up to a factor 2N. The requirement of equallyspaced knot-points and equally-spaced data points. ∆x j In two dimensions with knot-spacing ∆x and ∆y . ∆x2 j ∆x 1. then the B-spline approximation to a 1-dimensional function is the ﬁnite-basis expansion. for norm=’ortho’: x0 1 yk = √ + √ N N N −1 xn cos n=1 πn(2k + 1) 2N 0 ≤ k < N.and two-dimensional data.0. and a few B-spline interpolation algorithms for one. Unlike the general spline interpolation algorithms. If the knot. The advantage of representing a set of samples via B-spline basis functions is that continuous-domain operators (derivatives.fftpack. β o (·) is the space-limited B-spline basis function of order. The (unnormalized) DCT-III is the inverse of the (unnormalized) DCT-II. For example. these algorithms can quickly ﬁnd the spline coefﬁcients for large images. yn .8.points are equally spaced with spacing ∆x . from sample-values.1 B-splines A B-spline is an approximation of a continuous function over a ﬁnite. re. a limited set of ﬁlter design tools.7. we use the following (for norm=None): N −1 yk = x0 + 2 n=1 xn cos πn(2k + 1) 2N 0 ≤ k < N.

1. A function to compute this Gaussian for arbitrary x and o is also available ( signal. derfilt.0]]. and data-samples can be recovered exactly from the spline coefﬁcients by assuming them to be mirror-symmetric also. the B-spline basis function can be approximated well by a zero-mean Gaussian function with standard-deviation equal to σo = (o + 1) /12 : β o (x) ≈ 1 x2 exp − 2 2σo 2πσo . derfilt) Alternatively we could have done: laplacian = array([[0.1. For large o .0) deriv = signal. so that simple convolution with the sampled B-spline function recovers the original data from the spline coefﬁcients. spline coefﬁcients are computed based on that assumption.1. misc >>> import matplotlib. If o = 3 .10. signal. then at the sample points.sepfir2d(ck. Thus.boundary=’symm’) 44 Chapter 1.0. smoothing splines can be found to make the second-derivative less sensitive to random-errors.cspline1d. Thus.laplacian. This function is ideally suited for reconstructing samples from spline coefﬁcients and is faster than signal.SciPy Reference Guide. SciPy Tutorial .float32) ck = signal. The output of convolutions can change depending on how boundaries are handled (this becomes increasingly more important as the number of dimensions in the data. The package also supplies a function ( signal.qspline1d.convolve2d which convolves arbitrary two-dimensional ﬁlters and allows for choosing mirror-symmetric boundary conditions.cspline2d).sepfir2d(ck. The command signal. if desired.cspline2d(image.qspline2d. = cn+1 − 2cn + cn−1 .sepfir2d was used to apply a separable two-dimensional FIR ﬁlter with mirror.[1. The following code and Figure uses spline-ﬁltering to compute an edge-image (the second-derivative of a smoothed spline) of Lena’s face which is an array returned by the command lena.-4. signal. Currently the package provides functions for determining second.astype(float32) derfilt = array([1.[0. [1].-2.convolve2d(ck.symmetric boundary conditions to the spline coefﬁcients.and two-dimensions (signal. β o (x) for arbitrary order and x.pyplot as plt >>> >>> >>> >>> >>> image = misc.0]. >>> from numpy import * >>> from scipy import signal.8.set increases).0].gauss_spline ). [1]) + \ signal. The savvy reader will have already noticed that the data samples are related to the knot coefﬁcients via a convolution operator.1]. Release 0. ∆x2 y (x)|x=n∆x = j cj δn−j+1 − 2cj δn−j + cj δn−j−1 .bspline ) for evaluating the bspline basis function.processing sub package assume mirror-symmetric boundary conditions. the second-derivative signal can be easily calculated from the spline ﬁt.float32) deriv2 = signal.and third-order cubic spline coefﬁcients from equally spaced samples in one.lena(). signal.0.dev6665 Using the property of B-splines that d2 β o (w) = β o−2 (w + 1) − 2β o−2 (w) + β o−2 (w − 1) dw2 it can be seen that y (x) = 1 ∆x2 cj β o−2 j x x x − j + 1 − 2β o−2 − j + β o−2 −j−1 ∆x ∆x ∆x .mode=’same’. The algorithms relating to B-splines in the signal.

show() 0 100 200 300 400 500 0 Original image 100 200 300 400 500 >>> >>> >>> >>> >>> plt.figure() plt.imshow(deriv) plt.8.title(’Output of spline edge filter’) plt.2 Filtering Filtering is a generic name for any system that modiﬁes an input signal in some way. Signal Processing (signal) 45 . There are different kinds of ﬁlters for different kinds of operations.gray() plt.8.dev6665 >>> >>> >>> >>> >>> plt.figure() plt.gray() plt.10. In SciPy a signal can be thought of as a Numpy array.imshow(image) plt.SciPy Reference Guide.0. Release 0.show() 0 100 200 300 400 500 0 Output of spline edge filter 100 200 300 400 500 1. There are two broad kinds 1.title(’Original image’) plt.

0. 719. 476. . 46 Chapter 1. If the ﬂag has a value of ‘valid’ then only the middle K − M + 1 = (K + 1) − (M + 1) + 1 output values are returned where z depends on all of the values of the smallest input from h [0] to h [M ] . . Release 0. y [M ] = x [0] h [M ] + x [1] h [M − 1] + · · · + x [M ] h [0] y [M + 1] = x [1] h [M ] + x [2] h [M − 1] + · · · + x [M + 1] h [0] .0) x [k] h [n − k] . . At 4 bytes per element this would require 256GB of memory. .10. more explicitly the output of this operation is y [0] = x [0] h [0] y [1] = x [0] h [1] + x [1] h [0] y [2] = x [0] h [2] + x [1] h [1] + x [2] h [0] . . then the discrete convolution expression is min(n. . . . Linear ﬁlters can always be reduced to multiplication of the ﬂattened Numpy array by an appropriate matrix resulting in another ﬂattened Numpy array. choose n = 0 to be the starting point of both sequences. .SciPy Reference Guide. SciPy Tutorial . y [K] = x [K − M ] h [M ] + · · · + x [K] h [0] y [K + 1] = x [K + 1 − M ] h [M ] + · · · + x [K] h [1] . The default value of ‘full’ returns the entire signal. the matrix multiplication can be accomplished using Fourier transforms. In most applications most of the elements of this matrix are zero and a different method for computing the output of the ﬁlter is employed. In this case. . . This function takes as inputs the signals x. Let x [n] deﬁne a one-dimensional signal indexed by the integer n. h . . If the ﬂag has a value of −1 ‘same’ then only the middle K values are returned starting at y M2 so that the output has the same length as the largest input. . . Full convolution of two one-dimensional signals can be expressed as ∞ y [n] = k=−∞ x [k] h [n − k] . and an optional ﬂag and returns the signal y. . the full discrete convolution of two ﬁnite sequences of lengths K + 1 and M + 1 respectively results in a ﬁnite sequence of length K + M + 1 = (K + 1) + (M + 1) − 1. For example ﬁltering a 512 × 512 image with this method would require multiplication of a 5122 ×5122 matrix with a 5122 vector. . this is not usually the best way to compute the ﬁlter as the matrices and vectors involved may be huge. Thus. .K) y [n] = k=max(n−M. Convolution/Correlation Many linear ﬁlters also have the property of shift-invariance.convolve . . . y [K + M − 1] y [K + M ] = x [K − 1] h [M ] + x [K] h [M − 1] = x [K] h [M ] . This means that the ﬁltering operation is the same at different locations in the signal and it implies that the ﬁltering matrix can be constructed from knowledge of one row (or column) of the matrix alone. In other words only the values y [M ] to y [K] inclusive are returned. . let K + 1 be that value for which y [n] = 0 for all n > K + 1 and M + 1 be that value for which x [n] = 0 for all n > M + 1 . One dimensional convolution is implemented in SciPy with the function signal. Then. The optional ﬂag allows for speciﬁcation of which part of the output signal to return. This equation can only be implemented directly if we limit the sequences to ﬁnite support sequences that can be stored in a computer.dev6665 of ﬁltering operations: linear and non-linear. Just trying to store the 5122 × 5122 matrix using a standard Numpy array would require 68. Of course. . . . 736 elements. . For convenience assume K ≥ M.

K] and x [n] = 0 outside of the range [0. . . The SciPy function signal.convolve can be used to construct arbitrary image ﬁlters to perform actions such as blurring.convolve can actually take N -dimensional arrays as inputs and will return the N -dimensional convolution of the two arrays. . . signal. . enhancing. y [0] x [2] + y [1] x [3] + · · · + y [M − 2] x [M ] . .10.8. y [K − 1] x [0] + y [K] x [1] .0.−n) y [k] x [n + k] . .correlate and/or signal. The same input ﬂags are available for that case as well. = y [0] x [1] + y [1] x [2] + · · · + y [M − 1] x [M ] = . The function signal. . . Assuming again that K ≥ M this is w [−K] w [−K + 1] . Thus ∞ w [n] = k=−∞ y [k] x [n + k] is the (cross) correlation of the signals y and x. . w [M − K] = y [K − M ] x [0] + y [K − M + 1] x [1] + · · · + y [K] x [M ] w [M − K + 1] = y [K − M − 1] x [0] + · · · + y [K − 1] x [M ] .M −n) w [n] = k=max(0.SciPy Reference Guide. w [−1] = y [1] x [0] + y [2] x [1] + · · · + y [M + 1] x [M ] w [0] = y [0] x [0] + y [1] x [1] + · · · + y [M ] x [M ] w [1] w [2] . w −K + M2 This ﬁnal option returns the K − M + 1 values w [M − K] to w [0] inclusive. When N = 2. Convolution is mainly used for ﬁltering when one of the signals is much smaller than the other ( K linear ﬁltering is more easily accomplished in the frequency domain (see Fourier Transforms). . . . .dev6665 This same function signal. . = y [K] x [0] = . the summation can simplify to min(K. . Release 0. Correlation is very similar to convolution except for the minus sign becomes a plus sign. and edge-detection for an image. . w [M − 1] = y [0] x [M − 1] + y [1] x [M ] w [M ] = y [0] x [M ] . Equivalent ﬂags are available for this operation to return the full K +M +1 length sequence (‘full’) or a sequence with the same size as the largest sequence starting at −1 (‘same’) or a sequence where the values depend on all the values of the smallest sequence (‘valid’). Difference-equation ﬁltering A general class of linear one-dimensional ﬁlters (that includes convolution ﬁlters) are ﬁlters described by the difference equation N M M ). . otherwise ak y [n − k] = k=0 k=0 bk x [n − k] 1. .correlate implements this operation. Signal Processing (signal) 47 . M ] .correlate can also take arbitrary N -dimensional arrays as input and return the N dimensional convolution of the two arrays on output. . For ﬁnite-length signals with y [n] = 0 outside of the range [0.

Often a0 = 1 is chosen for normalization. Sometimes it is more convenient to express the initial conditions in terms of the signals x [n] and y [n] . . to restart the calculation in the same state. . A general purpose median ﬁlter that works on N-dimensional arrays is signal. . Release 0. b2 x [n] + z2 [n − 1] − a2 y [n] . In other words. . However.medfilt . Median Filter A median ﬁlter is commonly applied when noise is markedly non. The difference-equation ﬁlter is called using the command signal. The sample median is the middle array value in a sorted list of neighborhood values. The actual implementation equations are (assuming a0 = 1 ). the output at time n depends only on the input at time n and the value of z0 at the previous time.Gaussian or when it is desired to preserve edges. If. zK−1 [n − 1] are computed and stored at each time step. The difference equation ﬁlter can be thought of as ﬁnding y [n] recursively in terms of it’s previous values a0 y [n] = −a1 y [n − 1] − · · · − aN y [n − N ] + · · · + b0 x [n] + · · · + bM x [n − M ] . desired. This command takes as inputs the vector b. If x is N -dimensional.dev6665 where x [n] is the input sequence and y [n] is the output sequence. The implementation in SciPy of this general difference equation ﬁlter is a little more complicated then would be implied by the previous equation. then this kind of ﬁlter can be implemented using convolution.SciPy Reference Guide. initial conditions providing the values of z0 [−1] to zK−1 [−1] can be provided or else it will be assumed that they are all zero. . K−m−1 zm [n] = p=0 (bm+p+1 x [n − p] − am+p+1 y [n − p]) . This can always be calculated as long as the K values z0 [n − 1] . Other ﬁlters The signal processing package provides many more ﬁlters as well.lfilter in SciPy. In addition. Using this formula we can ﬁnd the intial condition vector z0 [−1] to zK−1 [−1] given initial conditions on y (and x ). The median ﬁlter works by sorting all of the array pixel values in a rectangular region surrounding the point of interest. for example. a. then the ﬁlter is computed along the axis provided. In this way. If we assume initial rest so that y [n] = 0 for n < 0 .medfilt2d . then the ﬁnal conditions on the intermediate variables are also returned. These could be used. Note that bK = 0 if K > M and aK = 0 if K > N. perhaps you have the values of x [−M ] to x [−1] and the values of y [−N ] to y [−1] and would like to determine what values of zm [−1] should be delivered as initial conditions to the difference-equation ﬁlter. then the average of the middle two values is used as the median. .lfiltic performs this function. It is not difﬁcult to show that for 0 ≤ m < K. If there are an even number of elements in the neighborhood. It is implemented so that only one signal needs to be delayed.0. 48 Chapter 1. If initial conditions are provided. where K = max (N.10. The sample median of this list of neighborhood pixel values is used as the value for the output array. y [n] z0 [n] z1 [n] . the convolution ﬁlter sequence h [n] could be inﬁnite if ak = 0 for k ≥ 1. The command signal. SciPy Tutorial . the vector. zK−2 [n] zK−1 [n] = b0 x [n] + z0 [n − 1] = b1 x [n] + z1 [n − 1] − a1 y [n] = . M ) . = bK−1 x [n] + zK−1 [n − 1] − aK−1 y [n] = bK x [n] − aK y [n] . a signal x and returns the vector y (the same length as x ) computed using the equation given above. this general class of linear ﬁlter allows initial conditions to be placed on y [n] for n < 0 resulting in a ﬁlter that cannot be expressed using convolution. A specialized version that works only for two-dimensional arrays is available as signal. . .

For example if x = cos ωn then y = hilbert (x) would return (except near the edges) y = exp (jωn) . 0 for negative frequencies and 1 for zero-frequencies. . The order ﬁlter takes an additional argument besides the input array and the region mask that speciﬁes which of the elements in the sorted list of neighbor array values should be used as the output. For the median ﬁlter. and test the signiﬁcance of. 1. Fourier analysis. LSSA mitigates such problems. assumed to have been scaled and shifted such that its mean is zero and its variance is unity. then the output is σ2 σ2 2 2 2 2 σx mx + 1 − σx x σx ≥ σ . Nt Nt 2 2 2 j cos ω(tj − τ ) j sin ω(tj − τ ) Here. the normalized Lomb-Scargle periodogram at frequency f is 2 2 Nt Nt Xj cos ω(tj − τ ) Xj sin ω(tj − τ ) j j 1 Pn (f ) + . 2 Where mx is the local estimate of the mean and σx is the local estimate of the variance.8. In the frequency domain. the sample median of the list of array values is used as the output. Let x be the input signal. The parameter σ 2 is a threshold noise parameter. similar to Fourier analysis. the hilbert transform performs Y =X ·H where H is 2 for positive frequencies. Signal Processing (signal) 49 . The frequency dependent time offset τ is given by tan 2ωτ = Nt j Nt j sin 2ωtj cos 2ωtj . Nt ). . ω ≡ 2πf is the angular frequency. The window for these estimates is an optional input parameter (default is 3 × 3 ). Release 0. .order_filter . Lomb-Scargle Periodograms (spectral.3 Least-Squares Spectral Analysis (spectral) Least-squares spectral analysis (LSSA) is a method of estimating a frequency spectrum. local-mean ﬁlter.lombscargle) The Lomb-Scargle method performs spectral analysis on unevenly sampled data and is known to be a powerful way to ﬁnd. generally boosts long-periodic noise in long gapped records. A general order ﬁlter allows the user to select which of the sorted values will be used as the output. . y= 2 mx σx < σ 2 . Hilbert ﬁlter The Hilbert transform constructs the complex-valued analytic signal from a real signal. If σ is not given then it is estimated as the average of the local variances. all order ﬁlters use the array values in a region surrounding that pixel.10. based on a least squares ﬁt of sinusoids to data samples. For a time series comprising Nt measurements Xj ≡ X(tj ) sampled at times tj where (j = 1. Wiener ﬁlter The Wiener ﬁlter is a simple deblurring ﬁlter for denoising images. 1.SciPy Reference Guide. To compute the output at a particular pixel. weak periodic signals. the most used spectral method in science. for example one could choose to pick the maximum in the list or the minimum. The command to perform an order ﬁlter is signal. So. This is not the Wiener ﬁlter commonly described in image reconstruction problems but instead it is a simple.dev6665 Order Filter A median ﬁlter is a speciﬁc example of a more general class of ﬁlters called order ﬁlters. These array values are sorted and then one of them is selected as the output value.8.0.

SciPy Reference Guide, Release 0.10.0.dev6665

The lombscargle function calculates the periodogram using a slightly modiﬁed algorithm due to Townsend 1 which allows the periodogram to be calculated using only a single pass through the input arrays for each frequency. The equation is refactored as: Pn (f ) = and tan 2ωτ = Here, cτ = cos ωτ, while the sums are

Nt

(cτ XC + sτ XS)2 (cτ XS − sτ XC)2 1 + 2 2 CC + 2c s CS + s2 SS 2 cτ cτ SS − 2cτ sτ CS + s2 CC τ τ τ τ 2CS . CC − SS sτ = sin ωτ

XC =

j Nt

Xj cos ωtj

XS =

j Nt

**Xj sin ωtj cos2 ωtj
**

j Nt

CC =

SS =

j Nt

sin2 ωtj

CS =

j

cos ωtj sin ωtj .

This requires Nf (2Nt + 3) trigonometric function evaluations giving a factor of ∼ 2 speed increase over the straightforward implementation. References Some further reading and related software: data”, Astrophysics and Space Science, vol 39, pp. 447-462, 1976 Statistical aspects of spectral analysis of unevenly spaced data”, The Astrophysical Journal, vol 263, pp. 835-853, 1982 periodogram using graphics processing units.”, The Astrophysical Journal Supplement Series, vol 191, pp. 247-253, 2010

1.9 Linear Algebra

When SciPy is built using the optimized ATLAS LAPACK and BLAS libraries, it has very fast linear algebra capabilities. If you dig deep enough, all of the raw lapack and blas libraries are available for your use for even more speed. In this section, some easier-to-use interfaces to these routines are described. All of these linear algebra routines expect an object that can be converted into a 2-dimensional array. The output of these routines is also a two-dimensional array. There is a matrix class deﬁned in Numpy, which you can initialize with an appropriate Numpy array in order to get objects for which multiplication is matrix-multiplication instead of the default, element-by-element multiplication.

1

R.H.D. Townsend, “Fast calculation of the Lomb-Scargle

50

Chapter 1. SciPy Tutorial

SciPy Reference Guide, Release 0.10.0.dev6665

1.9.1 Matrix Class

The matrix class is initialized with the SciPy command mat which is just convenient short-hand for numpy.matrix. If you are going to be doing a lot of matrix-math, it is convenient to convert arrays into matrices using this command. One advantage of using the mat command is that you can enter two-dimensional matrices using MATLAB-like syntax with commas or spaces separating columns and semicolons separting rows as long as the matrix is placed in a string passed to mat .

1.9.2 Basic routines

Finding Inverse The inverse of a matrix A is the matrix B such that AB = I where I is the identity matrix consisting of ones down the main diagonal. Usually B is denoted B = A−1 . In SciPy, the matrix inverse of the Numpy array, A, is obtained using linalg.inv (A) , or using A.I if A is a Matrix. For example, let 1 3 5 A = 2 5 1 2 3 8 then A−1 −37 1 14 = 25 4 9 2 −3 22 −1.48 −9 = 0.56 1 0.16 0.36 0.08 −0.12 0.88 −0.36 . 0.04

**The following example demonstrates this computation in SciPy
**

>>> A = mat(’[1 3 5; 2 5 1; 2 3 8]’) >>> A matrix([[1, 3, 5], [2, 5, 1], [2, 3, 8]]) >>> A.I matrix([[-1.48, 0.36, 0.88], [ 0.56, 0.08, -0.36], [ 0.16, -0.12, 0.04]]) >>> from scipy import linalg >>> linalg.inv(A) array([[-1.48, 0.36, 0.88], [ 0.56, 0.08, -0.36], [ 0.16, -0.12, 0.04]])

Solving linear system Solving linear systems of equations is straightforward using the scipy command linalg.solve. This command expects an input matrix and a right-hand-side vector. The solution vector is then computed. An option for entering a symmetrix matrix is offered which can speed up the processing when applicable. As an example, suppose it is desired to solve the following simultaneous equations: x + 3y + 5z 2x + 5y + z 2x + 3y + 8z = = = 10 8 3

1.9. Linear Algebra

51

SciPy Reference Guide, Release 0.10.0.dev6665

We could ﬁnd the solution vector using a matrix inverse: x 1 y = 2 z 2 3 5 3 −1 −232 5 −9.28 10 1 129 = 5.16 . 1 8 = 25 19 8 0.76 3

However, it is better to use the linalg.solve command which can be faster and more numerically stable. In this case it however gives the same answer as shown in the following example:

>>> A = mat(’[1 3 5; 2 5 1; 2 3 8]’) >>> b = mat(’[10;8;3]’) >>> A.I*b matrix([[-9.28], [ 5.16], [ 0.76]]) >>> linalg.solve(A,b) array([[-9.28], [ 5.16], [ 0.76]])

Finding Determinant The determinant of a square matrix A is often denoted |A| and is a quantity often used in linear algebra. Suppose aij are the elements of the matrix A and let Mij = |Aij | be the determinant of the matrix left by removing the ith row and j th column from A . Then for any row i, |A| =

j

(−1)

i+j

aij Mij .

This is a recursive way to deﬁne the determinant where the base case is deﬁned by accepting that the determinant of a 1 × 1 matrix is the only matrix element. In SciPy the determinant can be calculated with linalg.det . For example, the determinant of 1 3 5 A = 2 5 1 2 3 8 is |A| = = 1 5 3 1 8 −3 2 2 1 8 +5 2 2 5 3

1 (5 · 8 − 3 · 1) − 3 (2 · 8 − 2 · 1) + 5 (2 · 3 − 2 · 5) = −25.

**In SciPy this is computed as shown in this example:
**

>>> A = mat(’[1 3 5; 2 5 1; 2 3 8]’) >>> linalg.det(A) -25.000000000000004

Computing norms Matrix and vector norms can also be computed with SciPy. A wide range of norm deﬁnitions are available using different parameters to the order argument of linalg.norm . This function takes a rank-1 (vectors) or a rank-2 (matrices) array and an optional order argument (default is 2). Based on these inputs a vector or matrix norm of the requested order is computed.

52

Chapter 1. SciPy Tutorial

SciPy Reference Guide, Release 0.10.0.dev6665

For vector x , the order parameter can be any real number including inf or -inf. The computed norm is max |xi | ord = inf min |xi | ord = −inf x = 1/ord ord |ord| < ∞. i |xi | For matrix A the only valid values for norm are ±2, ±1, ± inf, and ‘fro’ (or ‘f’) Thus, ord = inf maxi j |aij | min |aij | ord = −inf i j maxj ord = 1 i |aij | A = ord = −1 minj i |aij | max σi ord = 2 min σi ord = −2 trace (AH A) ord = ’fro’ where σi are the singular values of A . Solving linear least-squares problems and pseudo-inverses Linear least-squares problems occur in many branches of applied mathematics. In this problem a set of linear scaling coefﬁcients is sought that allow a model to ﬁt data. In particular it is assumed that data yi is related to data xi through a set of coefﬁcients cj and model functions fj (xi ) via the model yi =

j

cj fj (xi ) +

i

where

i

**represents uncertainty in the data. The strategy of least squares is to pick the coefﬁcients cj to minimize
**

2

J (c) =

i

yi −

j

cj fj (xi ) .

**Theoretically, a global minimum will occur when ∂J =0= ∂c∗ n or cj
**

j i ∗ fj (xi ) fn (xi )

∗ cj fj (xi ) (−fn (xi )) j

y i −

i

=

i

∗ yi fn (xi )

A Ac where

H

= AH y

**{A}ij = fj (xi ) . When AH A is invertible, then c = AH A
**

−1

AH y = A† y

where A† is called the pseudo-inverse of A. Notice that using this deﬁnition of A the model can be written y = Ac + . The command linalg.lstsq will solve the linear least squares problem for c given A and y . In addition linalg.pinv or linalg.pinv2 (uses a different method based on singular value decomposition) will ﬁnd A† given A. 1.9. Linear Algebra 53

SciPy Reference Guide, Release 0.10.0.dev6665

The following example and ﬁgure demonstrate the use of linalg.lstsq and linalg.pinv for solving a dataﬁtting problem. The data shown below were generated using the model: yi = c1 e−xi + c2 xi where xi = 0.1i for i = 1 . . . 10 , c1 = 5 , and c2 = 4. Noise is added to yi and the coefﬁcients c1 and c2 are estimated using linear least squares.

>>> from numpy import * >>> from scipy import linalg >>> import matplotlib.pyplot as plt >>> >>> >>> >>> >>> c1,c2= 5.0,2.0 i = r_[1:11] xi = 0.1*i yi = c1*exp(-xi)+c2*xi zi = yi + 0.05*max(yi)*random.randn(len(yi))

>>> A = c_[exp(-xi)[:,newaxis],xi[:,newaxis]] >>> c,resid,rank,sigma = linalg.lstsq(A,zi) >>> xi2 = r_[0.1:1.0:100j] >>> yi2 = c[0]*exp(-xi2) + c[1]*xi2 >>> >>> >>> >>> >>> plt.plot(xi,zi,’x’,xi2,yi2) plt.axis([0,1.1,3.0,5.5]) plt.xlabel(’$x_i$’) plt.title(’Data fitting with linalg.lstsq’) plt.show()

5.5 5.0 4.5 4.0 3.5 3.0 0.0 0.2

Data fitting with linalg.lstsq

0.4

xi

0.6

0.8

1.0

Generalized inverse The generalized inverse is calculated using the command linalg.pinv or linalg.pinv2. These two commands differ in how they compute the generalized inverse. The ﬁrst uses the linalg.lstsq algorithm while the second uses singular value decomposition. Let A be an M × N matrix, then if M > N the generalized inverse is A† = AH A 54

−1

AH Chapter 1. SciPy Tutorial

SciPy Reference Guide, Release 0.10.0.dev6665

**while if M < N matrix the generalized inverse is A# = AH AAH In both cases for M = N , then A† = A# = A−1 as long as A is invertible.
**

−1

.

1.9.3 Decompositions

In many applications it is useful to decompose a matrix using other representations. There are several decompositions supported by SciPy. Eigenvalues and eigenvectors The eigenvalue-eigenvector problem is one of the most commonly employed linear algebra operations. In one popular form, the eigenvalue-eigenvector problem is to ﬁnd for some square matrix A scalars λ and corresponding vectors v such that Av = λv. For an N × N matrix, there are N (not necessarily distinct) eigenvalues — roots of the (characteristic) polynomial |A − λI| = 0. The eigenvectors, v , are also sometimes called right eigenvectors to distinguish them from another set of left eigenvectors that satisfy H H vL A = λvL or AH vL = λ∗ vL . With it’s default optional arguments, the command linalg.eig returns λ and v. However, it can also return vL and just λ by itself ( linalg.eigvals returns just λ as well). In addtion, linalg.eig can also solve the more general eigenvalue problem Av A vL

H

= λBv = λ∗ BH vL

for square matrices A and B. The standard eigenvalue problem is an example of the general eigenvalue problem for B = I. When a generalized eigenvalue problem can be solved, then it provides a decomposition of A as A = BVΛV−1 where V is the collection of eigenvectors into columns and Λ is a diagonal matrix of eigenvalues. By deﬁnition, eigenvectors are only deﬁned up to a constant scale factor. In SciPy, the scaling factor for the eigenvec2 2 tors is chosen so that v = i vi = 1. As an example, consider ﬁnding the eigenvalues and eigenvectors of the matrix 1 5 2 A = 2 4 1 . 3 6 2

1.9. Linear Algebra

55

SciPy Reference Guide, Release 0.10.0.dev6665

The characteristic polynomial is |A − λI| = (1 − λ) [(4 − λ) (2 − λ) − 6] − 5 [2 (2 − λ) − 3] + 2 [12 − 3 (4 − λ)]

= −λ3 + 7λ2 + 8λ − 3. The roots of this polynomial are the eigenvalues of A : λ1 λ2 λ3 = 7.9579

= −1.2577 = 0.2997.

The eigenvectors corresponding to each eigenvalue can be found using the original equation. The eigenvectors associated with these eigenvalues can then be found.

>>> from scipy import linalg >>> A = mat(’[1 5 2; 2 4 1; 3 6 2]’) >>> la,v = linalg.eig(A) >>> l1,l2,l3 = la >>> print l1, l2, l3 (7.95791620491+0j) (-1.25766470568+0j) (0.299748500767+0j) >>> print v[:,0] [-0.5297175 -0.44941741 -0.71932146] >>> print v[:,1] [-0.90730751 0.28662547 0.30763439] >>> print v[:,2] [ 0.28380519 -0.39012063 0.87593408] >>> print sum(abs(v**2),axis=0) [ 1. 1. 1.] >>> v1 = mat(v[:,0]).T >>> print max(ravel(abs(A*v1-l1*v1))) 8.881784197e-16

Singular value decomposition Singular Value Decompostion (SVD) can be thought of as an extension of the eigenvalue problem to matrices that are not square. Let A be an M × N matrix with M and N arbitrary. The matrices AH A and AAH are square hermitian matrices 2 of size N × N and M × M respectively. It is known that the eigenvalues of square hermitian matrices are real and non-negative. In addtion, there are at most min (M, N ) identical non-zero eigenvalues of AH A and AAH . 2 Deﬁne these positive eigenvalues as σi . The square-root of these are called singular values of A. The eigenvectors of H A A are collected by columns into an N × N unitary 3 matrix V while the eigenvectors of AAH are collected by columns in the unitary matrix U , the singular values are collected in an M × N zero matrix Σ with main diagonal entries set to the singular values. Then A = UΣVH is the singular-value decomposition of A. Every matrix has a singular value decomposition. Sometimes, the singular values are called the spectrum of A. The command linalg.svd will return U , VH , and σi as an array of the singular values. To obtain the matrix Σ use linalg.diagsvd. The following example illustrates the use of linalg.svd .

2 3

A hermitian matrix D satisﬁes DH = D. A unitary matrix D satisﬁes DH D = I = DDH so that D−1 = DH .

56

Chapter 1. SciPy Tutorial

SciPy Reference Guide, Release 0.10.0.dev6665

>>> A = mat(’[1 3 2; 1 2 3]’) >>> M,N = A.shape >>> U,s,Vh = linalg.svd(A) >>> Sig = mat(linalg.diagsvd(s,M,N)) >>> U, Vh = mat(U), mat(Vh) >>> print U [[-0.70710678 -0.70710678] [-0.70710678 0.70710678]] >>> print Sig [[ 5.19615242 0. 0. ] [ 0. 1. 0. ]] >>> print Vh [[ -2.72165527e-01 -6.80413817e-01 -6.80413817e-01] [ -6.18652536e-16 -7.07106781e-01 7.07106781e-01] [ -9.62250449e-01 1.92450090e-01 1.92450090e-01]] >>> print A [[1 3 2] [1 2 3]] >>> print U*Sig*Vh [[ 1. 3. 2.] [ 1. 2. 3.]]

LU decomposition The LU decompostion ﬁnds a representation for the M × N matrix A as A = PLU where P is an M × M permutation matrix (a permutation of the rows of the identity matrix), L is in M × K lower triangular or trapezoidal matrix ( K = min (M, N ) ) with unit-diagonal, and U is an upper triangular or trapezoidal matrix. The SciPy command for this decomposition is linalg.lu . Such a decomposition is often useful for solving many simultaneous equations where the left-hand-side does not change but the right hand side does. For example, suppose we are going to solve Axi = bi for many different bi . The LU decomposition allows this to be written as PLUxi = bi . Because L is lower-triangular, the equation can be solved for Uxi and ﬁnally xi very rapidly using forward- and back-substitution. An initial time spent factoring A allows for very rapid solution of similar systems of equations in the future. If the intent for performing LU decomposition is for solving linear systems then the command linalg.lu_factor should be used followed by repeated applications of the command linalg.lu_solve to solve the system for each new right-hand-side. Cholesky decomposition Cholesky decomposition is a special case of LU decomposition applicable to Hermitian positive deﬁnite matrices. When A = AH and xH Ax ≥ 0 for all x , then decompositions of A can be found so that A A = UH U = LLH

1.9. Linear Algebra

57

SciPy Reference Guide, Release 0.10.0.dev6665

where L is lower-triangular and U is upper triangular. Notice that L = UH . The command linagl.cholesky computes the cholesky factorization. For using cholesky factorization to solve systems of equations there are also linalg.cho_factor and linalg.cho_solve routines that work similarly to their LU decomposition counterparts. QR decomposition The QR decomposition (sometimes called a polar decomposition) works for any M × N array and ﬁnds an M × M unitary matrix Q and an M × N upper-trapezoidal matrix R such that A = QR. Notice that if the SVD of A is known then the QR decomposition can be found A = UΣVH = QR implies that Q = U and R = ΣVH . Note, however, that in SciPy independent algorithms are used to ﬁnd QR and SVD decompositions. The command for QR decomposition is linalg.qr . Schur decomposition For a square N × N matrix, A , the Schur decomposition ﬁnds (not-necessarily unique) matrices T and Z such that A = ZTZH where Z is a unitary matrix and T is either upper-triangular or quasi-upper triangular depending on whether or not a real schur form or complex schur form is requested. For a real schur form both T and Z are real-valued when A is real-valued. When A is a real-valued matrix the real schur form is only quasi-upper triangular because 2 × 2 blocks extrude from the main diagonal corresponding to any complex- valued eigenvalues. The command linalg.schur ﬁnds the Schur decomposition while the command linalg.rsf2csf converts T and Z from a real Schur form to a complex Schur form. The Schur form is especially useful in calculating functions of matrices. The following example illustrates the schur decomposition:

>>> from scipy import linalg >>> A = mat(’[1 3 2; 1 4 5; 2 3 6]’) >>> T,Z = linalg.schur(A) >>> T1,Z1 = linalg.schur(A,’complex’) >>> T2,Z2 = linalg.rsf2csf(T,Z) >>> print T [[ 9.90012467 1.78947961 -0.65498528] [ 0. 0.54993766 -1.57754789] [ 0. 0.51260928 0.54993766]] >>> print T2 [[ 9.90012467 +0.00000000e+00j -0.32436598 +1.55463542e+00j -0.88619748 +5.69027615e-01j] [ 0.00000000 +0.00000000e+00j 0.54993766 +8.99258408e-01j 1.06493862 +1.37016050e-17j] [ 0.00000000 +0.00000000e+00j 0.00000000 +0.00000000e+00j 0.54993766 -8.99258408e-01j]] >>> print abs(T1-T2) # different [[ 1.24357637e-14 2.09205364e+00 6.56028192e-01] [ 0.00000000e+00 4.00296604e-16 1.83223097e+00] [ 0.00000000e+00 0.00000000e+00 4.57756680e-16]] >>> print abs(Z1-Z2) # different [[ 0.06833781 1.10591375 0.23662249]

58

Chapter 1. SciPy Tutorial

SciPy Reference Guide, Release 0.10.0.dev6665

[ 0.11857169 0.5585604 0.29617525] [ 0.12624999 0.75656818 0.22975038]] >>> T,Z,T1,Z1,T2,Z2 = map(mat,(T,Z,T1,Z1,T2,Z2)) >>> print abs(A-Z*T*Z.H) # same [[ 1.11022302e-16 4.44089210e-16 4.44089210e-16] [ 4.44089210e-16 1.33226763e-15 8.88178420e-16] [ 8.88178420e-16 4.44089210e-16 2.66453526e-15]] >>> print abs(A-Z1*T1*Z1.H) # same [[ 1.00043248e-15 2.22301403e-15 5.55749485e-15] [ 2.88899660e-15 8.44927041e-15 9.77322008e-15] [ 3.11291538e-15 1.15463228e-14 1.15464861e-14]] >>> print abs(A-Z2*T2*Z2.H) # same [[ 3.34058710e-16 8.88611201e-16 4.18773089e-18] [ 1.48694940e-16 8.95109973e-16 8.92966151e-16] [ 1.33228956e-15 1.33582317e-15 3.55373104e-15]]

1.9.4 Matrix Functions

Consider the function f (x) with Taylor series expansion

∞

f (x) =

k=0

f (k) (0) k x . k!

**A matrix function can be deﬁned using this Taylor series for the square matrix A as
**

∞

f (A) =

k=0

f (k) (0) k A . k!

While, this serves as a useful representation of a matrix function, it is rarely the best way to calculate a matrix function. Exponential and logarithm functions The matrix exponential is one of the more common matrix functions. It can be deﬁned for square matrices as

∞

eA =

k=0

1 k A . k!

The command linalg.expm3 uses this Taylor series deﬁnition to compute the matrix exponential. Due to poor convergence properties it is not often used. Another method to compute the matrix exponential is to ﬁnd an eigenvalue decomposition of A : A = VΛV−1 and note that eA = VeΛ V−1 where the matrix exponential of the diagonal matrix Λ is just the exponential of its elements. This method is implemented in linalg.expm2 . The preferred method for implementing the matrix exponential is to use scaling and a Padé approximation for ex . This algorithm is implemented as linalg.expm . The inverse of the matrix exponential is the matrix logarithm deﬁned as the inverse of the matrix exponential. A ≡ exp (log (A)) . The matrix logarithm can be obtained with linalg.logm . 1.9. Linear Algebra 59

SciPy Reference Guide, Release 0.10.0.dev6665

Trigonometric functions The trigonometric functions sin , cos , and tan are implemented for matrices in linalg.sinm, linalg.cosm, and linalg.tanm respectively. The matrix sin and cosine can be deﬁned using Euler’s identity as sin (A) cos (A) The tangent is tan (x) = and so the matrix tangent is deﬁned as sin (x) −1 = [cos (x)] sin (x) cos (x)

−1

= =

ejA − e−jA 2j jA e + e−jA . 2

[cos (A)] Hyperbolic trigonometric functions

sin (A) .

The hyperbolic trigonemetric functions sinh , cosh , and tanh can also be deﬁned for matrices using the familiar deﬁnitions: sinh (A) cosh (A) tanh (A) = = = eA − e−A 2 eA + e−A 2 −1 [cosh (A)] sinh (A) .

These matrix functions can be found using linalg.sinhm, linalg.coshm , and linalg.tanhm. Arbitrary function Finally, any arbitrary function that takes one complex number and returns a complex number can be called as a matrix function using the command linalg.funm. This command takes the matrix and an arbitrary Python function. It then implements an algorithm from Golub and Van Loan’s book “Matrix Computations “to compute function applied to the matrix using a Schur decomposition. Note that the function needs to accept complex numbers as input in order to work with this algorithm. For example the following code computes the zeroth-order Bessel function applied to a matrix.

>>> from scipy import special, random, linalg >>> A = random.rand(3,3) >>> B = linalg.funm(A,lambda x: special.jv(0,x)) >>> print A [[ 0.72578091 0.34105276 0.79570345] [ 0.65767207 0.73855618 0.541453 ] [ 0.78397086 0.68043507 0.4837898 ]] >>> print B [[ 0.72599893 -0.20545711 -0.22721101] [-0.27426769 0.77255139 -0.23422637] [-0.27612103 -0.21754832 0.7556849 ]] >>> print linalg.eigvals(A) [ 1.91262611+0.j 0.21846476+0.j -0.18296399+0.j] >>> print special.jv(0, linalg.eigvals(A)) [ 0.27448286+0.j 0.98810383+0.j 0.99164854+0.j] >>> print linalg.eigvals(B) [ 0.27448286+0.j 0.98810383+0.j 0.99164854+0.j]

60

Chapter 1. SciPy Tutorial

SciPy Reference Guide, Release 0.10.0.dev6665

Note how, by virtue of how matrix analytic functions are deﬁned, the Bessel function has acted on the matrix eigenvalues.

1.9.5 Special matrices

SciPy and NumPy provide several functions for creating special matrices that are frequently used in engineering and science. Type block diagonal circulant companion Hadamard Hankel Leslie Toeplitz Van der Monde Function scipy.linalg.block_diag scipy.linalg.circulant scipy.linalg.companion scipy.linalg.hadamard scipy.linalg.hankel scipy.linalg.leslie scipy.linalg.toeplitz numpy.vander Description Create a block diagonal matrix from the provided arrays. Construct a circulant matrix. Create a companion matrix. Construct a Hadamard matrix. Construct a Hankel matrix. Create a Leslie matrix. Construct a Toeplitz matrix. Generate a Van der Monde matrix.

For examples of the use of these functions, see their respective docstrings.

1.10 Statistics

1.10.1 Introduction

SciPy has a tremendous number of basic statistics routines with more easily added by the end user (if you create one please contribute it). All of the statistics functions are located in the sub-package scipy.stats and a fairly complete listing of these functions can be had using info(stats). Random Variables There are two general distribution classes that have been implemented for encapsulating continuous random variables and discrete random variables . Over 80 continuous random variables and 10 discrete random variables have been implemented using these classes. The list of the random variables available is in the docstring for the stats subpackage. Note: The following is work in progress

1.10.2 Distributions

First some imports

>>> >>> >>> >>> import numpy as np from scipy import stats import warnings warnings.simplefilter(’ignore’, DeprecationWarning)

**We can obtain the list of available distribution through introspection:
**

>>> dist_continu = [d for d in dir(stats) if ... isinstance(getattr(stats,d), stats.rv_continuous)] >>> dist_discrete = [d for d in dir(stats) if ... isinstance(getattr(stats,d), stats.rv_discrete)] >>> print ’number of continuous distributions:’, len(dist_continu)

1.10. Statistics

61

SciPy Reference Guide, Release 0.10.0.dev6665

number of continuous distributions: 84 >>> print ’number of discrete distributions: number of discrete distributions: 12

’, len(dist_discrete)

Distributions can be used in one of two ways, either by passing all distribution parameters to each method call or by freezing the parameters for the instance of the distribution. As an example, we can get the median of the distribution by using the percent point function, ppf, which is the inverse of the cdf:

>>> print stats.nct.ppf(0.5, 10, 2.5) 2.56880722561 >>> my_nct = stats.nct(10, 2.5) >>> print my_nct.ppf(0.5) 2.56880722561

help(stats.nct) prints the complete docstring of the distribution. Instead we can print just some basic information:

>>> print stats.nct.extradoc #contains the distribution specific docs Non-central Student T distribution df**(df/2) * gamma(df+1) nct.pdf(x,df,nc) = -------------------------------------------------2**df*exp(nc**2/2)*(df+x**2)**(df/2) * gamma(df/2) for df > 0, nc > 0.

>>> print ... number of >>> print ... bounds of

’number of arguments: %d, shape parameters: %s’% (stats.nct.numargs, stats.nct.shapes) arguments: 2, shape parameters: df,nc ’bounds of distribution lower: %s, upper: %s’ % (stats.nct.a, stats.nct.b) distribution lower: -1.#INF, upper: 1.#INF

We can list all methods and properties of the distribution with dir(stats.nct). Some of the methods are private methods, that are not named as such, i.e. no leading underscore, for example veccdf or xa and xb are for internal calculation. The main methods we can see when we list the methods of the frozen distribution:

>>> print dir(my_nct) #reformatted [’__class__’, ’__delattr__’, ’__dict__’, ’__doc__’, ’__getattribute__’, ’__hash__’, ’__init__’, ’__module__’, ’__new__’, ’__reduce__’, ’__reduce_ex__’, ’__repr__’, ’__setattr__’, ’__str__’, ’__weakref__’, ’args’, ’cdf’, ’dist’, ’entropy’, ’isf’, ’kwds’, ’moment’, ’pdf’, ’pmf’, ’ppf’, ’rvs’, ’sf’, ’stats’]

The main public methods are: • rvs: Random Variates • pdf: Probability Density Function • cdf: Cumulative Distribution Function • sf: Survival Function (1-CDF) • ppf: Percent Point Function (Inverse of CDF) • isf: Inverse Survival Function (Inverse of SF) • stats: Return mean, variance, (Fisher’s) skew, or (Fisher’s) kurtosis • moment: non-central moments of the distribution The main additional methods of the not frozen distribution are related to the estimation of distrition parameters:

62

Chapter 1. SciPy Tutorial

SciPy Reference Guide, Release 0.10.0.dev6665

• ﬁt: maximum likelihood estimation of distribution parameters, including location and scale • ﬁt_loc_scale: estimation of location and scale when shape parameters are given • nnlf: negative log likelihood function • expect: Calculate the expectation of a function against the pdf or pmf All continuous distributions take loc and scale as keyword parameters to adjust the location and scale of the distribution, e.g. for the standard normal distribution location is the mean and scale is the standard deviation. The standardized distribution for a random variable x is obtained through (x - loc) / scale. Discrete distribution have most of the same basic methods, however pdf is replaced the probability mass function pmf, no estimation methods, such as ﬁt, are available, and scale is not a valid keyword parameter. The location parameter, keyword loc can be used to shift the distribution. The basic methods, pdf, cdf, sf, ppf, and isf are vectorized with np.vectorize, and the usual numpy broadcasting is applied. For example, we can calculate the critical values for the upper tail of the t distribution for different probabilites and degrees of freedom.

>>> stats.t.isf([0.1, 0.05, 0.01], [[10], [11]]) array([[ 1.37218364, 1.81246112, 2.76376946], [ 1.36343032, 1.79588482, 2.71807918]])

Here, the ﬁrst row are the critical values for 10 degrees of freedom and the second row is for 11 d.o.f., i.e. this is the same as

>>> stats.t.isf([0.1, 0.05, 0.01], 10) array([ 1.37218364, 1.81246112, 2.76376946]) >>> stats.t.isf([0.1, 0.05, 0.01], 11) array([ 1.36343032, 1.79588482, 2.71807918])

If both, probabilities and degrees of freedom have the same array shape, then element wise matching is used. As an example, we can obtain the 10% tail for 10 d.o.f., the 5% tail for 11 d.o.f. and the 1% tail for 12 d.o.f. by

>>> stats.t.isf([0.1, 0.05, 0.01], [10, 11, 12]) array([ 1.37218364, 1.79588482, 2.68099799])

Performance and Remaining Issues The performance of the individual methods, in terms of speed, varies widely by distribution and method. The results of a method are obtained in one of two ways, either by explicit calculation or by a generic algorithm that is independent of the speciﬁc distribution. Explicit calculation, requires that the method is directly speciﬁed for the given distribution, either through analytic formulas or through special functions in scipy.special or numpy.random for rvs. These are usually relatively fast calculations. The generic methods are used if the distribution does not specify any explicit calculation. To deﬁne a distribution, only one of pdf or cdf is necessary, all other methods can be derived using numeric integration and root ﬁnding. These indirect methods can be very slow. As an example, rgh = stats.gausshyper.rvs(0.5, 2, 2, 2, size=100) creates random variables in a very indirect way and takes about 19 seconds for 100 random variables on my computer, while one million random variables from the standard normal or from the t distribution take just above one second. The distributions in scipy.stats have recently been corrected and improved and gained a considerable test suite, however a few issues remain: • skew and kurtosis, 3rd and 4th moments and entropy are not thoroughly tested and some coarse testing indicates that there are still some incorrect results left. • the distributions have been tested over some range of parameters, however in some corner ranges, a few incorrect results may remain. 1.10. Statistics 63

SciPy Reference Guide, Release 0.10.0.dev6665

• the maximum likelihood estimation in ﬁt does not work with default starting parameters for all distributions and the user needs to supply good starting parameters. Also, for some distribution using a maximum likelihood estimator might inherently not be the best choice. The next example shows how to build our own discrete distribution, and more examples for the usage of the distributions are shown below together with the statistical tests. Example: discrete distribution rv_discrete In the following we use stats.rv_discrete to generate a discrete distribution that has the probabilites of the truncated normal for the intervalls centered around the integers.

>>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> ... npoints = 20 # number of integer support points of the distribution minus 1 npointsh = npoints / 2 npointsf = float(npoints) nbound = 4 # bounds for the truncated normal normbound = (1+1/npointsf) * nbound # actual bounds of truncated normal grid = np.arange(-npointsh, npointsh+2, 1) # integer grid gridlimitsnorm = (grid-0.5) / npointsh * nbound # bin limits for the truncnorm gridlimits = grid - 0.5 grid = grid[:-1] probs = np.diff(stats.truncnorm.cdf(gridlimitsnorm, -normbound, normbound)) gridint = grid normdiscrete = stats.rv_discrete(values = (gridint, np.round(probs, decimals=7)), name=’normdiscrete’)

From the docstring of rv_discrete: “You can construct an aribtrary discrete rv where P{X=xk} = pk by passing to the rv_discrete initialization method (through the values= keyword) a tuple of sequences (xk, pk) which describes only those values of X (xk) that occur with nonzero probability (pk).” There are some requirements for this distribution to work. The keyword name is required. The support points of the distribution xk have to be integers. Also, I needed to limit the number of decimals. If the last two requirements are not satisﬁed an exception may be raised or the resulting numbers may be incorrect. After deﬁning the distribution, we obtain access to all methods of discrete distributions.

>>> print ’mean = %6.4f, variance = %6.4f, skew = %6.4f, kurtosis = %6.4f’% \ ... normdiscrete.stats(moments = ’mvsk’) mean = -0.0000, variance = 6.3302, skew = 0.0000, kurtosis = -0.0076 >>> nd_std = np.sqrt(normdiscrete.stats(moments = ’v’))

**Generate a random sample and compare observed frequencies with probabilities
**

>>> n_sample = 500 >>> np.random.seed(87655678) # fix the seed for replicability >>> rvs = normdiscrete.rvs(size=n_sample) >>> rvsnd = rvs >>> f, l = np.histogram(rvs, bins=gridlimits) >>> sfreq = np.vstack([gridint, f, probs*n_sample]).T >>> print sfreq [[ -1.00000000e+01 0.00000000e+00 2.95019349e-02] [ -9.00000000e+00 0.00000000e+00 1.32294142e-01] [ -8.00000000e+00 0.00000000e+00 5.06497902e-01] [ -7.00000000e+00 2.00000000e+00 1.65568919e+00] [ -6.00000000e+00 1.00000000e+00 4.62125309e+00] [ -5.00000000e+00 9.00000000e+00 1.10137298e+01] [ -4.00000000e+00 2.60000000e+01 2.24137683e+01]

64

Chapter 1. SciPy Tutorial

SciPy Reference Guide, Release 0.10.0.dev6665

[ -3.00000000e+00 [ -2.00000000e+00 [ -1.00000000e+00 [ 0.00000000e+00 [ 1.00000000e+00 [ 2.00000000e+00 [ 3.00000000e+00 [ 4.00000000e+00 [ 5.00000000e+00 [ 6.00000000e+00 [ 7.00000000e+00 [ 8.00000000e+00 [ 9.00000000e+00 [ 1.00000000e+01

3.70000000e+01 5.10000000e+01 7.10000000e+01 7.40000000e+01 8.90000000e+01 5.50000000e+01 5.00000000e+01 1.70000000e+01 1.10000000e+01 4.00000000e+00 3.00000000e+00 0.00000000e+00 0.00000000e+00 0.00000000e+00

3.89503370e+01] 5.78004747e+01] 7.32455414e+01] 7.92618251e+01] 7.32455414e+01] 5.78004747e+01] 3.89503370e+01] 2.24137683e+01] 1.10137298e+01] 4.62125309e+00] 1.65568919e+00] 5.06497902e-01] 1.32294142e-01] 2.95019349e-02]]

Next, we can test, whether our sample was generated by our normdiscrete distribution. This also veriﬁes, whether the random numbers are generated correctly The chisquare test requires that there are a minimum number of observations in each bin. We combine the tail bins into larger bins so that they contain enough observations.

>>> f2 = np.hstack([f[:5].sum(), f[5:-5], f[-5:].sum()]) >>> p2 = np.hstack([probs[:5].sum(), probs[5:-5], probs[-5:].sum()]) >>> ch2, pval = stats.chisquare(f2, p2*n_sample) >>> print ’chisquare for normdiscrete: chi2 = %6.3f pvalue = %6.4f’ % (ch2, pval) chisquare for normdiscrete: chi2 = 12.466 pvalue = 0.4090

The pvalue in this case is high, so we can be quite conﬁdent that our random sample was actually generated by the distribution.

**1.10.3 Analysing One Sample
**

First, we create some random variables. We set a seed so that in each run we get identical results to look at. As an example we take a sample from the Student t distribution:

>>> np.random.seed(282629734) >>> x = stats.t.rvs(10, size=1000)

Here, we set the required shape parameter of the t distribution, which in statistics corresponds to the degrees of freedom, to 10. Using size=100 means that our sample consists of 1000 independently drawn (pseudo) random numbers. Since we did not specify the keyword arguments loc and scale, those are set to their default values zero and one. Descriptive Statistics x is a numpy array, and we have direct access to all array methods, e.g.

>>> print x.max(), x.min() # equivalent to np.max(x), np.min(x) 5.26327732981 -3.78975572422 >>> print x.mean(), x.var() # equivalent to np.mean(x), np.var(x) 0.0140610663985 1.28899386208

**How do the some sample properties compare to their theoretical counterparts?
**

>>> m, v, s, k = stats.t.stats(10, moments=’mvsk’) >>> n, (smin, smax), sm, sv, ss, sk = stats.describe(x)

1.10. Statistics

65

SciPy Reference Guide, Release 0.10.0.dev6665

>>> print ’distribution:’, distribution: >>> sstr = ’mean = %6.4f, variance = %6.4f, skew = %6.4f, kurtosis = %6.4f’ >>> print sstr %(m, v, s ,k) mean = 0.0000, variance = 1.2500, skew = 0.0000, kurtosis = 1.0000 >>> print ’sample: ’, sample: >>> print sstr %(sm, sv, ss, sk) mean = 0.0141, variance = 1.2903, skew = 0.2165, kurtosis = 1.0556

Note: stats.describe uses the unbiased estimator for the variance, while np.var is the biased estimator. For our sample the sample statistics differ a by a small amount from their theoretical counterparts. T-test and KS-test We can use the t-test to test whether the mean of our sample differs in a statistcally signiﬁcant way from the theoretical expectation.

>>> print ’t-statistic = %6.3f pvalue = %6.4f’ % t-statistic = 0.391 pvalue = 0.6955 stats.ttest_1samp(x, m)

The pvalue is 0.7, this means that with an alpha error of, for example, 10%, we cannot reject the hypothesis that the sample mean is equal to zero, the expectation of the standard t-distribution. As an exercise, we can calculate our ttest also directly without using the provided function, which should give us the same answer, and so it does:

>>> tt = (sm-m)/np.sqrt(sv/float(n)) # t-statistic for mean >>> pval = stats.t.sf(np.abs(tt), n-1)*2 # two-sided pvalue = Prob(abs(t)>tt) >>> print ’t-statistic = %6.3f pvalue = %6.4f’ % (tt, pval) t-statistic = 0.391 pvalue = 0.6955

The Kolmogorov-Smirnov test can be used to test the hypothesis that the sample comes from the standard t-distribution

>>> print ’KS-statistic D = %6.3f pvalue = %6.4f’ % stats.kstest(x, ’t’, (10,)) KS-statistic D = 0.016 pvalue = 0.9606

Again the p-value is high enough that we cannot reject the hypothesis that the random sample really is distributed according to the t-distribution. In real applications, we don’t know what the underlying distribution is. If we perform the Kolmogorov-Smirnov test of our sample against the standard normal distribution, then we also cannot reject the hypothesis that our sample was generated by the normal distribution given that in this example the p-value is almost 40%.

>>> print ’KS-statistic D = %6.3f pvalue = %6.4f’ % stats.kstest(x,’norm’) KS-statistic D = 0.028 pvalue = 0.3949

However, the standard normal distribution has a variance of 1, while our sample has a variance of 1.29. If we standardize our sample and test it against the normal distribution, then the p-value is again large enough that we cannot reject the hypothesis that the sample came form the normal distribution.

>>> d, pval = stats.kstest((x-x.mean())/x.std(), ’norm’) >>> print ’KS-statistic D = %6.3f pvalue = %6.4f’ % (d, pval) KS-statistic D = 0.032 pvalue = 0.2402

Note: The Kolmogorov-Smirnov test assumes that we test against a distribution with given parameters, since in the last case we estimated mean and variance, this assumption is violated, and the distribution of the test statistic on which the p-value is based, is not correct.

66

Chapter 1. SciPy Tutorial

SciPy Reference Guide, Release 0.10.0.dev6665

Tails of the distribution Finally, we can check the upper tail of the distribution. We can use the percent point function ppf, which is the inverse of the cdf function, to obtain the critical values, or, more directly, we can use the inverse of the survival function

>>> crit01, crit05, crit10 = stats.t.ppf([1-0.01, 1-0.05, 1-0.10], 10) >>> print ’critical values from ppf at 1%%, 5%% and 10%% %8.4f %8.4f %8.4f’% (crit01, crit05, crit10) critical values from ppf at 1%, 5% and 10% 2.7638 1.8125 1.3722 >>> print ’critical values from isf at 1%%, 5%% and 10%% %8.4f %8.4f %8.4f’% tuple(stats.t.isf([0.01, critical values from isf at 1%, 5% and 10% 2.7638 1.8125 1.3722 >>> freq01 = np.sum(x>crit01) / float(n) * >>> freq05 = np.sum(x>crit05) / float(n) * >>> freq10 = np.sum(x>crit10) / float(n) * >>> print ’sample %%-frequency at 1%%, 5%% sample %-frequency at 1%, 5% and 10% tail

100 100 100 and 10%% tail %8.4f %8.4f %8.4f’% (freq01, freq05, freq10) 1.4000 5.8000 10.5000

In all three cases, our sample has more weight in the top tail than the underlying distribution. We can brieﬂy check a larger sample to see if we get a closer match. In this case the empirical frequency is quite close to the theoretical probability, but if we repeat this several times the ﬂuctuations are still pretty large.

>>> freq05l = np.sum(stats.t.rvs(10, size=10000) > crit05) / 10000.0 * 100 >>> print ’larger sample %%-frequency at 5%% tail %8.4f’% freq05l larger sample %-frequency at 5% tail 4.8000

We can also compare it with the tail of the normal distribution, which has less weight in the tails:

>>> print ’tail prob. of normal at 1%%, 5%% and 10%% %8.4f %8.4f %8.4f’% \ ... tuple(stats.norm.sf([crit01, crit05, crit10])*100) tail prob. of normal at 1%, 5% and 10% 0.2857 3.4957 8.5003

The chisquare test can be used to test, whether for a ﬁnite number of bins, the observed frequencies differ signiﬁcantly from the probabilites of the hypothesized distribution.

>>> quantiles = [0.0, 0.01, 0.05, 0.1, 1-0.10, 1-0.05, 1-0.01, 1.0] >>> crit = stats.t.ppf(quantiles, 10) >>> print crit [ -Inf -2.76376946 -1.81246112 -1.37218364 1.37218364 1.81246112 2.76376946 Inf] >>> n_sample = x.size >>> freqcount = np.histogram(x, bins=crit)[0] >>> tprob = np.diff(quantiles) >>> nprob = np.diff(stats.norm.cdf(crit)) >>> tch, tpval = stats.chisquare(freqcount, tprob*n_sample) >>> nch, npval = stats.chisquare(freqcount, nprob*n_sample) >>> print ’chisquare for t: chi2 = %6.3f pvalue = %6.4f’ % (tch, tpval) chisquare for t: chi2 = 2.300 pvalue = 0.8901 >>> print ’chisquare for normal: chi2 = %6.3f pvalue = %6.4f’ % (nch, npval) chisquare for normal: chi2 = 64.605 pvalue = 0.0000

We see that the standard normal distribution is clearly rejected while the standard t-distribution cannot be rejected. Since the variance of our sample differs from both standard distribution, we can again redo the test taking the estimate for scale and location into account. The ﬁt method of the distributions can be used to estimate the parameters of the distribution, and the test is repeated using probabilites of the estimated distribution.

>>> tdof, tloc, tscale = stats.t.fit(x) >>> nloc, nscale = stats.norm.fit(x) >>> tprob = np.diff(stats.t.cdf(crit, tdof, loc=tloc, scale=tscale))

1.10. Statistics

67

chisquare(freqcount.0858 Taking account of the estimated parameters.skewtest(x) normal skewtest teststat = 2. tpval = stats. tpval) chisquare for t: chi2 = 1.4f’ % stats.3f pvalue = %6.379 pvalue = 0. there are several additional functions available to test whether a sample could have been drawn from a normal distribution First we can test if skew and kurtosis of our sample differ signiﬁcantly from those of a normal distribution: >>> print ’normal skewtest teststat = %6.std()) normaltest teststat = 30.0000 These two tests are combined in the normality test >>> print ’normaltest teststat = %6.0000 Because normality is rejected so strongly.4 Comparing two samples In the following.4f’ % stats.normaltest(x) normaltest teststat = 30. In the ﬁrst case this is because the test is not powerful enough to distinguish a t and a normally distributed random variable in a small sample. Special tests for normal distributions Since the normal distribution is the most common distribution in statistics.3f pvalue = %6.084 pvalue = 0.normaltest(stats. npval) chisquare for normal: chi2 = 11.3f pvalue = %6.0054 >>> print ’normal kurtosistest teststat = %6.3f pvalue = %6.norm.4f’ % stats.SciPy Reference Guide.0000 In all three tests the p-values are very low and we can reject the hypothesis that the our sample has skew and kurtosis of the normal distribution. and we want to test whether these samples have the same statistical properties.3f pvalue = %6. size=100)) normaltest teststat = 4.7361 When testing for normality of a small sample of t-distributed observations and a large sample of normal distributed observation. Since skew and kurtosis of our sample are based on central moments.9542 >>> print ’chisquare for normal: chi2 = %6.3f pvalue = %6.4f’ % stats.10.0.rvs(size=1000)) normaltest teststat = 0. we are given two samples.577 pvalue = 0.diff(stats.4f’ % \ .3f pvalue = %6. with a p-value of 0. tprob*n_sample) >>> nch.kurtosistest(x) normal kurtosistest teststat = 4. stats. but again.norm. we can check whether the normaltest gives reasonable results for other cases: >>> print ’normaltest teststat = %6.698 pvalue = 0. SciPy Tutorial .4f’ % stats. loc=nloc.rvs(10.normaltest(stats.3f pvalue = %6.dev6665 >>> nprob = np.mean())/x.normaltest((x-x.t. we can still reject the hypothesis that our sample came from a normal distribution (at the 5% level).757 pvalue = 0. scale=nscale)) >>> tch.cdf(crit.0955 >>> print ’normaltest teststat = %6. npval = stats.4f’ % (tch.chisquare(freqcount. 1.10.95. Release 0. we get exactly the same results if we test the standardized sample: >>> print ’normaltest teststat = %6...785 pvalue = 0.4f’ % (nch.379 pvalue = 0. which can come either from the same or from different distribution. nprob*n_sample) >>> print ’chisquare for t: chi2 = %6. then in neither case can we reject the null hypothesis that the sample comes from a normal distribution. 68 Chapter 1.613 pvalue = 0. we cannot reject the t distribution.

rvs3) (-4. Multi-dimensional image processing (ndimage) 69 . This is done by simply assigning the desired numpy type object to the output argument. the output argument is used. For example: 1. 6.11. In this case the result is not returned. 0. however. Notably. Usually.99541195173064878) In the second example.025999999999999995. rvs2) (-0. the type of the result is equal to the type of the speciﬁed output argument. means. 1.norm. size=500) >>> stats.11 Multi-dimensional image processing (ndimage) 1. If no output argument is given. 0. size=500) >>> stats.1 Introduction Image processing and analysis are generally seen as operations on two-dimensional arrays of values.ks_2samp(rvs1. with different location. i.54890361750888583. B-spline interpolation.ttest_ind(rvs1. but it is in most cases equal to the type of the input. Good examples of these are medical imaging and biological imaging.rvs(loc=5.norm.2 Properties shared by all functions All functions share some common properties.10. we can reject the null hypothesis since the pvalue is below 1% >>> stats. scale=10. all functions allow the speciﬁcation of an output array with the output argument.11399999999999999. rvs3) (0. and object measurements.SciPy Reference Guide.rvs(loc=5. since an existing array is used to store the result. Release 0.ks_2samp(rvs1. size=500) >>> rvs2 = stats. rvs2) (0.ttest_ind(rvs1. The packages currently includes functions for linear and non-linear ﬁltering. The scipy. it is still possible to specify what the result of the output should be.e. numpy is suited very well for this type of applications due its inherent multidimensional nature. The type of arrays returned is dependent on the type of operation.rvs(loc=8. binary morphology. scale=10.norm.507128186505895e-006) Kolmogorov-Smirnov test for two samples ks_2samp For the example where both samples are drawn from the same distribution. using the output argument is more efﬁcient. 0. With this argument you can specify an array that will be changed in-place with the result with the operation.11.0027132103661283141) 1. If.11.ndimage packages provides a number of general image processing and analysis functions that are designed to operate with arrays of arbitrary dimensionality. scale=10.5334142901750321.0. we cannot reject the null hypothesis since the pvalue is high >>> stats.5831943748663857) Test with sample with different means: >>> rvs3 = stats. There are however a number of ﬁelds where images of higher dimensionality must be analyzed.dev6665 Comparing means Test with sample with identical means: >>> rvs1 = stats.

5 6. 1]. 30. Take for example the correlation of a one-dimensional array with a ﬁlter of length 3 consisting of ones: >>> a = [0. [-1. but its use will generate an deprecation warning. which is often rectangular in shape but may also have an arbitrary footprint. the origin of a one-dimensional kernel of length three is at the second element.0]]) print footprint 1 0] 1 1] 1 0]] Usually the origin of the kernel is at the center calculated by dividing the dimensions of the kernel shape by two. 0. either by specifying an output array of the desired type. using the origin parameter instead of a larger kernel is more efﬁcient.5].dev6665 >>> print correlate(arange(10).5 27. 0. [1. 2. some functions accepted the output_type argument to achieve the same effect. For example: >>> a = [0. or by specifying the type of the output that is to be returned.0]. but it may be useful especially for ﬁlters that have an even size. 1.5]) [ 0 2 6 9 13 16 20 23 27 30] >>> print correlate(arange(10). 1. 2. 0] >>> print correlate1d(a.SciPy Reference Guide. 1]) [0 0 1 1 1 0 0] Sometimes it is convenient to choose a different origin for the kernel.1. For example a cross shaped kernel can be deﬁned as follows: >>> >>> [[0 [1 [0 footprint = array([[0.0. 0. by passing a mask through the footprint parameter. origin = -1) [0 1 1 1 0 0 0] The effect is a shift of the result towards the left. 1. [-1. Many of the functions described below allow you to deﬁne the footprint of the kernel. is by using the output argument. 0] >>> correlate1d(a.ndimage. origin = -1) ## forward difference [ 0 1 0 0 -1 0 0] We could also have calculated the forward difference as follows: >>> print correlate1d(a. A good example is the calculation of backward and forward differences: >>> a = [0.1. We refer to this neighborhood of elements as the ﬁlter kernel. 1.11. This feature will not be needed very often. 0. in which case the origin is assumed to be equal along all axes.5 13. [1. [1. -1. 16. For multi-dimensional kernels origin can be a number. 1]) [ 0 1 0 0 -1 0 0] however. 1]) ## backward difference [ 0 0 1 0 0 -1 0] >>> print correlate1d(a. 1]. Release 0. 2. This argument is still supported. 9. 0] >>> print correlate1d(a. 23.10.5] Note: In previous versions of scipy. 0. 0. 70 Chapter 1. 1. In a future version all instances of this argument will be removed. 1. For this reason most functions support the origin parameter which gives the origin of the ﬁlter relative to its center.[1.1]. 0. 1.3 Filter functions The functions described in this section all perform some type of spatial ﬁltering of the the input array: the elements in the output are some function of the values in the neighborhood of the corresponding input element. or a sequence giving the origin along each axis. For instance. [1.5 20.1. 0. SciPy Tutorial . output = Float64) [ 0. 0.[0. The preferred way to specify an output type. 0. 1. [0.

Correlation and convolution The correlate1d function calculates a one-dimensional correlation along the given axis. The lines of the array along the given axis are convoluted with the given weights. As a result. the standard deviation of the ﬁlter is equal along all directions. Higher order derivatives are not implemented. The lines of the array along the given axis are correlated with the given weights. For large arrays and large ﬁlter kernels.11. Setting order = 0 corresponds to convolution with a Gaussian kernel. Multi-dimensional image processing (ndimage) 71 .SciPy Reference Guide.0. Note: A convolution is essentially a correlation after mirroring the kernel. Following boundary conditions are currently supported: “nearest” “wrap” “reﬂect” “constant” Use the value at the boundary Periodically replicate the array Reﬂect the array at the boundary Use a constant value. The gaussian_filter function implements a multi-dimensional Gaussian ﬁlter. or 3 corresponds to convolution with the ﬁrst. In the functions described below. If sigma is not a sequence but a single number. Note: A convolution is essentially a correlation after mirroring the kernel. second or third derivatives of a Gaussian. The convolve1d function calculates a one-dimensional convolution along the given axis. the origin parameter behaves differently than in the case of a correlation: the results is shifted in the opposite direction. and the functions described below therefore use a different approach that does not require allocating large temporary buffers. The function convolve implements multi-dimensional convolution of the input array with a given kernel. this would be very memory consuming. Note: The multi-dimensional ﬁlter is implemented as a sequence of one-dimensional Gaussian ﬁlters. the boundary conditions can be selected using the mode parameter which must be a string with the name of the boundary condition. Higher order derivatives are not implemented. the origin parameter behaves differently than in the case of a correlation: the result is shifted in the opposite directions.10. to specify the same order for all axes. default is 0. second or third derivatives of a Gaussian. As a result. The weights parameter must be a one-dimensional sequences of numbers. An order of 0 corresponds to convolution with a Gaussian kernel. This is done by assuming that the arrays are extended beyond their boundaries according certain boundary conditions. The intermediate arrays are stored in the same data type as the output. The function correlate implements multi-dimensional correlation of the input array with a given kernel. An order of 1. the borders of the array need to be dealt with appropriately by providing the values outside the borders. The standarddeviations of the Gaussian ﬁlter along each axis are passed through the parameter sigma as a sequence or numbers. The order of the ﬁlter can be speciﬁed separately for each axis. Therefore. or 3 corresponds to convolution with the ﬁrst. Note: The easiest way to implement such boundary conditions would be to copy the data to a larger array and extend the data at the borders according to the boundary conditions.dev6665 Since the output elements are a function of elements in the neighborhood of the input elements. 2. The standarddeviation of the Gaussian ﬁlter is passed through the parameter sigma. The weights parameter must be a one-dimensional sequences of numbers. or a sequence of numbers to specify a different order for each axis. Release 0. The order parameter must be a number. for output types with a 1. An order of 1.0 [1 2 3]->[1 1 2 3 3] [1 2 3]->[3 1 2 3 1] [1 2 3]->[1 1 2 3 3] [1 2 3]->[0 1 2 3 0] The “constant” mode is special since it needs an additional parameter to specify the constant value that should be used. 2. Smoothing ﬁlters The gaussian_filter1d function implements a one-dimensional Gaussian ﬁlter.

i. The footprint. Filters based on order statistics The minimum_filter1d function calculates a one-dimensional minimum ﬁlter of given size along the given axis. The footprint. if provided. The size parameter. Either the sizes of a rectangular kernel or the footprint of the kernel must be provided.. if provided. The size parameter. Derivatives Derivative ﬁlters can be constructed in several ways. must be an array that deﬁnes the shape of the kernel by its non-zero elements. The uniform_filter implements a multi-dimensional uniform ﬁlter. if provided. percentile = -20 equals percentile = 80. must be an array that deﬁnes the shape of the kernel by its non-zero elements. the sizes along all axis are assumed to be equal. The size parameter.SciPy Reference Guide. The median_filter function calculates a multi-dimensional median ﬁlter. must be a sequence of sizes or a single number in which case the size of the ﬁlter is assumed to be equal along each axis. but a single number. The footprint if provided. Note: The multi-dimensional ﬁlter is implemented as a sequence of one-dimensional uniform ﬁlters. Either the sizes of a rectangular kernel or the footprint of the kernel must be provided. The intermediate arrays are stored in the same data type as the output. rank = -1 indicates the largest element. for output types with a lower precision. The function gaussian_filter1d described in Smoothing ﬁlters can be used to calculate derivatives along a given axis using the order parameter.e. If size is not a sequence. The size parameter. must be an array that deﬁnes the shape of the kernel by its non-zero elements. Other derivative ﬁlters are the 72 Chapter 1. if provided. The percentile may be less then zero. The uniform_filter1d function calculates a one-dimensional uniform ﬁlter of the given size along the given axis. The size parameter. The footprint.0. The rank_filter function calculates a multi-dimensional rank ﬁlter. The rank may be less then zero. must be an array that deﬁnes the shape of the kernel by its non-zero elements. This can be prevented by specifying a more precise output type. if provided.. The sizes of the uniform ﬁlter are given for each axis as a sequence of integers by the size parameter. must be a sequence of sizes or a single number in which case the size of the ﬁlter is assumed to be equal along each axis. This can be prevented by specifying a more precise output type. if provided. i.dev6665 lower precision. must be an array that deﬁnes the shape of the kernel by its non-zero elements. Release 0. The footprint. the results may be imprecise because intermediate results may be stored with insufﬁcient precision. The maximum_filter1d function calculates a one-dimensional maximum ﬁlter of given size along the given axis. if provided. Either the sizes of a rectangular kernel or the footprint of the kernel must be provided. must be a sequence of sizes or a single number in which case the size of the ﬁlter is assumed to be equal along each axis. if provided. The maximum_filter function calculates a multi-dimensional maximum ﬁlter. The minimum_filter function calculates a multi-dimensional minimum ﬁlter.10. SciPy Tutorial . Therefore.e. must be a sequence of sizes or a single number in which case the size of the ﬁlter is assumed to be equal along each axis. Either the sizes of a rectangular kernel or the footprint of the kernel must be provided. if provided. the results may be imprecise because intermediate results may be stored with insufﬁcient precision. must be a sequence of sizes or a single number in which case the size of the ﬁlter is assumed to be equal along each axis. Either the sizes of a rectangular kernel or the footprint of the kernel must be provided. The percentile_filter function calculates a multi-dimensional percentile ﬁlter.

d2) [[ 0 0 0 0 0] [ 0 0 1 0 0] [ 0 1 -4 1 0] [ 0 0 1 0 0] [ 0 0 0 0 0]] To demonstrate the use of the extra_arguments argument we could do: >>> def d2(input. cval have the usual meaning.) . 2] = 1 >>> print generic_laplace(a. axis. [1. different Laplace ﬁlters can be constructed using different second derivative functions.. Release 0.)) [[ 0 0 0 0 0] [ 0 0 1 0 0] [ 0 1 -4 1 0] [ 0 0 1 0 0] [ 0 0 0 0 0]] or: >>> print generic_laplace(a. -2. cval. >>> a = zeros((5.. The sobel function calculates a derivative along the given axis. return correlate1d(input. output. d2.11. output.0. d2. The Laplace ﬁlter is calculated by the sum of the second derivatives along all axes. weights): . return correlate1d(input. Therefore we provide a general function that takes a function argument to calculate the second derivative along a given direction and to construct the Laplace ﬁlter: The function generic_laplace calculates a laplace ﬁlter using the function passed through derivative2 to calculate second derivatives. The extra_arguments and extra_keywords arguments can be used to pass a tuple of extra arguments and a dictionary of named arguments that are passed to derivative2 at each call. otherwise it should return the result.. -2. 1]. extra_keywords = {’weights’: [1. mode. 2] = 1 >>> print generic_laplace(a. cval. Multi-dimensional image processing (ndimage) 73 . 1]. **extra_keywords) It should calculate the second derivative along the dimension axis.. 0) . 0. cval. cval): . 1]}) [[ 0 0 0 0 0] [ 0 0 1 0 0] [ 0 1 -4 1 0] [ 0 0 1 0 0] [ 0 0 0 0 0]] The following two functions are implemented using generic_laplace by providing appropriate functions for the second derivative function: 1. For example: >>> def d2(input. mode.. output. output. The function derivative2 should have the following signature: derivative2(input. axis. mode. 5)) >>> a[2.10. extra_arguments = ([1. weights. mode. 5)) >>> a[2. -2. If output is not None it should use that for the output and return None. cval. axis. *extra_arguments. mode.SciPy Reference Guide.. output.. axis. Thus.dev6665 Prewitt and Sobel ﬁlters: The prewitt function calculates a derivative along the given axis.. mode. axis. >>> a = zeros((5.

along with such details as the implementation of the boundary conditions.dev6665 The function laplace calculates the Laplace using discrete differentiation for the second derivative (i. Similar to the generic Laplace function there is a generic_gradient_magnitude function that calculated the gradient magnitude of an array: The function generic_gradient_magnitude calculates a gradient magnitude using the function passed through derivative to calculate ﬁrst derivatives. cval have the usual meaning. **extra_keywords) It should calculate the derivative along the dimension axis. Release 0. 2] = 1 print generic_gradient_magnitude(a. The generic_filter1d function iterates over the lines of an array and calls function at each line. mode. The standard-deviations of the Gaussian ﬁlter along each axis are passed through the parameter sigma as a sequence or numbers.10. -2. The extra_arguments and extra_keywords arguments can be used to pass a tuple of extra arguments and a dictionary of named arguments that are passed to derivative at each call. The generic_filter1d function implements a generic one-dimensional ﬁlter function. The 74 Chapter 1. For example. The sobel and prewitt functions ﬁt the required signature and can therefore directly be used with generic_gradient_magnitude. the standard deviation of the ﬁlter is equal along all directions. The function derivative should have the following signature: derivative(input.e. Only a callable object implementing a callback function that does the actual ﬁltering work must be provided. 1]). the sobel function ﬁts the required signature: >>> >>> >>> [[0 [0 [0 [0 [0 a = zeros((5. If output is not None it should use that for the output and return None. The arguments that are passed to function are one-dimensional arrays of the tFloat64 type. The following function implements the gradient magnitude using Gaussian derivatives: The function gaussian_gradient_magnitude calculates the gradient magnitude using gaussian_filter to calculate the ﬁrst derivatives. mode. output.0. If sigma is not a sequence but a single number. If sigma is not a sequence but a single number. The gradient magnitude is deﬁned as the square root of the sum of the squares of the gradients in all directions. The iteration over the input and output arrays is handled by these generic functions. cval. The standard-deviations of the Gaussian ﬁlter along each axis are passed through the parameter sigma as a sequence or numbers.SciPy Reference Guide. sobel) 0 0 0 0] 1 2 1 0] 2 0 2 0] 1 2 1 0] 0 0 0 0]] See the documentation of generic_laplace for examples of using the extra_arguments and extra_keywords arguments. axis. 5)) a[2. The callback function can also be written in C and passed using a PyCObject (see Extending ndimage in C for more information). generic functions can be used that accept a callable object that implements the ﬁltering operation. *extra_arguments. the standard deviation of the ﬁlter is equal along all directions. SciPy Tutorial . convolution with [1. where the actual ﬁltering operation must be supplied as a python function (or other callable object). The function gaussian_laplace calculates the Laplace using gaussian_filter to calculate the second derivatives. otherwise it should return the result. Generic ﬁlter functions To implement ﬁlter functions.

SciPy Reference Guide. >>> print generic_filter1d(a. ’b’:3}) [[ 3 8 14 17] [27 32 38 41] [51 56 62 65]] The generic_filter function implements a generic ﬁlter function. where the actual ﬁltering operation must be supplied as a python function (or other callable object). The second array should be modiﬁed in-place to provide the output values of the line. It is extended at the beginning end the end. a. extra_arguments = (2. >>> print generic_filter1d(a.. The generic_filter function iterates over the array and calls function at each element. 3. 3)) [[ 3 8 14 17] [27 32 38 41] [51 56 62 65]] or >>> print generic_filter1d(a. each input line was extended by one value at the beginning and at the end. fnc. Optionally extra arguments can be deﬁned and passed to the ﬁlter function. that contains the values around the current element that are within the footprint of the ﬁlter.. shape = (3. For example... extra_keywords = {’a’:2. The extra_arguments and extra_keywords arguments can be used to pass a tuple of extra arguments and/or a dictionary of named arguments that are passed to derivative at each call. [[1.4)) >>> print correlate1d(a.. For example consider a correlation along one dimension: >>> a = arange(12. 3) [[ 3 8 14 17] [27 32 38 41] [51 56 62 65]] Here the origin of the kernel was (by default) assumed to be in the middle of the ﬁlter of length 3. [1. fnc. fnc. according to the ﬁlter_size and origin arguments... 2. we can pass the parameters of our ﬁlter as an argument: >>> def fnc(iline. 3]]) [[ 0 3 7 11] [12 15 19 23] [28 31 35 39]] The same operation can be implemented using generic_ﬁlter as follows: 1.dev6665 ﬁrst contains the values of the current line. For example consider a correlation: >>> a = arange(12.. [0. The argument of function is a onedimensional array of the tFloat64 type. 0].10. oline[. oline[.. b): ..11.0. Release 0.] = iline[:-2] + 2 * iline[1:-1] + 3 * iline[2:] . oline. oline): . 3. 3]) [[ 3 8 14 17] [27 32 38 41] [51 56 62 65]] The same operation can be implemented using generic_filter1d as follows: >>> def fnc(iline.] = iline[:-2] + a * iline[1:-1] + b * iline[2:] ..4)) >>> print correlate(a. shape = (3. Multi-dimensional image processing (ndimage) 75 . The function should return a single value that can be converted to a double precision number. Therefore.. before the function was called.

0].. if provided. must be an array that deﬁnes the shape of the kernel by its non-zero elements.. Release 0. fnc. axes = range(len(self. extra_keywords= {’weights’: [ [[ 0 3 7 11] [12 15 19 23] [28 31 35 39]] These functions iterate over the lines or elements starting at the last axis. print self.sum() . The extra_arguments and extra_keywords arguments can be used to pass a tuple of extra arguments and/or a dictionary of named arguments that are passed to derivative at each call. 0]. we can pass the parameters of our ﬁlter as an argument: >>> def fnc(buffer. SciPy Tutorial . either the sizes of a rectangular kernel or the footprint of the kernel must be provided... # store the shape: ... 1]].. 3]. shape = (3. footprint = [[1. i. weights): . shape): .... Here is an example of using a class that implements the ﬁlter and keeps track of the current coordinates while iterating.sum() . The size parameter.sum() . [0.. 1]]. return (buffer * weights). axes. fnc.)) [[ 0 3 7 11] [12 15 19 23] [28 31 35 39]] or >>> print generic_filter(a.SciPy Reference Guide. but additionally prints the current coordinates: >>> a = arange(12. # calculate the next coordinates: .4)) >>> >>> class fnc_class: .. must be a sequence of sizes or a single number in which case the size of the ﬁlter is assumed to be equal along each axis.coordinates = [0] * len(shape) ..shape = shape ..e. def __init__(self. self. def filter(self. For example.. When calling generic_filter. self.. return (buffer * array([1.. buffer): . >>> print generic_filter(a.0.shape)) . extra_arguments = ([1.10. The footprint.. if provided.. the last index changes the fastest. footprint = [[1.coordinates .. . [0..reverse() . result = (buffer * array([1. # initialize the coordinates: . fnc.. This order of iteration is guaranteed for the case that it is important to adapt the ﬁlter depending on spatial location. which was multiplied with the proper weights and the result summed.. 3])).... 0].dev6665 >>> def fnc(buffer): .. 1]]) [[ 0 3 7 11] [12 15 19 23] [28 31 35 39]] Here a kernel footprint was speciﬁed that contains only two elements.. Therefore the ﬁlter function receives a buffer of length equal to two. [0... footprint = [[1.. for jj in axes: 76 Chapter 1.. Optionally extra arguments can be deﬁned and passed to the ﬁlter function. >>> print generic_filter(a.. 3])). weights = asarray(weights) .. It performs the same ﬁlter operation as described above for generic_filter...

1]]) [0.... . axis = -1): # store the filter axis: self. else: .1: . >>> fnc = fnc_class(shape = (3.. break .shape = shape # initialize the coordinates: self.. . oline): oline[.1: self.reverse() for jj in axes: if self.shape[jj] . ..4)) >>> print generic_filter(a... 3] [[ 0 3 7 11] [12 15 19 23] [28 31 35 39]] For the generic_filter1d function the same approach works.coordinates[jj] = 0 fnc = fnc1d_class(shape = (3.. [0...4)) print generic_filter1d(a.... shape = (3. . 2] [2... [1.. fnc..filter. .coordinates[jj] < self. except that this function does not iterate over the axis that is being ﬁltered... 0] [0. . 3] [1. .. .coordinates = [0] * len(shape) def filter(self... . ... self. . if self.. return result .SciPy Reference Guide..4)) class fnc1d_class: def __init__(self.. ....filter.axis = axis # store the shape: self. .shape[jj] .] = iline[:-2] + 2 * iline[1:-1] + 3 * iline[2:] print self. The example for generic_filter1d then becomes this: >>> >>> >>> . a = arange(12.. fnc..11..coordinates # calculate the next coordinates: axes = range(len(self..... self.coordinates[jj] += 1 break else: self. . Multi-dimensional image processing (ndimage) 77 .. footprint = [[1.10.. 3) 0] 0] 1...... 0] [1....dev6665 . shape. .coordinates[jj] += 1 .. 1] [1. 1] [2.. 1] [0.axis] axes.... Release 0..coordinates[jj] < self. . >>> >>> [0.... ...shape)) # skip the filter axis: del axes[self.. . 2] [0. .. 3] [2. . .coordinates[jj] = 0 . iline. 0]. 0] [2..0. . 2] [1.

but they can be instructed not to do this by setting the preﬁlter keyword equal to False. 2. the input array of such a function should be compatible with an inverse Fourier transform function. vol. or a single value for all dimensions. The shift parameter is a sequences of shifts for each dimension. The following two functions implement the pre-ﬁltering: The spline_filter1d function calculates a one-dimensional spline ﬁlter along the given axis. Thus. The fourier_uniform function multiplies the input array with the multi-dimensional Fourier transform of a uniform ﬁlter with given sizes size. The size parameter is a sequences of values for each dimension. An output array can optionally be provided. 16. In the case of a real Fourier transform only half of the of the symmetric complex transform is stored. it is assumed that the input array was the result of a complex Fourier transform.fft module. Release 0. The intermediate arrays are stored in the same data type as the output.ﬁltering step. 0] [[ 3 8 14 17] [27 32 38 41] [51 56 62 65]] Fourier domain ﬁlters The functions described in this section perform ﬁltering operations in the Fourier domain. The fourier_ellipsoid function multiplies the input array with the multi-dimensional Fourier transform of a elliptically shaped ﬁlter with given sizes size. This is useful if more than one interpolation operation is done on the same array. if an output with a limited 78 Chapter 1. 22-38. If this parameter is less than zero. A good introduction to Bsplines can be found in: M. pp. The size parameter is a sequences of values for each dimension. Therefore.” IEEE Signal Processing Magazine. The sigma parameter is a sequences of values for each dimension. Additionally.11. “Splines: A Perfect Fit for Signal and Image Processing. In this case it is more efﬁcient to do the pre-ﬁltering only once and use a preﬁltered array as the input of the interpolation functions. Note: The multi-dimensional ﬁlter is implemented as a sequence of one-dimensional spline ﬁlters. The fourier_shift function multiplies the input array with the multi-dimensional Fourier transform of a shift operation for the given shift.SciPy Reference Guide. or a single value for all dimensions. such as the functions from the numpy. no.10.dev6665 [2. The parameter axis can be used to indicate along which axis the real transform was executed. This function is only implemented for dimensions 1. or a single value for all dimensions.0. The fourier_gaussian function multiplies the input array with the multi-dimensional Fourier transform of a Gaussian ﬁlter with given standard-deviations sigma. SciPy Tutorial . November 1999. The order of the spline must be larger then 1 and less than 6. 6. 1. Unser. We therefore have to deal with arrays that may be the result of a real or a complex Fourier transform. or a single value for all dimensions. Spline pre-ﬁlters Interpolation using splines of an order larger than 1 requires a pre.4 Interpolation functions This section describes various interpolation functions that are based on B-spline theory. and 3. The interpolation functions described in section Interpolation functions apply pre-ﬁltering by calling spline_filter. The functions described here provide a parameter n that in the case of a real transform must be equal to the length of the real transform axis before transformation. The spline_filter function calculates a multi-dimensional spline ﬁlter. it needs to be known what the length of the axis was that was transformed by the real fft.

mapping must be a callable object that accepts a tuple of length equal to the output array rank and returns the corresponding input coordinates as a tuple of length equal to the input array rank. The extra_arguments and extra_keywords arguments can be used to pass a tuple of extra arguments and/or a dictionary of named arguments that are passed to derivative at each call.5) .2625 9. 1. ] [ 0. The parameter coordinates is used to ﬁnd for each point in the output the corresponding coordinates in the input. 1.. 1.8125 6. shift_func) [[ 0..0.10. s1): . extra_keywords = {’s0’: 0. This can be prevented by specifying a output type of high precision.5}) [[ 0. 0.5. and therefore the possibility arises that input values outside the boundaries are needed. 4. 0. >>> print geometric_transform(a.5. 0. and a cval parameter that gives a constant value in case that the ‘constant’ mode is used.7375] [ 0. The function map_coordinates applies an arbitrary coordinate transformation using the given array of coordinates. we can pass the shifts in our example as arguments: >>> def shift_func(output_coordinates.s0.3625 2. For example. For example: >>> a = arange(12. 4.8125 6. shift_func.7375] [ 0. 8.5)) [[ 0. >>> print geometric_transform(a. Interpolation functions Following functions all employ spline interpolation to effect some type of geometric transformation of the input array. This problem is solved in the same way as described in Filter functions for the multi-dimensional ﬁlter functions. 0.3625 2.0.6375]] or >>> print geometric_transform(a. extra_arguments = (0.0.3625 2.s1) . 0..1875] [ 0. The output shape and output type can optionally be provided.6375]] Optionally extra arguments can be deﬁned and passed to the ﬁlter function. output_coordinates[1] . return (output_coordinates[0] . shift_func.1875] [ 0.. output_coordinates[1] .. This requires a mapping of the output coordinates to the input coordinates. ] [ 0. return (output_coordinates[0] . type = Float64) >>> def shift_func(output_coordinates): .6375]] Note: The mapping function can also be written in C and passed using a PyCObject. ’s1’: 0. The geometric_transform function applies an arbitrary geometric transform to the input.1875] [ 0. the results may be imprecise because intermediate results may be stored with insufﬁcient precision. shape=(4.3)..7375] [ 0.11. 8.SciPy Reference Guide.2625 9. 8. Therefore these functions all support a mode parameter that determines how the boundaries are handled. The shape of the output is derived from that of the coordinate array by dropping the ﬁrst axis..8125 6. See Extending ndimage in C for more information. If not given they are equal to the input shape and type. s0. Multi-dimensional image processing (ndimage) 79 . The given mapping function is called at each point in the output to ﬁnd the corresponding coordinates in the input. The values of coordinates along the ﬁrst axis are the coordinates in the input array at which 1. 4.5. Release 0.dev6665 precision is requested. ] [ 0..2625 9. 0. 0.

0.] [ 3.3).5. The given transformation matrix and offset are used to ﬁnd for each point in the output the corresponding coordinates in the input. 1) 1 0] 1 1] 1 0]] print generate_binary_structure(2. 4. 2): >>> a = arange(12.SciPy Reference Guide. The size of the structure that is returned is equal to three in each direction. The transformation matrix must be two-dimensional or can also be given as a one-dimensional sequence or array. type = numarray. The zoom function returns a rescaled version of the input.5 Morphology Binary morphology Binary morphology (need something to put here). The origin parameter controls the placement of the structuring element as described in Filter functions.5) and (1. using spline interpolation of the requested order. (See also the numarray coordinates function. 10. Here is an example that interpolates a 2D array at (0. The border_value parameter gives the value of 80 Chapter 1. then the size of the output array is adapted to contain the rotated input.integer coordinates. A more efﬁcient interpolation algorithm is then applied that exploits the separability of the problem. ] The affine_transform function applies an afﬁne transformation to the input array. 0. 2. The angle must be given in degrees. two dimensional 4-connected and 8-connected structures are generated as follows: >>> [[0 [1 [0 >>> [[1 [1 [1 print generate_binary_structure(2. 2]. If reshape is true. 1]]) [ 1.5. The value of each element is equal to one if the square of the Euclidean distance from the element to the center is less or equal to connectivity. The rank of the structure must be provided. The value of the input at the calculated coordinates is determined by spline interpolation of the requested order. the value of the input at these coordinates is determined by spline interpolation of the requested order. it is assumed that the matrix is diagonal. If not given they are equal to the input shape and type. 2) 1 1] 1 1] 1 1]] Most binary morphology functions can be expressed in terms of the basic operations erosion and dilation: The binary_erosion function implements binary erosion of arrays of arbitrary rank with the given structuring element. The rotate function returns the input array rotated in the plane deﬁned by the two axes given by the parameter axes. using spline interpolation of the requested order. [0.] [ 9. [[0. 8. SciPy Tutorial . The output shape and output type can optionally be provided. using spline interpolation of the requested order. If no structuring element is provided. Release 0. In the latter case.]] >>> print map_coordinates(a. The generate_binary_structure functions generates a binary structuring element for use in binary morphology operations.10.11. 7. The shift function returns a shifted version of the input.dev6665 the output value is found. 1.] [ 6. an element with connectivity equal to one is generated using generate_binary_structure.5. shape=(4.Float64) >>> print a [[ 0. 11.3625 7. For instance. 1. 5.) Since the coordinates may be non.

0.SciPy Reference Guide.0.0. 1. the dilation is repeated until the result does not change anymore. 0].10. The dilation is repeated iterations times.0]. 1.0.shape). For convenience the iterate_structure also returns the adapted origin if the origin parameter is not None: >>> print iterate_structure(struct. 1. 2. 1. 1. [1. 1. 0].0.1. only those elements with a true value at the corresponding mask element are modiﬁed at each iteration. [0. 0]. 0]. For instance: >>> >>> [[0 [1 [0 >>> [[0 [0 [1 [0 [0 struct = generate_binary_structure(2. [1. 1]. If a mask array is given. -1. by repeatedly dilating an empty array from the border using the data array as the mask: >>> >>> >>> [[1 [1 [0 [0 >>> [[1 [1 [0 [0 struct = array([[0. Release 0.0. If not.0. 1. 1]. 1.dev6665 the array outside boundaries.0. 1.0]]) print a 0 0 0 0] 1 0 1 0] 0 1 1 0] 0 0 0 0]] print binary_dilation(zeros(a. 1. struct. If no structuring element is provided. 1. a. The border_value parameter gives the value of the array outside boundaries.1.1. A function is provided that allows the calculation of a structure that is dilated a number of times with itself: The iterate_structure function returns a structure by dilation of the input structure iteration .1. The origin parameter controls the placement of the structuring element as described in Filter functions. -1) (array([[0. 0. The binary_dilation function implements binary dilation of arrays of arbitrary rank with the given structuring element. 1. 1.0]. [1.0. If iterations is less than one. The erosion is repeated iterations times. [0. [0. Here is an example of using binary_dilation to ﬁnd all elements that touch the border. 0]]) a = array([[1.11. If a mask array is given. 1. [0. then it is also equal to 0 for the iterated structure. Repeating an erosion or a dilation with a given structure n times is equivalent to an erosion or a dilation with a structure that is n-1 times dilated with itself. only those elements with a true value at the corresponding mask element are modiﬁed at each iteration.0.1 times with itself.0]. [0. Multi-dimensional image processing (ndimage) 81 . an element with connectivity equal to one is generated using generate_binary_structure. the origin must also be adapted if the equivalent of the iterations erosions or dilations must be achieved with the iterated structure. The adapted origin is simply obtained by multiplying with the number of iterations. 1) print struct 1 0] 1 1] 1 0]] print iterate_structure(struct. border_value=1) 0 0 0 0] 1 0 0 0] 0 0 0 0] 0 0 0 0]] The binary_erosion and binary_dilation functions both have an iterations parameter which allows the erosion or dilation to be repeated a number of times. 2) 0 1 0 0] 1 1 1 0] 1 1 1 1] 1 1 1 0] 0 1 0 0]] If the origin of the original structure is equal to 0. the erosion is repeated until the result does not change anymore. If iterations is less than one.

it is set equal to the logical not of structure1. or by the size parameter if structure is not given. Grey-scale morphology Grey-scale morphology operations are the equivalents of binary morphology operations that operate on arrays with arbitrary values. The binary_fill_holes function is used to close holes in objects in a binary image. If the ﬁrst structuring element is not provided. Similar to binary erosion and dilation there are operations for grey-scale erosion and dilation: The grey_erosion function calculates a multi-dimensional grey. The origin parameters control the placement of the structuring elements as described in Filter functions. 0. The iterations parameter gives the number of dilations that is performed followed by the same number of erosions. The grey_dilation function calculates a multi-dimensional grey. If no structuring element is provided. If origin2 equals None it is set equal to the origin1 parameter. must be an array that deﬁnes the shape of the kernel by its non-zero elements.SciPy Reference Guide. 82 Chapter 1. the structure is assumed to be rectangular. opening and closing. 0]]. The origin parameter controls the placement of the structuring element as described in Filter functions. The grey-scale morphology operations optionally take a structure parameter that gives the values of the structuring element. If this parameter is not given the structuring element is assumed to be ﬂat with a value equal to zero. with sizes equal to the dimensions of the structure array. an element with connectivity equal to one is generated using generate_binary_structure.scale dilation. must be a sequence of sizes or a single number in which case the size of the ﬁlter is assumed to be equal along each axis. where the structure deﬁnes the connectivity of the holes. Grey-scale opening and closing operations can be deﬁned similar to their binary counterparts: The grey_opening function implements grey-scale opening of arrays of arbitrary rank. The binary_hit_or_miss function implements a binary hit-or-miss transform of arrays of arbitrary rank with the given structuring elements.10. These operations are implemented in a similar fashion as the ﬁlters described in Filter functions.dev6665 [0. dilation. If this parameter is not given. The shape of the structure can optionally be deﬁned by the footprint parameter. 0. [-2.scale erosion. an element with connectivity equal to one is generated using generate_binary_structure. -2]) Other morphology operations can be deﬁned in terms of erosion and d dilation. Grey-scale opening is equivalent to a grey-scale erosion followed by a grey-scale dilation. The origin parameter controls the placement of the structuring element as described in Filter functions. type=Bool). Below we describe the grey-scale equivalents of erosion. and the handling of array borders. if structure2 is not provided. SciPy Tutorial . a structuring element with connectivity equal to one is generated using generate_binary_structure. if provided. If no structuring element is provided. and we refer to this section for the description of ﬁlter kernels and footprints. in which case the structuring element is assumed to be rectangular and ﬂat with the dimensions given by size.0. 1. The iterations parameter gives the number of erosions that is performed followed by the same number of dilations. The binary_closing function implements binary closing of arrays of arbitrary rank with the given structuring element. If no structuring element is provided. The size parameter is only used if both structure and footprint are not given. Binary closing is equivalent to a binary dilation followed by a binary erosion with the same structuring element. Release 0. an element with connectivity equal to one is generated using generate_binary_structure. The footprint parameter. if provided. erosion of the logical not of the input with the second structure. Following functions provide a few of these operations for convenience: The binary_opening function implements binary opening of arrays of arbitrary rank with the given structuring element. The origin parameter controls the placement of the structuring element as described in Filter functions. The size parameter. Binary opening is equivalent to a binary erosion followed by a binary dilation with the same structuring element. The hit-or-miss transform is calculated by erosion of the input with the ﬁrst structure. followed by the logical and of these two erosions.

Grey-scale opening is equivalent to a grey-scale dilation followed by a grey-scale erosion. Computer Vision. The distances and indices arguments can be used to give optional output arrays that must be of the correct size and type (Float64 and Int32). the feature transform can be calculated. The function distance_transform_edt calculates the exact euclidean distance transform of the input. or a single number in which the sampling is assumed to be equal along all axes. The grey-scale morphological gradient is equal to the difference of a grey-scale dilation and a grey-scale erosion. In this case the index of the closest background element is returned along the ﬁrst axis of the result. If the structure is equal to ‘cityblock’ a structure is generated using generate_binary_structure with a squared distance equal to 1.dev6665 The grey_closing function implements grey-scale closing of arrays of arbitrary rank. The distances and indices arguments can be used to give optional output arrays that must be of the correct size and type (both Int32).11. 1. The morphological_laplace function implements a grey-scale morphological laplace of arrays of arbitrary rank. In addition to the distance transform. The black_tophat function implements a black top-hat ﬁlter of arrays of arbitrary rank. a structure is generated using generate_binary_structure with a squared distance equal to the rank of the array.6 Distance transforms Distance transforms are used to calculate the minimum distance from each element of an object to the background. The basics of the algorithm used to implement this function is described in: G. Graphics. or both must be returned. by replacing each object element (deﬁned by values larger than zero) with the shortest distance to the background (all non-object elements). the feature transform. 1984. The white top-hat is equal to the difference of the input and a grey-scale opening. The white_tophat function implements a white top-hat ﬁlter of arrays of arbitrary rank. and Chessboard distances. and return_indices ﬂags can be used to indicate if the distance transform. The following functions implement distance transforms for three different distance metrics: Euclidean. The morphological_gradient function implements a grey-scale morphological gradient of arrays of arbitrary rank.11. The return_distances. The structure determines the type of chamfering that is done.0.”. The return_distances. “Distance transformations in arbitrary dimensions. and return_indices ﬂags can be used to indicate if the distance transform. Multi-dimensional image processing (ndimage) 83 . or both must be returned. Borgefors. The function distance_transform_cdt uses a chamfer type algorithm to calculate the distance transform of the input. The grey-scale morphological laplace is equal to the sum of a grey-scale dilation and a grey-scale erosion minus twice the input. These choices correspond to the common interpretations of the cityblock and the chessboard distancemetrics in two dimensions.SciPy Reference Guide.10. Release 0. 27:321345. The black top-hat is equal to the difference of the a grey-scale closing and the input. and Image Processing. City Block. In addition to the distance transform. If the structure is equal to ‘chessboard’. In this case the index of the closest background element is returned along the ﬁrst axis of the result. the feature transform. the feature transform can be calculated. by replacing each object element (deﬁned by values larger than zero) with the shortest euclidean distance to the background (all non-object elements). Optionally the sampling along each axis can be given by the sampling parameter which should be a sequence of length equal to the input rank. 1.

IEEE Trans. >>> [[0 [0 [0 [0 a = array([[1. . [0.1.1.0. [1. in which case only the number of objects is returned.1. [0.[0.0. This parameter is only used in the case of the euclidean distance transform.3.. 265-270.[0.1.SciPy Reference Guide. 2. which is easily done with numpy functions: >>> . 0. 1. [1. SciPy Tutorial .1.3. 0. 0) 1 1 0 0 0] 1 1 0 1 0] 0 0 1 1 1] 0 0 0 1 0]] The result is a binary image. Release 0. 2.7 Segmentation and labeling Segmentation is the process of separating objects of interest from the background. The metric must be one of “euclidean”.2]. 2) 84 Chapter 1.0. and return_indices ﬂags can be used to indicate if the distance transform. or both must be returned.1. 1. 0]. The distances and indices arguments can be used to give optional output arrays that must be of the correct size and type (Float64 and Int32). 0.2.1]]) print where(a > 1. 1.[0.1. 0.2. 0.1. The most simple approach is probably intensity thresholding. The function label generates an array where each object is assigned a unique number: The label function generates an array where the objects in the input are labeled with an integer index. the feature transform can be calculated.1.1.. It returns a tuple consisting of the array of object labels and the number of objects found. in which the individual objects still need to be identiﬁed and labeled. Raghavan.0. Note: This function uses a slow brute-force algorithm. 0].1].0]]) >>> s = [[0. or “chessboard”. 2003.1. [1. .1.2. 0.1. 0].2. The function distance_transform_edt can be used to more efﬁciently calculate the exact euclidean distance transform.11. the function distance_transform_cdt can be used to more efﬁciently calculate cityblock and chessboard distance transforms. R.. R. In addition to the distance transform. unless the output parameter is given. or a single number in which the sampling is assumed to be equal along all axes. Qi.3.. 2]. [0. 0.. s) (array([[0. The connectivity of the objects is deﬁned by a structuring element.10. and V. [0. 1.0. the feature transform.1.1.0]..0. “A linear time algorithm for computing exact euclidean distance transforms of binary images in arbitrary dimensions.1].0]. 0]]). The function distance_transform_bf uses a brute-force algorithm to calculate the distance transform of the input. 2. For instance. 1. The return_distances..0]] >>> print label(a.1.0]. 2.0.0].0. 1.2. “cityblock”.1.1. Jr. in two dimensions using a four-connected structuring element gives: >>> a = array([[0. 1.0. 0. PAMI 25. by replacing each object element (deﬁned by values larger than zero) with the shortest distance to the background (all non-object elements). Maurer. [0.dev6665 The algorithm used to implement this function is described in: C. In this case the index of the closest background element is returned along the ﬁrst axis of the result. Optionally the sampling along each axis can be given by the sampling parameter which should be a sequence of length equal to the input rank.

This is useful if you need to ‘re-label’ an array of object indices. 0]. 0]]. 0. There is a large number of other approaches for segmentation. . [0. where any non-zero value is a marker. 1.SciPy Reference Guide. For instance: >>> l. . 0]. . ..1]. [0. 0. using an Iterative Forest Transform.. 0.1. for instance from an estimation of the borders of the objects that can be obtained for instance by derivative ﬁlters. 0.. 1.1]. 1. The function watershed_ift generates an array where each object is assigned a unique label. Eurographics 2001. 0.. 0. and an array of markers that designate the objects by a unique label. .”. [0. 0]. 0... numarray. 0. as described in: P. 0.[0. 0. 1. However. 0) >>> print l [1 0 0 0 3] >>> print label(l)[0] [1 0 0 0 2] Note: The structuring element used by label is assumed to be symmetric. 1. 0. 0. 0].. 0. 0. 0.11.0.. 0.0.1.1. For instance: >>> .. Release 0. 1.0. 0. . 0.. .. [0. [0. 0.1. 0]. an 8-connected structuring element results in only a single object: >>> >>> >>> [[0 [0 [0 [0 a = array([[0.0]. The inputs of this function are the array to which the transform is applied.1. one is generated by calling generate_binary_structure (see Binary morphology) using a connectivity of one (which in 2D is the 4-connected structure of the ﬁrst example). . 1.10. 0. 0.. n = label([1.. 1]) >>> print l [1 0 2 0 3] >>> l = where(l != 2. 0. [0. 0. 0. 0. 0. 0. Bruckschwaiger. 0]. 1.UInt8) markers = array([[1. numarray.. 0]..0. markers) 1 1 1 1 1 1] 1. 0. 0. 0. It uses an array containing initial markers for the objects: The watershed_ift function applies a watershed from markers algorithm. 0.Int8) print watershed_ift(input.0. 0. and M. >>> [[1 input = array([[0. 0. The input can be of any type. 0. 0.1. 1.0. [0.0.[0. 0. . 0. [0. for instance after removing unwanted objects. 0. [1. 0. [0.[0. 0. 0].. 0. from an array that localizes the object borders. 0. s)[0] 1 1 0 0 0] 1 1 0 1 0] 0 0 1 1 1] 0 0 0 1 0]] If no structuring element is provided. Just apply the label function again to the index array. 2.. Multi-dimensional image processing (ndimage) 85 . R. 1. 0. 0. generated for instance by a gradient magnitude ﬁlter. Wegenkittl. 0].1. [0. >>> . l. 0. 1.0. C:26-35. 0.1. pp. 1.1. 0.1. 1. “Implementation and Complexity of the Watershed-from-Markers Algorithm Computed as a Minimal Cost Forest.. [0. [1.. 0. any value not equal to zero is taken to be part of an object.0].dev6665 These two objects are not connected because there is no way in which we can place the structuring element such that it overlaps with both objects... 0.1]. 0.. 0. 1. 0]].. 0. 0. 0. One such an approach is watershed segmentation. [0. 1. 1.1]] print label(a. 1. Felkel. 0]. .. 0]. 0]. 0.0]]) s = [[1.0.1.

0. using an 8-connected structure with the last example yields a different object: >>> print watershed_ift(input. [0.. 1]]. .. numarray. 0. 0. 0]. >>> [[1 [1 [1 [1 [1 [1 [1 markers = array([[0. 0. markers) 0]. 0. 0. 0.10. [[-1 -1 -1 -1 -1 -1 -1] [-1 -1 2 2 2 -1 -1] [-1 2 2 2 2 2 -1] [-1 2 2 2 2 2 -1] [-1 2 2 2 2 2 -1] [-1 -1 2 2 2 -1 -1] [-1 -1 -1 -1 -1 -1 -1]] 0. 0. markers) 0]. ..1]. 0.. 0. .) For example. 0].. 0. 0]. numarray.. [1. 0..1.1. 0]. 0.. 0. structure = [[1.SciPy Reference Guide. [0. . 0.. print watershed_ift(input. 0. 0].. [0. 0. 0. 0. 0. 0. 0. 0. This may not be the desired effect if the ﬁrst marker was supposed to designate a background object. 0.. Release 0. 0]. If no structuring element is provided. 0. 0. 0. . 0. . 0. 0.. 0. 0. 0.. [0. [0. 0. Therefore watershed_ift treats markers with a negative value explicitly as background markers and processes them after the normal markers. 0. SciPy Tutorial . . 0. 0]. 0. 0.. 0].1]. 1 1 1 1 1 1] 1 1 1 1 1 1] 1 2 2 2 1 1] 1 2 2 2 1 1] 1 2 2 2 1 1] 1 1 1 1 1 1] 1 1 1 1 1 1]] 0. 0. For instance. one is generated by calling generate_binary_structure (see Binary morphology) using a connectivity of one (which in 2D is a 4-connected structure. [0. 0. 0. . 0. 2. 0. 0.1.Int8) The result is that the object (marker = 2) is smaller because the second marker was processed earlier.. 0. 0. The order in which these are processed is arbitrary: moving the marker for the background to the lower right corner of the array yields a different result: >>> .... . markers. -1]]. 0. 0. 0. 0.Int8) The connectivity of the objects is deﬁned by a structuring element. [0. 0. 0... 0. 0.dev6665 [1 [1 [1 [1 [1 [1 1 2 2 2 1 1 2 2 2 2 2 1 2 2 2 2 2 1 2 2 2 2 2 1 1 2 2 2 1 1 1] 1] 1] 1] 1] 1]] Here two markers were used to designate an object (marker = 2) and the background (marker = 1). replacing the ﬁrst marker by a negative marker gives a result similar to the ﬁrst example: >>> markers = array([[0. [0. 0. 0. >>> print watershed_ift(input. 0. [0.. 2.. 0..0. 0.. .. 0. 0.1]]) [[-1 -1 -1 -1 -1 -1 -1] [-1 2 2 2 2 2 -1] 86 Chapter 1. [0. 0]. [1.. 0. [0. 0. 0. 0. . . 0. 0]. [0.

10. 2) 80. 3. in which case only the ﬁrst max_label objects are returned.1.[0. unless the max_label parameter is larger then zero. max_label = 3) [(slice(0.0.0 For large arrays and small objects it is more efﬁcient to call the measurement functions after slicing the array: 1. 4].dev6665 [-1 2 2 2 2 2 [-1 2 2 2 2 2 [-1 2 2 2 2 2 [-1 2 2 2 2 2 [-1 -1 -1 -1 -1 -1 -1] -1] -1] -1] -1]] Note: The implementation of watershed_ift limits the data types of the input to UInt8 and UInt16.1].0. (slice(2.1.1].).0. The find_objects function can be used to generate a list of slices that for each object.0.shape=(4. If an index is missing in the label array. Therefore a few measurements functions are deﬁned that accept the array of object labels and the index of the object to be measured.1. image[slices[1]]. None).1. 1.SciPy Reference Guide. 0. n = label(a) f = find_objects(l) print a[f[0]] 1] 1]] print a[f[1]] 1 0] 1 1] 1 0]] find_objects returns slices for all objects. None).0]. For instance: >>> >>> >>> >>> [[1 [1 >>> [[0 [1 [0 a = array([[0.sum() 80 That is however not particularly efﬁcient.0.0.0]]) l.)] The list of slices generated by find_objects is useful to ﬁnd the position and dimensions of the objects in the array. Multi-dimensional image processing (ndimage) 87 .[0. labels.0.1.0].0.8 Object measurements Given an array of labeled objects.[0.1. None is return instead of a slice.0].1. Say we want to ﬁnd the sum of the intensities of an object in image: >>> >>> >>> >>> image = arange(4*6.0.0.6)) mask = array([[0.0]]) labels = label(mask)[0] slices = find_objects(labels) Then we can calculate the sum of the elements in the second object: >>> print where(labels[slices[1]] == 2.0].1. None.0.11.0.1.1. 3.1. Release 0. give the smallest sub-array that fully contains the object: The find_objects function ﬁnds all objects in a labeled array and returns a list of slices that correspond to the smallest regions in the array that contains the object.0.1.1. the properties of the individual objects can be measured. For example: >>> print find_objects([1.[0.0. For instance calculating the sum of the intensities can be done by: >>> print sum(image. 0). but can also be used to perform measurements on the individual objects.1.[0.0.1.1.11.[0. 1.0. and may also be more complicated for other types of measurements.0.

The maximum function calculates the maximum of the elements of the object with label(s) given by index. return their result as a tuple if index is a single number. The result is the same as a tuple formed by the results of the functions minimum. all elements with a non-zero label value are treated as a single object. using the labels array for the object labels.SciPy Reference Guide. If label is None. using the labels array for the object labels. to measure the sum of the values of the background and the second object in our example we give a list of labels: >>> print sum(image. Thus. all elements of input are used in the calculation. if index is a sequence. If label is None.0. The mean function calculates the mean of the elements of the object with label(s) given by index. using the labels array for the object labels. all elements of input are used in the calculation. This indicates that all elements where the label is larger than zero should be treated as a single object and measured.0] The measurement functions described below all support the index parameter to indicate which object(s) should be measured. all elements of input are used in the calculation. 88 Chapter 1. labels[slices[1]]. If index is a number or a sequence of numbers it gives the labels of the objects that are measured. we can do the measurements for a number of labels with a single function call. the maximum. The minimum function calculates the minimum of the elements of the object with label(s) given by index. The sum function calculates the sum of the elements of the object with label(s) given by index. The result is a tuple giving the minimum. using the labels array for the object labels. and maximum_position that are described above. If index is None. If label is None. 80. all elements of input are used in the calculation. If index is None. returning a list of results.0 Alternatively. all elements with a non-zero label value are treated as a single object. The maximum_position function calculates the position of the maximum of the elements of the object with label(s) given by index. minimum_position. using the labels array for the object labels. If index is None. all elements with a non-zero label value are treated as a single object. If label is None. all elements with a non-zero label value are treated as a single object. If label is None. If label is None.0. all elements of input are used in the calculation.10. all elements of input are used in the calculation. If label is None. Functions that return more than one result. all elements with a non-zero label value are treated as a single object. [0. The extrema function calculates the minimum. or as a tuple of lists. using the labels array for the object labels. and their positions. For instance. 2]) [178. Release 0. The variance function calculates the variance of the elements of the object with label(s) given by index. in this case the labels array is treated as a mask deﬁned by the elements that are larger than zero. all elements of input are used in the calculation. The standard_deviation function calculates the standard deviation of the elements of the object with label(s) given by index. If label is None. using the labels array for the object labels. using the labels array for the object labels. If index is None. all elements with a non-zero label value are treated as a single object. If index is a sequence. The default value of index is None. maximum. If index is None. If index is None. using the labels array for the object labels. SciPy Tutorial . labels. all elements of input are used in the calculation. The minimum_position function calculates the position of the minimum of the elements of the object with label(s) given by index. the position of the minimum and the postition of the maximum. a list of the results is returned. If index is None.dev6665 >>> print sum(image[slices[1]]. 2) 80. all elements of input are used in the calculation. If label is None. all elements with a non-zero label value are treated as a single object. of the elements of the object with label(s) given by index. If index is None. the maximum. If index is None. all elements with a non-zero label value are treated as a single object. all elements with a non-zero label value are treated as a single object.

all elements with a non-zero label value are treated as a single object. you must write your own C extension that deﬁnes the function. using the labels array for the object labels. The histogram function calculates a histogram of the of the object with label(s) given by index.dev6665 The center_of_mass function calculates the center of mass of the of the object with label(s) given by index. } This function is called at every element of the output array. since no error can occur.10.0.ndimage take a call-back argument. *cdata = shift. If label is None. Both are passed by a single PyCObject which is created by the following python extension function: static PyObject * py_shift_function(PyObject *obj. Histograms are deﬁned by their minimum (min).shift. Release 0. If index is None. return NULL.11.9 Extending ndimage in C A few functions in the scipy. The ranks of the input and output array are passed through output_rank and input_rank. since the overhead of calling a python function at each element is avoided. } else { /* assign the shift to a dynamically allocated location: */ double *cdata = (double*)malloc(sizeof(double)). &shift)) { PyErr_SetString(PyExc_RuntimeError. in this case always 1. The value of the shift is passed through the callback_data argument. /* return OK status: */ return 1. A pointer to this function and a pointer to the shift value must be passed to geometric_transform. To use this feature. This can be a python function. An example of a function that supports this is geometric_transform (see Interpolation functions). They are returned as one-dimensional arrays of type Int32. PyObject *args) { double shift = 0. int input_rank. ii < irank. passing the current coordinates in the output_coordinates array. all elements of input are used in the calculation.SciPy Reference Guide. Multi-dimensional image processing (ndimage) 89 . maximum (max) and the number of bins (bins).11. int output_rank. "d". This mapping function can also be a C function. and deﬁne a Python function that returns a PyCObject containing a pointer to this function. ii++) icoor[ii] = ocoor[ii] . void *callback_data) { int ii. The function returns an error status. /* get the shift from the callback data pointer: */ double shift = *(double*)callback_data. /* wrap function and callback_data in a CObject: */ 1. if (!PyArg_ParseTuple(args. double* input_coordinates. For example to implement a simple shift function we deﬁne the following function: static int _shift_function(int *output_coordinates. You can pass it a python callable object that deﬁnes a mapping from all output coordinates to corresponding coordinates in the input array. If index is None. /* calculate the coordinates: */ for(ii = 0. On return. but also a PyCObject containing a pointer to a C function. which generally will be much more efﬁcient. using the labels array for the object labels. 1.0. all elements with a non-zero label value are treated as a single object. If label is None. all elements of input are used in the calculation. "invalid parameters"). the input_coordinates array must contain the coordinates at which the input is interpolated. which is a pointer to void.

7375] [ 0. cdata. This destructor is very simple: static void _destructor(void* cobject. _destructor).SciPy Reference Guide. a default error message is set by the calling function. ] [ 0. fnc) [[ 0.10 Functions that support C callback functions The ndimage functions that support C callback functions are described here. (PyCFunction)py_shift_function.5) >>> print geometric_transform(array. 1. otherwise. } } The value of the shift is obtained and then assigned to a dynamically allocated memory location. METH_VARARGS. Additionally. The next section lists the ndimage functions that acccept a C callback function and gives the prototype of the callback function.3625 2. 0.1875] [ 0. a pointer to a destructor function is given.6375]] C callback functions for use with ndimage functions must all be written according to this scheme. or 1 otherwise. which can also accept a pointer to a destructor function to free any memory allocated for callback_data. NULL} }.3). 4. PyCObject_FromVoidPtr may be used instead. methods). 0. void initexample(void) { Py_InitModule("example". {NULL. All these callback functions accept a void callback_data pointer that must be wrapped in a PyCObject using the Python PyCObject_FromVoidPtrAndDesc function. Therefore we give here the prototypes of the callback functions. type = Float64) >>> fnc = example. } This extension can then be used in Python. } To use these functions. 0. The function generic_filter (see Generic ﬁlter functions) accepts a callback function with the following prototype: 90 Chapter 1.8125 6. If callback_data is not needed. Both this data pointer and the function pointer are then wrapped in a PyCObject. SciPy Tutorial . which is returned. If an error occurs.2625 9.0. The callback functions must return an integer error status that is equal to zero if something went wrong. that will free the memory we allocated for the shift value when the PyCObject is destroyed. the prototype of the function that is provided to these functions must match exactly that what they expect.shift_function(0.10. ""}. 1.11. void *cdata) { if (cdata) free(cdata). 8. an extension module is built: static PyMethodDef methods[] = { {"shift_function". shape=(4.dev6665 return PyCObject_FromVoidPtrAndDesc(_shift_function. Obviously. NULL. Release 0. you should normally set the python error status with an informative message before returning. for example: >>> import example >>> array = arange(12.

io as sio Load MATLAB ﬁle Save a dictionary of names and arrays into a MATLAB-style .0.loadmat sio. you will ﬁnd the mio module . The rank of the input and output arrays are given by input_rank and output_rank respectively.routines. mdict[.. File IO (scipy. The callback function must return the coordinates at which the input must be interpolated in input_coordinates. appendmat. The function geometric_transform (see Interpolation functions) expects a function with the following prototype: The calling function iterates over the elements of the output array.mat ﬁle. appendmat]) savemat(ﬁle_name.matlab. 1.io (in numpy) 1. calling the callback function at each element.io) 91 .dev6665 The calling function iterates over the elements of the input and output arrays. The function generic_filter1d (see Generic ﬁlter functions) accepts a callback function with the following prototype: The calling function iterates over the lines of the input and output arrays..matlab This is the package from which loadmat and savemat are imported.12. **kwargs[. and the result is copied into the array that is passed through the input_line array.containing the machinery that loadmat and savemat use. The length of the input line (after extension) is passed through input_length. try tab completing on sio. . You’ll also ﬁnd: sio. You’ll ﬁnd: sio. mdict. The coordinates of the current output element are passed through output_coordinates.10. The calculated valued should be returned in the return_value argument.12. From time to time you may ﬁnd yourself re-using this machinery. calling the callback function at each line. and the number of elements within the footprint through ﬁlter_size. 1. calling the callback function at each element.savemat These are the high-level functions you will most likely use. If you are using IPython.io) See Also: numpy-reference.12 File IO (scipy. Release 0.SciPy Reference Guide. The current line is extended according to the border conditions set by the calling function.]) Getting started: >>> import scipy. The length of the output line is passed through output_length. The callback function should apply the 1D ﬁlter and store the result in the array passed through output_line.1 MATLAB ﬁles loadmat(ﬁle_name. Within sio. The elements within the footprint of the ﬁlter at the current element are passed through the buffer parameter.

:. Start Octave (octave at the command line for me): octave:1> a = 1:12 a = 1 2 3 4 5 6 7 8 9 10 11 12 octave:2> a = reshape(a.mat Now..mat ﬁle that you want to read into Scipy. 8. to Python: >>> mat_contents = sio.0 MAT-file. 12. 5. 7. Release 0.SciPy Reference Guide..shape (1. 4. 11.].] [ 3.mat octave_a.0. 3.3) = 7 8 9 ans(:. 8..2... you want to pass some variables from Scipy / Numpy into MATLAB. 6. written by Octave 3.loadmat(’octave_a.:. To save us using a MATLAB license. [1 3 4]) a = ans(:.10. 7.. 5.]]] >>> print oct_a.. 11.:..]]]). Or.:. ’__header__’: ’MATLAB 5. ’__globals__’: []} >>> oct_a = mat_contents[’a’] >>> print oct_a [[[ 1.] [ 2. [ 2.1) = 1 2 3 ans(:. let’s start in Octave. 12.dev6665 How do I start? You may have a . SciPy Tutorial .2) = 4 5 6 ans(:. Octave has MATLAB-compatible save / load functions. 4) Now let’s try the other way round: 92 Chapter 1. 6.. 9.4) = 10 11 12 octave:3> save -6 octave_a. 10.3. 2010-05-30 02:13:40 UTC’. 9. ’__version__’: ’1.0’.mat a % MATLAB 6 compatible octave:4> ls octave_a.]. 4.mat’) >>> print mat_contents {’a’: array([[[ 1. 10. [ 3.

dev6665 >>> import numpy as np >>> vect = np. 1). except the ﬁeld names must be strings.mat octave:9> vect vect = 0 1 2 3 4 5 6 7 8 9 octave:10> size(vect) ans = 1 10 MATLAB structs MATLAB structs are a little bit like Python dicts.6/site-packages/scipy/io/matlab/mio. structs are in fact arrays of structs. oned_as=’row’) We can load this in Octave or MATLAB: octave:8> load np_vector.mat’. 1. ’field2’. 2) my_struct = { 1. where a single struct is an array of shape (1.arange(10) >>> print vect.SciPy Reference Guide.py:196: FutureWarning oned_as=oned_as) Then back to Octave: octave:5> load np_vector. this will default to row instead of column: >>> sio.savemat(’np_vector. {’vect’:vect}) /Users/mb312/usr/local/lib/python2.) >>> sio.shape (10. octave:11> my_struct = struct(’field1’. {’vect’:vect}.0. File IO (scipy. Release 0.mat’.savemat(’np_vector.io) 93 .10. As for all objects in MATLAB. In the future.mat octave:6> vect vect = 0 1 2 3 4 5 6 7 8 9 octave:7> size(vect) ans = 10 1 Note the deprecation warning. Any MATLAB object can be a value of a ﬁeld.12. The oned_as keyword determines the way in which one-dimensional vectors are stored.

0]])]].it’s a scalar Traceback (most recent call last): 94 Chapter 1.dev6665 field1 = field2 = } 1 2 octave:12> save -6 octave_struct.shape (1. with ﬁelds named for the struct ﬁelds. (’field2’.0]]) >>> print val[’field1’] [[ 1. MATLAB structs come back as numpy structured arrays.loadmat(’octave_struct. (’field2’.field1 array([[ 1. [[2. use the struct_as_record=False parameter to loadmat. Release 0. squeeze_me=True) >>> oct_struct = mat_contents[’my_struct’] >>> oct_struct.]] >>> print val[’field2’] [[ 2. dtype=[(’field1’.shape () Sometimes. ’__header__’: ’MATLAB 5.0]]. 1) >>> val = oct_struct[0. SciPy Tutorial .0] >>> print val ([[1. struct_as_record=False.shape # but no . ’__version__’: ’1. in MATLAB.0). ’|O8’)]). the struct array must be at least 2D. >>> mat_contents = sio.0].mat’.dtype [(’field1’.0] and: octave:13> size(my_struct) ans = 1 1 So. try this: >>> mat_contents = sio. it’s more convenient to load the MATLAB structs as python objects rather than numpy structured arrarys . ’|O8’).0 >>> oct_struct = mat_contents[’my_struct’] >>> print oct_struct.0’. If you want all length 1 dimensions squeezed out.mat’.mat’) >>> print mat_contents {’my_struct’: array([[([[1.8. ’|O8’).0.]] >>> print val. In order to do this. [[2. You can see the ﬁeld names in the dtype output above.SciPy Reference Guide.0]].loadmat(’octave_struct. struct_as_record=False) >>> oct_struct = mat_contents[’my_struct’] >>> oct_struct[0. Note also: >>> val = oct_struct[0.it can make the access syntax in python a bit more similar to that in MATLAB.loadmat(’octave_struct. squeeze_me=True) >>> oct_struct = mat_contents[’my_struct’] >>> oct_struct.10. ’|O8’)] In this version of Scipy (0.mat my_struct We can load this in Python: >>> mat_contents = sio. and we replicate that when we read into Scipy.mat’.loadmat(’octave_struct.]]) struct_as_record=False works nicely with squeeze_me: >>> mat_contents = sio.

dev6665 File "<stdin>". ’S10’)] >>> arr = np.io.0.mat’.mat my_cells 3 1 Back to Python: >>> mat_contents = sio. ’f8’). [2.SciPy Reference Guide.io) 95 .0. dtype=dt) >>> print arr [(0. {’a_dict’: a_dict}) loaded as: octave:21> load saved_struct octave:22> a_dict a_dict = { field2 = a string field1 = 0. in <module> AttributeError: ’mat_struct’ object has no attribute ’shape’ >>> print type(oct_struct) <class ’scipy.0.savemat(’np_struct_arr. (’f2’.mat’) >>> oct_cells = mat_contents[’my_cells’] >>> print oct_cells.).mat’.0 Saving struct arrays can be done in various ways.field1 1. octave:14> my_cells = {1. {’arr’: arr}) MATLAB cell arrays Cell arrays in MATLAB are rather like python lists.50000 } You can also save structs back again to MATLAB (or Octave in our case) like this: >>> dt = [(’f1’. ’’) (0.savemat(’saved_struct.12.1] = [1.5.mio5_params. line 1. ’’)] >>> arr[0][’f1’] = 0.loadmat(’octave_cells. 3]} my_cells = { [1. File IO (scipy.10.zeros((2.mat_struct’> >>> print oct_struct. ’field2’: ’a string’} >>> sio. in the sense that the elements in the arrays can contain any type of MATLAB object. One simple method is to use dicts: >>> a_dict = {’field1’: 0.dtype object 1. Release 0.matlab.2] = 2 } octave:15> save -6 octave_cells.5 >>> arr[0][’f2’] = ’python’ >>> arr[1][’f1’] = 99 >>> arr[1][’f2’] = ’not perl’ >>> sio. In fact they are most similar to numpy object arrays. and that is how we load them into numpy.

which are the standard data format for WEKA.0.wavfile) read(ﬁle) write(ﬁlename.3 Other save_as_module([ﬁle_name. rate. {’obj_arr’:obj_arr}) octave:16> load np_cells.0] >>> print val [[ 1.2 Matrix Market ﬁles mminfo(source) mmread(source) mmwrite(target. dtype=np. a[.savemat(’np_cells.).object) >>> obj_arr[0] = 1 >>> obj_arr[1] = ’a string’ >>> print obj_arr [1 a string] >>> sio.10.dev6665 >>> val = oct_cells[0. 96 Chapter 1.mat’.12.12. 1.io.12.mat octave:17> obj_arr obj_arr = { [1. SciPy Tutorial .SciPy Reference Guide. ﬁeld. Writes the sparse or dense matrix A to a Matrix Market formatted ﬁle.io.arff) Module to read ARFF ﬁles.1] = 1 [2. Release 0.12.1] = a string } 1. precision]) Queries the contents of the Matrix Market ﬁle ‘ﬁlename’ to Reads the contents of a Matrix Market ﬁle ‘ﬁlename’ into a matrix. See the WEKA website for more details about arff format and available datasets. data) Return the sample rate (in samples/sec) and data from a WAV ﬁle Write a numpy array as a WAV ﬁle 1. ARFF is a text ﬁle format which support numerical.4 Wav sound ﬁles (scipy.5 Arff ﬁles (scipy. data]) Save the dictionary “data” into a module and shelf named save.zeros((2. 1. string and data values. comment.]] >>> print val. The format can also represent missing data and sparse data.dtype float64 Saving to a MATLAB cell array just involves making a numpy object array: >>> obj_arr = np.

’w’) >>> f.. 3.. (’color’.10.io import arff >>> content = """ .75. 4.0.... ’green’. 3.. dtype=[(’width’..6 Netcdf (scipy. """ >>> f = open(’testdata.12.3. 4. Release 0. @data .0.blue .. 3.arff’) >>> data array([(5. ’<f8’). @attribute height numeric . Allows reading of NetCDF ﬁles (version of pupynere package) 1. 1.netcdf) netcdf_file(ﬁlename[.SciPy Reference Guide.1 Outline 1.0.25. (’height’.blue... ’black’) loadarff(ﬁlename) Read an arff ﬁle. version]) A ﬁle object for NetCDF data. Weave 97 ..13 Weave 1.. ’green’).0.. ’<f8’). ’blue’)..0.13..yellow. range is (’red’.75. ’blue’.loadarff(’testdata. @attribute color {red.5.. @relation foo . mode.arff’.. ’red’)]. (4.4.io.black} .00.green.3. @attribute width numeric . meta = arff. ’|S6’)]) >>> meta Dataset: foo width’s type is numeric height’s type is numeric color’s type is nominal.5. mmap. (3..red .write(content) >>> f.close() >>> data. 5.0.13. ’yellow’.25.dev6665 Examples >>> from scipy.green .

Tuple. Instance. and Dictionary Conversion · File Conversion · Callable. SciPy Tutorial .0.SciPy Reference Guide.dev6665 Contents • Weave – Outline – Introduction – Requirements – Installation – Testing * Testing Notes: – Benchmarks – Inline * More with printf * More examples · Binary search · Dictionary Sort · NumPy – cast/copy/transpose · wxPython * Keyword Option * Inline Arguments * Distutils keywords · Keyword Option Examples · Returning Values · The issue with locals() · A quick look at the code * Technical Details * Passing Variables in/out of the C/C++ code * Type Conversions · NumPy Argument Conversion · String. List. Release 0.10. and Module Conversion · Customizing Conversions * The Catalog · Function Storage · Catalog search paths and the PYTHONCOMPILED variable – Blitz * Requirements * Limitations * NumPy efﬁciency issues: What compilation buys you * The Tools · Parser · Blitz and NumPy * Type deﬁnitions and coersion * Cataloging Compiled Functions * Checking Array Sizes * Creating the Extension Module – Extension Modules * A Simple Example * Fibonacci Example – Customizing Type Conversions – Type Factories – Things I wish weave did 98 Chapter 1.

Serious users will need to at least look at the type conversion section to understand how Python variables map to C/C++ types and how to customize this behavior. The one issue I’m not sure 1.13. you can use ‘‘ from scipy import weave‘‘ and the examples will work identically.scipy.).py install).2 Introduction The scipy. blitz() was the original reason weave was built. One other note. Release 0. reference counting. Inlining C/C++ code within Python generally results in speed ups of 1. and I’ve had reports that it works on Debian also (thanks Pearu).inline() function executes C code directly within Python. I guess it would be possible to build such a tool on top of weave.0 or higher should work.ext_tools() might be the tool for you. SWIG and friends are deﬁnitely the better choice. On the other hand. Most of weave’s functionality should work on Windows and Unix. weave itself requires a C++ compiler. 1. However.org/svn/scipy/trunk/Lib/weave weave and install as python setup.95. but for anything complex.96). This weave does not do. This is great for inline(). I’m not sure the effort produces any new capabilities. So.13. Weave 99 .. I’m not sure where weave ﬁts in this spectrum.95. Note: weave is actually part of the SciPy package.1. but I expect the majority of compilers should work for inline and ext_tools. it is also possible to slow things down. and others). • C++ compiler weave uses distutils to actually build extension modules. but. weave. but nothing beyond this comes to mind. As of yet. The examples here are given as if it is used as a stand alone package.weave (below just weave) package provides tools for including C/C++ code within in Python code. For those interested in building extension libraries. If you’re wrapping legacy code.13. Things like function overloading are probably easily implemented in weave and it might be easier to mix Python/C code in function calls.SciPy Reference Guide.2 and 2. All tests also pass on Linux (RH 7.. If you are using from within scipy.3-6). and weave. it also works ﬁne as a standalone package (you can check out the sources using svn co http://svn. The next several sections give the basics of how to use weave. it is more ﬂexible to specify things the other way around – that is how C types map to Python types. so it uses whatever compiler was originally used to build Python. weave is set up so that you can customize how Python types are converted to C types in weave. If you don’t know C or C++ then these docs are probably of very little help to you.1. Further. It is closest in ﬂavor to CXX in that it makes creating new C/C++ extension modules pretty easy. weave does quite a bit for you. but with good tools like SWIG around. Probably 2. However. it’d be helpful if you know something about writing Python extensions. This offers both another level of optimization to those who need it. and an easy way to modify and extend any supported extension libraries such as wxPython and hopefully VTK soon. stick with SWIG. although some of its functionality requires gcc or a similarly modern C++ compiler that handles templates well.blitz() translates Python NumPy expressions to C++ for fast execution. SIP. All testing has been done with gcc. tools for building Python extension modules already exists (SWIG. etc.3 Requirements • Python I use 2. you’ll need to do some conversions. the ext_tools module provides classes for building extension modules within Python.5x to 30x speed-up over algorithms written in pure Python (However. On Unix gcc is the preferred choice because I’ve done a little testing with it. pycpp. if you’re developing new extension modules or optimizing Python functions in C. If you used a C++ compiler to build Python. Generally algorithms that require a large number of calls to the Python API don’t beneﬁt as much from the conversion to C/C++ as algorithms that have inner loops completely convertable to C.10. your probably ﬁne. most testing has been done on Windows 2000 with Microsoft’s C++ compiler (MSVC) and with gcc (mingw32 2. There are three basic ways to use weave. The weave. We’ll discuss what’s happening under the covers in more detail later on. The inline and blitz provide new functionality to Python (although I’ve recently learned about the PyInline project which may offer similar functionality to inline). for wrapping legacy code.1 with gcc 2.0. Up to now.dev6665 1. CXX. if you’re wrapping a gaggle of legacy functions or classes.

..13... >>> import weave >>> weave... since weave is useful outside of the scientiﬁc community.... Other versions are likely to work.. If you get errors............. or is this a gcc-ism? For blitz().4 Installation There are currently two ways to get weave.. so please report success if it works for you.2 works on windows and 2. it should run about 180 tests and spew some speed results along the way...... you’ll need gcc for blitz() as the MSVC compiler doesn’t handle templates well.... spews tons of output and a few warnings .... you can do this by running test() for that speciﬁc module.... Again.5 Testing Once weave is installed............ ---------------------------------------------------------------------Ran 184 tests in 158. 1..96 looks ﬁne on Linux.......... .distutils which is used by weave..... ... Release 0..... I’ve had it take 15 or so minutes..scalar_spec >>> weave. 1. Its likely that KAI’s C++ compiler and maybe some others will work......... My advice is to use gcc for now unless your willing to tinker with the code some...... If you only want to test a single module of the package... it has been setup so that it can be used as a stand-alone module...284s 100 Chapter 1.. The stand-alone version can be downloaded from here....0...... .. Some tests are known to fail at this point....... either MSVC or gcc (mingw32) should work.. On Windows....418s OK >>> This takes a while... Please report errors that you ﬁnd..... >>> import weave. On Unix with remote ﬁle systems. they’ll be reported at the end of the output................13... First... Second.... In the end. SciPy Tutorial .. I have not tried Cygwin...... ---------------------------------------------------------------------Ran 7 tests in 23... usually several minutes.scalar_spec...95. you’ll need a reasonably recent version of gcc... setup....10............. • NumPy The python NumPy module is required for blitz() to work and for numpy.. weave is part of SciPy and installed automatically (as a subpackage) whenever SciPy is installed. Is this standard across Unix compilers... Instructions for installing should be found there as well.......dev6665 about is that I’ve hard coded things so that compilations are linked with the stdc++ library. .test() runs long time.......SciPy Reference Guide.py ﬁle to simplify installation. .. ﬁre up python and run its unit tests.... 2..test() . but I haven’t tried.

95..50 82. let me know . I get gcc-2... I get gcc-2. Without more information about what the test actually do. If I check os. you’ll get a ton of DOS windows popping up periodically as weave spawns the compiler multiple times. If I check after running tests (and after failure). Very annoying. their value is limited.59 9.SciPy Reference Guide.dev6665 Testing Notes: • Windows 1 I’ve had some test fail on windows machines where I have msvc. This section has a few benchmarks – thats all people want to see anyway right? These are mostly taken from running ﬁles in the weave/example directory and also from the test scripts. If your interested in single precision results. ﬁlter.3-6.2.2). their here for the curious. Table 1. Anyone know of a safe way to detect whether wxPython can be imported and whether a display exists on a machine? 1.54 37.2: blitz – double precision Algorithm a = b + c 512x512 a = b + c + d 512x512 5 pt avg.1 on a 850 MHz PIII laptop with 320 MB of RAM. If anyone else sees this.3-6 (in c:gcc) all installed. Weave 101 .0. gcc-2. Testing with the gcc. The blitz() comparisons are shown compared to NumPy. These examples are run under windows 2000 using Microsoft Visual C++ and python2.05 4.95.20 2. 1. The test process runs very smoothly until the end where several test using gcc fail with cpp0 not found by g++.it may just be an quirk on my machine (unlikely). and gcc-2.95.13.1: inline and ext_tools Algorithm binary search ﬁbonacci (recursive) ﬁbonacci (loop) return None map dictionary sort vector quantization Speed up 1. Anyone know how to ﬁx this? • wxPython wxPython tests are not enabled by default because importing wxPython on a Unix machine without access to a X-term will cause the program to exit.14 1. The os. Release 0.17 0. Speed up is the improvement (degredation) factor of weave compared to conventional Python functions.environ[’PATH’] still has c:gcc ﬁrst in it and is not corrupted (msvc/distutils messes with the environment variables.95.95.10. • Windows 2 If you run the tests from PythonWin or some other GUI tool. so we have to undo its work in some places).95. My environment has c:gcc in the path and does not have c:gcc-2. 2D Image 512x512 Electromagnetics (FDTD) 100x100x100 Speed up 3. NumPy (at least on my machine) is signiﬁcantly worse for double precision than it is for single precision calculations.01 8.2 installation always works. ??huh??.95.40 Table 1.2 in the path.2.2 (in c:gcc-2. Still. you can pretty much divide the double precision speed up by 3 and you’ll be close.61 The benchmarks shown blitz in the best possible light..10 9.6 Benchmarks This section has not been updated from old scipy weave and Numeric. Look at the example scripts for more speciﬁcs about what problem was actually solved by each run.13.system(‘gcc -v’) before running tests.

10.cpp ﬁle.cpp Creating library C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp \Release\sc_e013937dbc8c647ac62438874e5795131. Algorithms that have to manipulate Python objects (sorting a list) usually only see a factor of 2 or so improvement. var_list is a list of variable names that are passed from Python into C/C++. This doesn’t mean that inline doesn’t work in these environments – it only means that standard out in C is not the same as the standard out for Python in these cases. The ﬁrst time you run this. PyShell.5. This is because the C code is writing to stdout. and executed. it loads the already compiled module and executes the appropriate function.inline(’printf("%d\\n".dev6665 1. there will be a much shorter delay in the fractions of seconds range. This is because weave stores a catalog of all previously compiled functions in an on disk cache. c_code is a string of valid C/C++ code. etc. Also. The r preceeding the code string in the last example denotes that this is a ‘raw string’.[’a’]) 1 In this. Note: If you try the printf example in a GUI shell such as IDLE. And.SciPy Reference Guide.inline(r’printf("%d\n". In raw strings. When it sees a string that has been compiled.95. The simple printf example is actually slower by 30% or so than using Python print statement.lib and object C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\sc_e013937dbc8c647ac62438874e 1 Nothing bad is happening.py ﬁle shows a factor of 30 or more improvement on the vector quantization algorithm that is used heavily in information theory and classiﬁcation problems. loaded into Python. cataloged for future use. this takes about 1.’. Algorithms that are highly computational or manipulate NumPy arrays can see much larger improvements. More with printf MSVC users will actually see a bit of compiler output that distutils does not supress the ﬁrst time the code executes: >>> weave. compiled into an extension module. its just a bit annoying. Release 0. (more on this later) Here’s a trivial printf example using inline(): >>> import weave >>> a = 1 >>> weave. the backslash character is not interpreted as an escape character. Values are returned from the C/C++ code through a special argument called return_val. If you kill and restart the interpreter and then execute the same code fragment again. instead of to the GUI window.2). the speed up can be worth while – anywhwere from 1. its most basic form. there will be a pause while the code is written to a .0. Although effort has been made to reduce the overhead associated with calling inline.7 Inline inline() compiles and executes C/C++ code on the ﬂy. the contents of mutable objects can be changed within the C/C++ code and the changes remain after the C code exits and returns to Python. Variables in the local and global Python scope are also available in the C/C++ code. On windows (850 MHz PIII). All subsequent executions of the code will happen very quickly because the code only needs to be compiled once. you’re unlikely to see the output.5 seconds when using Microsoft’s C++ compiler (MSVC) and 6-12 seconds using gcc (mingw32 2. it is still less efﬁcient for simple code snippets than using equivalent Python code. and so it isn’t necessary to use a double backslash to indicate that the ‘n’ is meant to be interpreted in the C printf statement 102 Chapter 1. SciPy Tutorial . The examples/vq. for more complicated algorithms. However.30 times faster.’. inline(c_code. * Anyone know how to turn this off?* This example also demonstrates using ‘raw strings’. Values are passed to the C/C++ code by assignment much like variables are passed into a standard Python function. Here we have a simple printf statement that writes the Python variable a to the screen. PythonWin.a).13.[’a’]) sc_e013937dbc8c647ac62438874e5795131. it is not difﬁcult to create code fragments that are 8-10 times slower using inline than equivalent Python..a). Non input/output functions will work as expected. var_list) requires two arguments.

>>> a = ’string’ >>> weave.std::string(a). weave doesn’t convert strings to char*.c_str()). C/C++ code fragments often have to change to accept different types.’.inline(r’printf("%d\n".. His recipe follows: 1. raw strings might make things easier. and execute the code. compile a new version of the code to accept strings as input.’.inline(’std::cout << a << std::endl.py. Weave 103 . If your C code contains a lot of strings and control characters. weave. >>> a = ’string’ >>> def protected_printf(a): .SciPy Reference Guide. but also non-fatal. Also. however.. assert(type(a) == type(1)) . By default. however.[’a’]) >>> protected_printf(1) 1 >>> protected_printf(’string’) AssertError. For inspiration. the result is non-sensical.a).inline(r’printf("%d\n". It includes a few algorithms from the Python Cookbook that have been re-written in inline C to improve speed as well as a couple examples using NumPy and wxPython..13.inline(r’printf("%s\n".[’a’]) string Examples using printf and cout are included in examples/print_example.’.’. the stream objects live in the std (standard) namespace and thus require the use of std::.[’a’]) 32956972 In this case. standard strings work just as well. The result? >>> a = ’string’ >>> weave. >>> weave. More examples This section shows several more advanced uses of inline. Release 0. Here we convert it to a C++ std::string and then ask cor the char* version. Its possible to protect against passing inline arguments of the wrong data type by using asserts in Python.. so you have to do a little more work.0. The printf statement in these examples is formatted to print out integers. Instead it uses CXX Py::String type. it might produce a compile time error because a is required to be an integer at some point in the code.. What happens if a is a string? inline will happily.inline(’std::cout << a << std::endl.[’a’]) string XXX This is a little convoluted. or it could produce a segmentation fault.a). For printing strings.’.. the format statement needs to be changed. For the given printing task. As in this case.[’a’]) 1 >>> a = ’string’ >>> weave. C++ streams provide a way of a single statement that works for integers and strings. Or maybe to char*.10. Binary search Lets look at the example of searching a sorted list of integers for a value. we’ll use Kalle Svensson’s binary_search() algorithm from the Python Cookbook. In other situations. Perhaps strings should convert to std::string objects instead of CXX objects. Most of the time.dev6665 instead of by Python.

1 else: return m This Python version works for arbitrary Python data types..0. break. val = py_to_int(PyList_GetItem(seq. } m = (min + max) /2.1. seq. else if (val > t) max = m . A little more about CXX and its class methods.1 while 1: if max < min: return -1 m = (min + max) / 2 if seq[m] < t: min = m + 1 elif seq[m] > t: max = m . All other temporary variables such as min.dev6665 def binary_search(seq. for(.t): # do a little type checking in Python assert(type(t) == type(1)) assert(type(seq) == type([])) # now the C code code = """ #line 29 "binary_search. working with Python objects in C/C++. or at least object orientify. break. must be declared – it is C after all. Full documentation for the CXX library can be found at its website. 104 Chapter 1. seq is a Python list. t): min = 0.ptr(). For example.10. PyObject *py_val. The C version below is specialized to handle integer values.[’seq’. min = 0. m. Python integers are converted to C int types in the transition from Python to C. max = len(seq) .length() ."val"). etc.m).SciPy Reference Guide. By default. max. t is guaranteed (by the assert) to be an integer. Release 0.1. } } """ return inline(code.length() returns the length of the list. etc. is in the ** type conversions ** section.’t’]) We have two variables seq and t passed in. There is a little type checking done in Python to assure that we’re working with the correct data types before heading into C. it is translated to a CXX list object.) { if (max < min ) { return_val = Py::new_reference_to(Py::Int(-1)).py" int val. Here’s the new mixed Python/C function: def c_int_binary_search(seq. The variables seq and t don’t need to be declared beacuse weave handles converting and declaring them in the C code. The basics are that the CXX provides C++ class equivalents for Python objects that simplify. else { return_val = Py::new_reference_to(Py::Int(m)). int max = seq. SciPy Tutorial . if (val < t) min = m + 1.

but it appears to me that it would mesh with the needs of weave quite well. If the compilation fails because of the syntax error in the code. All CXX functions and classes live in the namespace Py::. If we move down to searching a 10000 element list.2999). here are the results we get: C:\home\ej\wrk\scipy\weave\examples> python binary_search.32 speed in c: 0. The simple Python seq[i] call balloons into a C Python API call to grab the value out of the list and then a separate call to py_to_int() that converts the PyObject* to an integer. I think the log(N) algorithm is to blame. This removes the need for most error checking code. The examples/binary_search. Release 0. the overhead in using them appears to be relatively high. return_val is an automatically deﬁned variable of type PyObject* that is returned from the C code back to Python. This submission. The entire C++ code block is executed with in a try/catch block that handles exceptions much like Python does. The second big differences shows up in the retrieval of integer values from the Python list.78 So.0900000333786 speed up: 1. Anyone have other explanations or faster code.SciPy Reference Guide.13.py Binary search for 3000 items in 1000000 length list of integers: speed in python: 0. SCXX has a few less features. There are two main differences. It doesn’t use templates so it should compile faster and be more portable. However. In this example. it just a question of which becomes the default. there just isn’t much time spent computing things. so the standard Python API was used on the seq.110000014305 speed up: 1. Because the algorithm is nice. So what was all our effort worth in terms of efﬁciency? Well not a lot in this case. You’ll have to handle reference counting issues when setting this variable. demonstrates how to return the values from a dictionary sorted by their keys: 1. but it’s nice for debugging. Most of the algorithm above looks similar in C to the original Python code.dev6665 Note: CXX uses templates and therefore may be a little less portable than another alternative by Gordan McMillan called SCXX which was inspired by CXX.py” with an offset from the given line number (29 here). It is worth note that CXX lists do have indexing operators that result in code that looks much like Python. The ﬁrst is the setting of return_val instead of directly returning from the C code with a return statement. Both sets of spec ﬁles will probably stick around. so moving to C isn’t that big of a win. please let me know.45 speed in c(no asserts): 0. by Alex Martelli. the error will be reported as an error in the Python ﬁle “binary_search.10. The #line directive that is the ﬁrst line of the C code block isn’t necessary. but my preliminary efforts didn’t produce one. return_val = Py::new_reference_to(Py::Int(m)).py is another example from the Python CookBook. Even smaller lists might result in the Python version being faster. this may improve the C/Python speed up. the advantage evaporates.159999966621 speed of bisect: 0. Weave 105 . an exception is raised. If we run it on a 1 million element list and run the search 3000 times (for 0.0. py_to_int() includes both a NULL cheack and a PyInt_Check() call as well as the conversion call. If there are ways to reduce conversion overhead of values.py ﬁle runs both Python and C versions of the functions As well as using the standard bisect module.ptr() which is the underlying PyObject* of the List object. If either of the checks fail.121000051498 speed up: 1. and we’ll be able to compare on a more empirical basis. I’d like to say that moving to NumPy lists (and getting rid of the GetItem() call) offers a substantial speed up. The following code converts the integer m to a CXX Int() object and then to a PyObject* with an incremented reference count using Py::new_reference_to(). Hopefully xxx_spec ﬁles will be written for SCXX in the future. Dictionary Sort The demo in examples/dict_sort. CXX classes and functions handle the dirty work. we get roughly a 50-75% improvement depending on whether we use the Python asserts in our C version.

ptr(). The C version of this same algorithm follows: def c_sort(adict): assert(type(adict) == type({})) code = """ #line 21 "dict_sort. i < keys. """ return inline_tools.0.SciPy Reference Guide. 1. is about a factor of 2 faster than Python. Again. Py_XINCREF(item).ptr(). PyList_SetItem(items. 2. Here is the Python version of the function using standard NumPy operations. keys. a signiﬁcant portion of the common routines such as LU decompisition or singular value decompostion are spent in this setup routine. Release 0.dev6665 def sortedDictValues3(adict): keys = adict.typecode() == type: cast_array = copy.length()).i.keys(). Py::List items(keys. The C++ version.12 [0.item).inline(code.verbose=1) Like the original Python function.i++) { item = PyList_GET_ITEM(keys.keys() keys.10.151000022888 speed up: 2.319999933243 [0. but uses Python API calls to manipulate their contents.py" Py::List keys = adict. this choice is made for speed. 3.a_2d): 106 Chapter 1. It uses CXX objects for the most part to declare python types in C++. 2. the C++ version can handle any Python dictionary regardless of the key/value pair types. item = PyDict_GetItem(adict.[’adict’].get. Its needed in part because of the row-major memory layout of multi-demensional Python (and C) arrays vs. PyObject* item = NULL. C:\home\ej\wrk\scipy\weave\examples> python dict_sort.blitz_tools import blitz_type_factories from weave import scalar_spec from weave import inline def _cast_copy_transpose(type.transpose(a)) else: cast_array = copy. for(int i = 0. 3.i). array): if a.copy(NumPy.ptr(). 4] speed in c: 0.length().astype(type)) return cast_array And the following is a inline C version of the same function: from weave.copy(NumPy. keys) Alex provides 3 algorithms and this is the 3rd and fastest of the set.sort().item). This shouldn’t happen.py Dict sort of 1000 items for 300 iterations: speed in python: 0. For small matrices (say 100x100 or less). the col-major order of the underlying Fortran algorithms. } return_val = Py::new_reference_to(items). 4] NumPy – cast/copy/transpose CastCopyTranspose is a function called quite heavily by Linear Algebra routines in the NumPy library.sort() return map(adict.transpose(a). while more complicated. 1. SciPy Tutorial . def _castCopyAndTranspose(type.

0. Weave 107 . Release 0. This is why they aren’t the default type used for Numeric arrays (and also because most compilers can’t compile blitz arrays. """ % NumPy_type inline(code. code = \ """ #line 108 "wx_example.i < _Na_2d[0]. Chances are.type) NumPy_type = scalar_spec. wxNORMAL)) dc. inline() is also forced to use ‘gcc’ as the compiler because the default compiler on Windows (MSVC) will not compile blitz code.48 # inplace transpose c: 0. dc->SetPen(wxPen(*blue.py # Cast/Copy/Transposing (150.25 # speed up: 3.’a_2d’].150)array 1 times # speed in python: 0. dc->SetBrush(*grey_brush). but it also demonstrates that the type conversion mechanism is reasonably ﬂexible.py borrows the scrolled window example from the wxPython demo. dc): red = wxNamedColour("RED").13. """ inline(code. 15.SciPy Reference Guide.70 wxPython inline knows how to handle wxPython objects. blue = wxNamedColour("BLUE").compiler=’gcc’) return new_array This example uses blitz++ arrays instead of the standard representation of NumPy arrays so that indexing is simplier to write.dev6665 assert(len(shape(a_2d)) == 2) new_array = zeros(shape(a_2d). wxSWISS.870999932289 # speed in c: 0. i++) for(int j = 0. This is accomplished by passing in the blitz++ “type factories” to override the standard Python to C++ type conversions. Thats nice in and of itself.wxSOLID)).[’dc’.NumPy_to_blitz_type_mapping[type] code = \ """ for(int i = 0. 0x20. Also shown are the results of an “inplace” transpose routine that can be used if the output of the linear algebra routine can overwrite the original matrix (this is often appropriate).wxSOLID)). The examples/wx_example. 50). j < _Na_2d[1].SetTextForeground(wxColour(0xFF. 0xFF)) 1. wxNORMAL. 50. dc->DrawRectangle(5.i). (‘gcc’ I think will use the standard compiler on Unix machine instead of explicitly forcing gcc (check this)) Comparisons of the Python vs inline C++ code show a factor of 3 speed up. fast code.’blue’. but they also are sloooow to compile (20 seconds or more for this snippet).5. dc->SetPen(wxPen(*red. dc->DrawRectangle(15. #C:\home\ej\wrk\scipy\weave\examples> python cast_copy_transpose. accept that it mixes inline C code in the middle of the drawing function.10. def DoDrawing(self. j++) new_array(i.50).. type_factories = blitz_type_factories.4.’grey_brush’]) dc.’red’.4.[’new_array’.). it won’t take a ton of effort to support special types you might have.py" dc->BeginDrawing(). Blitz++ arrays allow you to write clean. grey_brush = wxLIGHT_GREY_BRUSH.j) = (%s) a_2d(j.129999995232 # speed up: 6.. This provides another factor of 2 improvement.SetFont(wxFont(14.50.

local_dict = None. There isn’t currently a way to learn this info from the library – you just have to know.SetPen(wxPen(wxNamedColour(’VIOLET’). Thats because MSVC and gcc. There isn’t any beneﬁt. the keyword arguments for distutils extension modules are accepted to specify extra information needed for compiling. I think there is a way around this.py or weave/wx_info.10. compiler optional. type_factories = None. That should sufﬁciently scare people into not even looking at this. some of the Python calls to wx objects were just converted to C++ calls. it’ll only understand the values understoof by distutils. its probably best. Instead it should assign results that need to be returned to Python in the return_val. it looks for mingw32 (the gcc compiler). 65) dc.DrawText("Hello World"..0. dictionary. Also.dev6665 te = dc.SciPy Reference Guide. On windows. A string of valid C++ code. 0 or 1. If local_dict is not speciﬁed the local dictionary of the calling function is used. customize=None. global_dict optional. are not binary compatible for C++.. 60. no matter what platform you’re on. 65+te[1]) . A list of Python variable names that should be transferred from Python into the C/C++ code. (I should add ‘gcc’ though to this). force optional. string.GetTextExtent("Hello World") dc. It should not specify a return statement. support_code = None. 60+te[0]. it is a dictionary of values that should be used as the local scope for the C/C++ code.py for your machine’s conﬁguration to point at the correct directories etc. it just demonstrates the capabilities.arg_names. while binary compatible in C. If this isn’t available. If 1. Here.. The following is a formatted cut/paste of the argument section of inline’s doc-string. If speciﬁed. This is really only useful for debugging. If global_dict is not speciﬁed the global dictionary of the calling function is used. One ﬁnal note. you’ll have to use the MSVC compiler if you use the standard wxPython DLLs distributed by Robin Dunn. There. auto_downcast=1. it is a dictionary of values that should be used as the global scope for the C/C++ code. The name of compiler to use when compiling. def inline(code. the C++ code is compiled every time inline is called. Inline Arguments code string. 108 Chapter 1. **kw): inline has quite a few options as listed below. force = 0. It also takes keyword arguments that are passed to distutils as compiler options. you’ll need to install the wxWindows libraries and link to them. 65+te[1]. global_dict = None.. local_dict optional. dictionary. SciPy Tutorial . at least on the windows platform. You might want to use this if you have a computationally intensive loop in your drawing code that you want to speed up. Also. If speciﬁed. to specify that inline use the same compiler that was used to build wxPython to be on the safe side. it understands ‘msvc’ and ‘gcc’ as well as all the compiler names understood by distutils. It explains all of the variables. In fact. Release 0.DrawLine(5. :) Keyword Option The basic deﬁnition of the inline() function has a slew of optional variables. compiler=’’. Some examples using various options will follow. verbose = 0. arg_names list of strings. default 0. the compiler defaults to the Microsoft C++ compiler. You’ll probably have to tweak weave/wx_spec. but I haven’t found it yet – I get some linking errors dealing with wxString. On Unix. On windows. and probably only useful if you’re editing support_code a lot. 4)) dc. On windows.

The following descriptions have been copied from Greg Ward’s distutils. Distutils keywords inline() also accepts a number of distutils keywords for controlling how the code is compiled. . Weave 109 . Setting this to 1 will cause all ﬂoating point values to be cast as ﬂoat instead of double if all the NumPy arrays are of type ﬂoat. etc. object ﬁles not implied by ‘sources’. and how long it took.extension. Keyword Option Examples We’ll walk through several examples here to demonstrate the behavior of inline and also how the various arguments are used.10. A string of valid C++ code declaring extra code that might be needed by your compiled function. return_val = Py::new_reference_to(Py::Int(l)). This could be declarations of functions. binary resource ﬁles. support_code optional.SciPy Reference Guide.separated) for portability. code and arg_names are the only arguments that need to be speciﬁed.. value : string|None)] list of macros to deﬁne. For platforms and compilers where “command line” makes sense.i). static library that must be explicitly speciﬁed. 1 informs you when compiling starts. int l = a. classes. SWIG (. (not sure this’ll be used much). These guys are what convert Python data types to C/C++ data types. each macro is deﬁned using a 2-tuple. type_factories optional..[’a’]) sc_86e98826b65b047ffd2cd5f479c627f12. headers. >>> from weave import inline >>> a = ’string’ >>> code = """ . export_symbols [string] list of symbols to be exported from a shared extension. Look in the type conversions section of the main documentation for examples..0..dev6665 On Unix.. """ >>> inline(code. or whatever else is recognized by the “build_ext” command as source for a Python extension. default 1.Extension class doc. string. etc. Source ﬁles may be C.and compiler-speciﬁc information to use when compiling the source ﬁles in ‘sources’. Speﬁcies how much much information is printed during the compile phase of inlining code.cpp ﬁle if you need to examine it. 0 is silent (except on windows with msvc where it still prints some garbage).) extra_compile_args [string] any extra platform. platform. verbose has no affect if the compilation isn’t necessary.strings for convenience: sources [string] list of source ﬁlenames. needed by the function see the weave.length(). or structures. and not generally necessary for Python extensions. list of type speciﬁcation factories. Its handy for ﬁnding the name of the . .speciﬁc resource ﬁles. customize optional. auto_downcast optional. 0. Similar interpretation as for ‘extra_compile_args’. Note: The module_path ﬁle is always appended to the front of this list include_dirs [string] list of directories to search for C/C++ header ﬁles (in Unix form for portability) deﬁne_macros [(name : string. defualt 0.13. base_info. specify them here. or 2. where ‘value’ is either the string to deﬁne it to or None to deﬁne it without a particular value (equivalent of “#deﬁne FOO” in source or -DFOO on Unix C compiler command line) undef_macros [string] list of macros to undeﬁne explicitly library_dirs [string] list of directories to search for C/C++ libraries at link time libraries [string] list of library names (not ﬁlenames or paths) to link against runtime_library_dirs [string] list of directories to search for C/C++ libraries at run time (for shared extensions. Not used on all platforms. but for other platforms it could be anything. ﬁnishes. If you’d like to use a different set of type conversions than the default. extra_link_args [string] any extra platform..and compiler-speciﬁc information to use when linking object ﬁles together to create the extension (or to create a new static Python interpreter). 0 or 1. Here’s a simple example run on Windows machine that has Microsoft VC++ installed. An alternative way to speciﬁy support_code. 2 prints out the command lines for the compilation process and can be useful if you’re having problems getting code to work. Cygwin’s behavior should be similar. which typically export exactly one symbol: “init” + extension_name.base_info module for more details. C++. in Unix form (slash. it’ll probably use the same compiler that was used when compiling Python. this is typically a list of command-line arguments.cpp 1. verbose optional. all variables maintain there standard types. If even one of the arrays has type double or double complex. relative to the distribution root (where the setup script lives). this is when the extension is loaded) extra_objects [string] list of extra ﬁles to link with (eg. In the simplest (most) cases. Release 0.custom_info object. This only affects functions that have Numeric arrays as input variables.1.

inline() did not recompile the code because it found the compiled function in the persistent catalog of functions. .[’a’]. changing any of the other options in inline does not force a recompile. inline does a recompile.[’a’]) 6 When inline is ﬁrst run. return_val = Py::new_reference_to(Py::Int(l)). However. The name of the extension ﬁle. and run the same code with a different string. >>> >>> >>> . but it is much shorter than compiling would require. Note: It also might be nice to add some methods for purging the cache and on disk catalogs.verbose=2. When set to 2..SciPy Reference Guide. the code fragment is not compiled since it already exists.[’a’]) inline(code. SciPy Tutorial .my_dict) Everytime. Because the example has already been compiled. is generated from the md5 check sum of the C/C++ code fragment. This is accomplished through a little call frame trickery. On the second call. Note that error messages from failed compiles are printed to the screen even if verbose is set to 0. Release 0. I use verbose sometimes for debugging. the code is changed.0. The “trash” is acutually part of the compilers output that distutils does not supress. The following example demonstrates using gcc instead of the standard msvc compiler on windows using same code fragment as above. Here is an example where the local_dict is speciﬁed using the same code example from above: >>> >>> >>> >>> 15 >>> 21 a = ’a longer string’ b = ’an even longer string’ my_dict = {’a’:b} inline(code. You can specify the local and global dictionaries if you’d like (much like exec or eval() in Python). the “expected” ones are used – i. but if they aren’t speciﬁed. and only the answer is returned.dev6665 Creating library C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\sc_86e98826b65b047ffd2cd5f47 and object C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\sc_86e98826b65b047ff d2cd5f479c627f12. The verbose ﬂag is added to show what is printed out: >>>inline(code..10. There is a short pause as it looks up and loads the function.[’a’].e. it’ll output all the information (including the name of the . In practice. the force=1 ﬂag is needed to make inline() ignore the previously compiled version and recompile using gcc. it is just as easy to change the code by a single character (like adding a space some place) to force the recompile. the trash will not appear. ..[’a’]) Notice this time. sc_bighonkingnumber.compiler=’gcc’. On Unix or windows machines with only gcc installed. """ inline(code.cpp. the ones from the function that called inline()..force=1) running build_ext 110 Chapter 1..cpp ﬁle) that you’d expect from running a make ﬁle. you’ll notice that pause and some trash printed to the screen.exp 6 >>> inline(code. Now kill the interpreter and restart. This is nice if you need to examine the generated code to see where things are going haywire. The force option was added so that one could force a recompile when tinkering with other variables.length(). >>> 15 from weave import inline a = ’a longer string’ code = """ int l = a..

o C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\cxx_extensions. So.13. .exe --driver-name g++ -mno-cygwin -mdll -static --output-lib C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\libsc_86e98826b65b047ffd2cd5f479c627f13 C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\sc_86e98826b65b047ffd2cd5f479c627f13.o up-to-date) skipping C:\home\ej\wrk\scipy\weave\CXX\IndirectPythonInterface..10. return Py::new_reference_to(Py::Int(l))..". It is a custom_info object that can 1... The support_code argument is likely to be used a lot.95.cpp -o C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\sc_86e98826b65b04ffd2cd5f479c627f13.SciPy Reference Guide.c (C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\cxxextensions.. . finished compiling (sec): 6.o C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\cxxsupport.pyd 15 That’s quite a bit of output.95.[’a’].2\bin\dllwrap. C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\cxxextensions.00800001621 15 Note: I’ve only used the compiler option for switching between ‘msvc’ and ‘gcc’ on windows. Release 0..dev6665 building ’sc_86e98826b65b047ffd2cd5f479c627f13’ extension c:\gcc-2..verbose=1. Weave 111 .0. support_code = support_code) customize is a left over from a previous way of specifying compiler options.cxx (C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\cxx_extensions.de -sC:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\sc_86e98826b65b047ffd2cd5f479c627f13..exe -mno-cygwin -mdll -O2 -w -Wstrict-prototypes -IC: \home\ej\wrk\scipy\weave -IC:\Python21\Include -c C:\DOCUME~1\eric\LOCAL S~1\Temp\python21_compiled\sc_86e98826b65b047ffd2cd5f479c627f13. if you make a change to support_code. >>>inline(code.cxx (C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\indirectpythoninterface.2\bin\g++. verbose=1 just prints the compile time.. I usually just add some inocuous whitespace to the end of one of the lines in code somewhere..o up-to-date) skipping C:\home\ej\wrk\scipy\weave\CXX\cxxsupport. .. Here’s an example of deﬁning a separate method for calculating the string length: >>> >>> >>> .o -LC:\Python21\libs -lpython21 -o C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\sc_86e98826b65b047ffd2cd5f479c627f13. } """ inline("return_val = length(a). Note that changes to support_code do not force a recompile.compiler=’gcc’. It may have use on Unix also. .o C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\indirectpythoninterface... The catalog only relies on code (for performance reasons) to determine whether recompiling is necessary. but I don’t know yet. structure or class deﬁnitions that you want to use in the code string.o up-to-date) writing C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\sc_86e98826b65b047ffd2cd5f479c6 c:\gcc-2. >>> .o up-to-date) skipping C:\home\ej\wrk\scipy\weave\CXX\cxx_extensions.length().force=1) Compiling code...[’a’]. you’ll need to alter code in some way or use the force argument to get the code to recompile.cxx (C:\DOCUME~1\eric\LOCALS~1\Temp\python21_compiled\temp\Release\cxxsupport.. 15 from weave import inline a = ’a longer string’ support_code = """ PyObject* length(Py::String a) { int l = a. skipping C:\home\ej\wrk\scipy\weave\CXX\cxxextensions. It allows you to specify extra code fragments such as function. .

PyInt_FromLong(3)).[’a’]) >>> a 2 The return_val variable can also be used to return newly created values. These info objects are the standard way of deﬁning compile information for type conversion classes. Release 0. the desired behavior would be something like: # THIS DOES NOT WORK >>> a = 1 >>> weave. set auto_downcast to 0. This is possible by returning a tuple. If you need to make changes to an immutable variable. Modiﬁcations to immutable types such as tuples. any changes made to c_a are not reﬂected in Python’s a variable. Thus.".0. If you want all values to keep there default type. The following trivial example illustrates how this can be done: 112 Chapter 1. Between these keywords. The type_factories variable is important to people who want to customize the way arguments are converted from Python to C. SciPy Tutorial . We’ll talk about this in the next chapter xx of this document when we discuss type conversions.inline("a++. For example.inline("PyList_SetItem(a. and numbers do not alter the Python variables. Changes made in C++ to the contents of mutable types are reﬂected in the Python variables. it will automatically downcast all scalar values from double to single precision when they are passed into the C++ code. This is not usually the desired behavior because it can double your memory usage. We’ll see if anyone cares to use it.ptr(). If you have an array of single precision values and multiply that array by a Python scalar.". This is the default behavior. I don’t think they are as handy here.inline("a++. any modiﬁcations to variables in the C++ code would be reﬂected in the Python variables when control was passed back to Python. the result is upcast to a double precision array because the scalar value is double precision.[’a’]) >>> a 1 Variables are passed into C++ as if you are calling a Python function.SciPy Reference Guide. Python’s calling convention is sometimes called “pass by assignment”. This means its as if a c_a = a assignment is made right before inline call is made and the c_a variable is used within the C++ code. strings. However. however. when looking at variables with mutable types.2] weave.10.0. a= [1.[’a’]) print a 2] So modiﬁcations to the contents of mutable types in C++ are seen when control is returned to Python.". Things do get a little more confusing. Returning Values Python variables in the local and global scope transfer seemlessly from Python into the C++ snippets. And.inline("return_val = Py::new_reference_to(Py::Int(a+1)). auto_downcast handles one of the big type conversion issues that is common when using NumPy arrays in conjunction with Python scalar values. If not. auto_downcast goes some distance towards changing the casting precedence of arrays and scalars. you’ll need to assign the new value to the “magic” variable return_val in C++. and the support_code option. I think customize may be obsolete. This value is returned by the inline() function: >>> a = 1 >>> a = weave. >>> >>> >>> [3. if inline were to completely live up to its name.dev6665 specify quite a bit of information about how a ﬁle is compiled. especially since we’ve exposed all the keyword arguments that distutils can handle.". it’ll get axed in the next version. If your only using single precision arrays.[’a’]) >>> a 2 Instead you get: >>> a = 1 >>> weave.

0. something so trivial has no reason to be written in C anyway. """ return inline_tools. PyObject* args) { py::object return_val. I don’t think we’ll get to the point of creating variables in Python for variables created in C – although I suppose with a C/C++ parser you could do that also. The cpp ﬁles are generally about 200-400 lines long and include quite a few functions to support type conversions. Can someone “in the know” conﬁrm or correct this? Another thing I’d like to know is whether there is a way to write to the local namespace of another stack frame from C/C++.inline(’printf("%d\\n". results[1] = "2nd". 1.[’a’]) 1 And here is the extension function generated by inline: static PyObject* compiled_func(PyObject*self. If so. PyObject *py_a. A quick look at the code weave generates a C++ ﬁle holding an extension function for each inline code snippet. as pointed out by the Python manual. results[0] = 1. I’m guessing local lookups don’t always look at a dictionary to ﬁnd values. Weave 113 . It extracts the variables that are used in the C++ code from these dictionaries. it would be possible to have some clean up code in compiled functions that wrote ﬁnal values of variables in C++ back to the correct Python stack frame. Of course. It seems like it would be trivial. However. PyObject *py__globals = NULL. Below is the familiar printf example: >>> import weave >>> a = 1 >>> weave.py. Release 0. and then calculates using them. the locals() dictionary is not writable.a).’. then. py_a = NULL. The C version here is about 7-10 times slower than the Python version. These ﬁle names are generated using from the md5 signature of the code snippet and saved to a location speciﬁed by the PYTHONCOMPILED environment variable (discussed later). return_val = results. I think this goes a long way toward making inline truely live up to its name. It also has the dubious honor of demonstrating how much inline() can slow things down. Unfortunately.10.SciPy Reference Guide. The issue with locals() inline passes the locals() and globals() dictionaries from Python into the C++ function from the calling function. I suspect locals() is not writable because there are some optimizations done to speed lookups of the local namespace. the actual compiled function is pretty simple. converts then to C++ variables.dev6665 # python version def multi_return(): return 1. etc.inline(code) The example is available in examples/tuple_return. PyObject *py__locals = NULL.13. after the calculations were ﬁnished to then insert the new values back into the locals() and globals() dictionaries so that the modiﬁed values were reﬂected in Python. def c_multi_return(): code = """ py::tuple results(2). int exception_occured = 0. ’2nd’ # C version.

sprintf(msg.disown()."_globals"). char* var_name) { char msg[500]. char* good_type.) { return_val = py::object(). } void handle_bad_type(PyObject* py_obj. throw Py::TypeError(msg).*/ } catch(."OO:compiled_func". py_to_int ﬁrst checks that the given PyObject* pointer is not NULL and is a Python integer. Otherwise.&py__locals.0. /*I would like to fill in changed locals and globals here.raw_globals). int a = convert_to_int(py_a. along with all inline code execution. 114 Chapter 1."_locals"). } Every inline function takes exactly two arguments – the local and global dictionaries for the current scope. an exception is raised. are done within a C++ try block. } /* cleanup code */ if(!(PyObject*)return_val && !exception_occured) { return_val = Py_None."received ’%s’ type instead of ’%s’ for variable ’%s’".raw_locals. if(PyInt_Check(py_obj)) return "int". it calls the Python API to convert the value to an int.a). The C++ exception is automatically converted to a Python exception by SCXX and returned to Python. } char* find_type(PyObject* py_obj) { if(py_obj == NULL) return "C NULL value". SciPy Tutorial .SciPy Reference Guide."int".. name). if(PyCallable_Check(py_obj)) return "callable". try { PyObject* raw_locals = py_to_raw_dict(py__locals. if(PyDict_Check(py_obj)) return "dict". All variable values are looked up out of these dictionaries. The py_to_int() function illustrates how the conversions and exception handling works..&py__globals)) return NULL.char* name) { if (!py_obj || !PyInt_Check(py_obj)) handle_bad_type(py_obj.good_type. if(PyFloat_Check(py_obj)) return "float". Release 0. The lookups. } return return_val. PyObject* raw_globals = py_to_raw_dict(py__globals.dev6665 if(!PyArg_ParseTuple(args."a"). find_type(py_obj).. return (int) PyInt_AsLong(py_obj). or there is an error converting a Python variable to the appropriate type in C++. if(PyString_Check(py_obj)) return "string". /* argument conversion code */ py_a = get_variable("a". /* inline code */ /* NDARRAY API VERSION 90907 */ printf("%d\n". If all is well.var_name). int py_to_int(PyObject* py_obj. If the variables aren’t found..10. it calls handle_bad_type() which gathers information about what went wrong and then raises a SCXX TypeError which returns to Python as a TypeError. exception_occured = 1.

Passing Variables in/out of the C/C++ code Note: Passing variables into the C code is pretty straight forward. if(PyFile_Check(py_obj)) return "file". Type conversions are customizable by the user if needed.10. Item 2 is covered later in the chapter covering the ext_tools module. see Returning Values for a more thorough discussion of this issue. } Since the inline is also executed within the try/catch block. It is usually a bad idea to directly return from your code. //should probably do more interagation (and thinking) on these. Some customizations were needed.SciPy Reference Guide. Technical Details There are several main steps to using C/C++ code withing Python: 1. but in more complicated examples.0. Might change in future version? By default. if(PyInstance_Check(py_obj)) return "instance". This skips the clean up section of the extension function. Type conversion 2.dev6665 if(PyList_Check(py_obj)) return "list". In this simple example. if(PyModule_Check(py_obj)) return "module". compiling the code is handled by distutils. Weave 115 . there may be some reference counting that needs to be taken care of here on converted variables. either uses exceptions or set return_val to NULL and use if/then’s to skip code after errors. Compile the code to an extension module 4. there isn’t any clean up code. Generating C/C++ code 3. To avoid this. Generating the C/C++ code is handled by ext_function and ext_module classes and . but there are subtlties to how variable modiﬁcations in C are returned to Python. even if an error occurs. 1. and distutils is covered by a completely separate document xxx. Catalog (and cache) the function for future use Items 1 and 2 above are related. you can use CXX exceptions within your code. return "unkown type". but surprisingly required the most code to implement (and still likely needs some work). So. Cataloging is pretty simple in concept. but they were relatively minor and do not require changes to distutils itself. if(PyCallable_Check(py_obj) && PyInstance_Check(py_obj)) return "callable". but most easily discussed separately.13. Type Conversions Note: Maybe xxx_converter instead of xxx_specification is a more descriptive name. this section covers items 1 and 4 from the list. For the most part. if(PyCallable_Check(py_obj)) return "callable". Release 0. Understanding them is pretty important for anything beyond trivial uses of inline. inline() makes the following type conversions between Python and C++ types. if(PyTuple_Check(py_obj)) return "tuple".

Consider the following inline function that has a single integer variable passed in: >>> a = 1 >>> inline("". the ﬂoat and complex conversion routines look like: 116 Chapter 1.0. Below is the basic template for the function. SciPy Tutorial . If you see an issue.char* name) { if (!py_obj || !PyInt_Check(py_obj)) handle_bad_type(py_obj. } Similarly.ndarray wxXXX C++ int double std::complex py::string py::list py::dict py::tuple FILE* py::object py::object PyArrayObject* wxXXX* The Py:: namespace is deﬁned by the SCXX library which has C++ class equivalents for many Python types. This is actually the exact code that is generated by calling weave. The following sections demostrate how these two areas are ﬁlled in by the default conversion methods. std:: is the namespace of the standard library in C++.raw_globals). please let me know. and complex arguments are handled in a very similar fashion. * Note: I’m not sure I have reference counting correct on a few of these.10.[’a’]) The argument conversion code inserted for a is: /* argument conversion code */ int a = py_to_int (get_variable("a".check this). name)."int". Release 0. The /*argument convserion code*/ and /* cleanup code */ sections are ﬁlled with code that handles conversion from Python to C++ types and code that deallocates memory or manipulates reference counts before the function returns. The /* inline code */ section is ﬁlled with the code passed to the inline() function call."a"). get_variable() reads the variable a from the local and global namespaces.dev6665 Table 1. py_to_int() has the following form: static int py_to_int(PyObject* py_obj.3: Default Data Type Conversions Python int ﬂoat complex string list dict tuple ﬁle callable instance numpy. Note: • I haven’t ﬁgured out how to handle long int yet (I think they are currenlty converted to int . The only thing I increase/decrease the ref count on is NumPy arrays. ﬂoating point. return (int) PyInt_AsLong(py_obj).raw_locals.. NumPy Argument Conversion Integer.inline(""). • Hopefully VTK will be added to the list soon Python to C++ conversions ﬁll in code in several locations in the generated inline extension function.SciPy Reference Guide.

char* name) { if (!py_obj || !PyDict_Check(py_obj)) handle_bad_type(py_obj.dev6665 static double py_to_float(PyObject* py_obj."float". name)."string". py_to_list() and its friends has the following form: static Py::List py_to_list(PyObject* py_obj. For the following code. name).raw_locals. } 1. Lists. >>> a = [1] >>> inline("". return Py::Dict(py_obj). return Py::String(py_obj).13. name). List. Tuple. } static Py::String py_to_string(PyObject* py_obj."list".char* name) { if (!PyString_Check(py_obj)) handle_bad_type(py_obj.10. get_variable() reads the variable a from the local and global namespaces. return Py::Tuple(py_obj). return Py::List(py_obj). PyComplex_ImagAsDouble(py_obj))."tuple".char* name) { if (!py_obj || !PyTuple_Check(py_obj)) handle_bad_type(py_obj. name). } NumPy conversions do not require any clean up code. Tuples and Dictionary conversions are all converted to SCXX types by default.raw_globals).char* name) { if (!py_obj || !PyComplex_Check(py_obj)) handle_bad_type(py_obj. } static Py::Dict py_to_dict(PyObject* py_obj. } static std::complex py_to_complex(PyObject* py_obj. String. } static Py::Tuple py_to_tuple(PyObject* py_obj. return std::complex(PyComplex_RealAsDouble(py_obj).char* name) { if (!py_obj || !PyFloat_Check(py_obj)) handle_bad_type(py_obj.SciPy Reference Guide. and Dictionary Conversion Strings. name). Weave 117 . Release 0."complex".0.[’a’]) The argument conversion code inserted for a is: /* argument conversion code */ Py::List a = py_to_list(get_variable("a".char* name) { if (!py_obj || !PyList_Check(py_obj)) handle_bad_type(py_obj. name)."a"). return PyFloat_AsDouble(py_obj)."dict".

’.inline(’fprintf(buf. in initial printf() examples..’. char* name) { if (!py_obj || !PyFile_Check(py_obj)) handle_bad_type(py_obj. } Because the PyObject* was incremented.stdout >>> weave. the following occurs: >>> buf = sys.stdout to a special object that implements the Python ﬁle interface.10.’) You might try: >>> buf = sys. lists. Its important to understand that ﬁle conversion only works on actual ﬁles – i. Why is this? Let’s look at what the buf object really is: >>> buf pywin. Release 0. name). etc.dev6665 SCXX handles reference counts on for strings.SciPy Reference Guide. but since the special object doesn’t have a FILE* pointer underlying it.inline(’printf("hello\\n"). >>> a = open("bob". get_variable() reads the variable a from the local and global namespaces. and dictionaries. For example. For example.. PyCrust.stderr.’w’) >>> inline("". so clean up code isn’t necessary. It does not support converting arbitrary objects that support the ﬁle interface into C FILE* pointers. py_to_file() converts PyObject* to a FILE* and increments the reference count of the PyObject*: FILE* py_to_file(PyObject* py_obj.framework. fprintf doesn’t know what to do with it (well this will be the problem when instance conversion is implemented. the clean up code needs to decrement the counter /* cleanup code */ Py_XDECREF(py_a)."a")."file".stdout and sys.raw_globals).interact. This works great in Python. but in PythonWin.).raw_locals. FILE* a = py_to_file(py_a. return PyFile_AsFile(py_obj). the error would have occurred at runtime instead). Py_INCREF(py_obj)."hello\\n").[’buf’]) The traceback tells us that inline() was unable to convert ‘buf’ to a C++ type (If instance conversion was implemented. SciPy Tutorial .[’buf’]) This will work as expected from a standard python interpreter. 118 Chapter 1.) writing to different stdout and stderr by using fprintf() and passing in sys. File Conversion For the following code. one might be tempted to solve the problem of C and Python IDE’s (PythonWin.stdout >>> weave.InteractiveView instance at 00EAD014 PythonWin has reassigned sys.[’a’]) The argument conversion code is: /* argument conversion code */ PyObject* py_a = get_variable("a"."hello\\n").e.0. tuples. This can affect many things.inline(’fprintf(buf. instead of >>> weave. ones created using the open() command in Python.

13. Instance. and support code information necessary for including a certain set of capabilities (such as blitz++ or CXX support) in a compiled module. Release 0. return py_obj. A lot of times you may just want to change how a speciﬁc variable type is represented. Closely related to the xxx_specification classes are yyy_info classes. /* argument conversion code */ PyObject* a = py_to_callable(get_variable("a". After deﬁning speciﬁcation classes. >>> def a(): pass >>> inline("".dev6665 Callable. The second is as a code generator that generate C++ code needed to convert from Python to C++ types for a speciﬁc variable. return py_obj. char* name) { if (!py_obj || !PyFile_Check(py_obj)) handle_bad_type(py_obj. but would like all other type conversions to have default behavior. The py_to_callable() and py_to_instance() don’t currently increment the ref count. get_variable() reads the variable a from the local and global namespaces. If you’d like to deﬁne your own set of type speciﬁcations.raw_locals. the code snippet has to be compiled. Maybe looking over sequence_spec. or instances. A type speciﬁcation class actually serve in two related but different roles.py). Say you’d rather have Python strings converted to std::string or maybe char* instead of using the CXX string object.[’a’]) is called for the ﬁrst time.inline(’printf("%d". The ﬁrst is in determining whether a Python variable that needs to be converted should be represented by the given class. name). } There is no cleanup code for callables."callable".’. Instance and Module conversion are not currently implemented.a). This requires that a new speciﬁcation class that handles strings is written 1. Weave 119 . } PyObject* py_to_instance(PyObject* py_obj. These classes contain compiler. Customizing Conversions Converting from Python to C++ types is handled by xxx_speciﬁcation classes. PyObject* py_to_callable(PyObject* py_obj. name).py” ﬁles in the weave package.0.SciPy Reference Guide. xxx_specification classes have one or more yyy_info classes associated with them.py are a good place to start. you’ll need to pass them into inline using the type_factories argument.py and cxx_info.10. Nothing is done to there reference counts. In this process. char* name) { if (!py_obj || !PyCallable_Check(py_obj)) handle_bad_type(py_obj. When >>> a = 1 >>> weave."instance". and Module Conversion Note: Need to look into how ref counts should be handled.[’a’]) Callable and instance variables are converted to PyObject*. the variable ‘a’ is tested against a list of type speciﬁcations (the default list is stored in weave/ext_tools. Also. Examples of xxx_specification are scattered throughout numerous “xxx_spec."a"). modules. The ﬁrst speciﬁcation in the list is used to represent the variable.raw_globals). the current best route is to examine some of the existing spec and info ﬁles. header.

for any reason it isn’t. If cpp_code has ever been called. it effectively overrides the default string speciﬁcation. If. If none of the functions work. the catalog looks through the on-disk function catalogs for the entries. Look at the examples/md5_speed. A fast local cache of functions is checked for the last function called for cpp_code. 2. If PYTHONCOMPILED is not present several platform dependent locations are searched. When a lookup for cpp_code fails.0. SciPy Tutorial . Along 120 Chapter 1. I think this is because it is more time consuming to compute the md5 value than it is to do look-ups of long strings in the dictionary. On Windows. By saving information about compiled functions to disk. All functions found for cpp_code in the path are loaded into the in-memory cache with functions found earlier in the search path closer to the front of the call list. On disk catalogs are stored in the same manor using standard Python shelves. a directory called pythonXX_compiled is created in the user’s temporary directory. written to the ﬁrst writable directory in the PYTHONCOMPILED path. This prevents inline() and related functions from having to compile functions everytime they are called. If the cache isn’t present. The catalog class also keeps an in-memory cache with a list of all the functions compiled for cpp_code. then the function is compiled. there was a question as to whether md5 check sums of the C++ code strings should be used instead of the actual code strings. The PYTHONCOMPILED variable determines where to search for these catalogs and in what order. then it starts searching through persisent catalogs on disk to see if it ﬁnds an entry for the given function. The directory permissions are set so that only you have access to the directory. 3. Catalog search paths and the PYTHONCOMPILED variable The default location for catalog ﬁles on Unix is is ~/. the entire string showed that using the entire string was at least a factor of 3 or 4 faster for Python. The Catalog catalog.10. then this cache will be present (loaded from disk). If this directory doesn’t exist. Since it is closer to the front of the list. it is created the ﬁrst time a catalog is used. The directory must be writable. each function in the cache is called until one is found that was compiled for the correct argument types.py has a class called catalog that helps keep track of previously compiled functions. catalog will check an in memory cache to see if the function has already been loaded into python. The actual catalog ﬁle that lives in this directory is a Python shelve with a platform speciﬁc name such as “nt21compiled_catalog” so that multiple OSes can share the same ﬁle systems without trampling on each other. Release 0. If the cache is present.dev6665 and then prepended to a list of the default type speciﬁcations. Early on. Some (admittedly quick) tests of the md5 vs. If it hasn’t. it isn’t necessary to re-compile functions everytime you stop and restart the interpreter. If the function isn’t found in the on-disk catalog.SciPy Reference Guide.. a new function is compiled with the given argument types.pythonXX_compiled where XX is version of Python being used. If an entry for cpp_code doesn’t exist in the cache or the cached function call fails (perhaps because the function doesn’t have compatible types) then the next step is to check the catalog. Instead. and also loaded into the in-memory cache. When inline(cpp_code) is called the following things happen: 1. Function Storage Function caches are stored as dictionaries where the key is the entire C++ code string and the value is either a single function (as in the “level 1” cache) or a list of functions (as in the main catalog cache). then the catalog attempts to create a directory based on your user id in the /tmp directory. The following code demonstrates how this is done: . I think this is the route inline Perl took. If this fails. I think you’re out of luck.py ﬁle for the test run. Functions are compiled once and stored for future use.. I don’t think either of these should ever fail though. then it is loaded from disk. This function is written to the on-disk catalog as well as into the in-memory cache.

but compiled for different input variables.so or . the following code fragment takes a 5 point average of the 512x512 2d image.inline_tools reduces the overhead of calling inline functions by about a factor of 2. Weave 121 .cpp and . a: from scipy import * # or from NumPy import * a = ones((512.. Release 0. weave.1:-1] + b[2:.10. and stores it in array. You can use the PYTHONCOMPILED environment variable to specify alternative locations for compiled functions. So. It speciﬁes that the compiled catalog should reside in the same directory as the module that called it. The function lists point at functions within these compiled modules.export PYTHONCOMPILED. 1. the ﬁrst writable directory in the list is where all new compiled function catalogs.’) separated list of directories.pyd ﬁles created by inline will live in this directory. it is a (‘. b. Float64) # .1:-1] + b[:-2.directory such as /usr/lib/python21/sitepackages/python21_compiled/linuxpython_compiled so that library ﬁles compiled with python21 are tried to link with python22 ﬁles in some strange scenarios. however. This is useful if an admin wants to build a lot of compiled functions during the build of a package and then install them in site-packages along with the package. Each function in the lists executes the same C++ code string... the new function will be stored in their default directory (or some other writable directory in the PYTHONCOMPILED path) because the user will not have write access to the site-packages directory. The in-module cache (in weave.pyd ﬁles are written. An example of using the PYTHONCOMPILED path on bash follows: PYTHONCOMPILED=MODULE:/some/path.8 Blitz Note: most of this section is lifted from old documentation.cpp and . On Unix this is a colon (‘:’) separated list of directories. Relative directory paths (‘..512). It can be reduced a little more for type loop calls where the same function is called over and over again if the cache was a single value instead of a dictionary. I should probably make a sub.’ and ‘. As an example.so or . 1. If you are using python21 on linux. Note. we’ll stick with a dictionary as the cache. Also.dev6665 with the catalog ﬁle. see a possible problem here. compiled expressions should provide a factor of 2-10 speed-up over NumPy arrays. There is a “special” path variable called MODULE that can be placed in the PYTHONCOMPILED variable. and the module bob.1:-1] \ + b[1:-1.blitz() compiles NumPy Python expressions for fast execution.py in site-packages has a compiled function in it. It should be pretty accurate.512).SciPy Reference Guide. but there may be a few discrepancies. Using compiled expressions is meant to be as unobtrusive as possible and works much like pythons exec statement.:-2]) / 5. Float64) b = ones((512. but the beneﬁt is very small (less than 5%) and the utility is quite a bit less. User’s who specify MODULE in their PYTHONCOMPILED variable will have access to these compiled functions. the . For most applications. Need to check this.1:-1] = (b[1:-1.do some stuff to fill in b.. Note: hmmm. # now average a[1:-1.’) should work ﬁne in the PYTHONCOMPILED variable as should environement variables.0. that if they call the function with a set of argument types that it hasn’t previously been built for. .13. then the catalog search order when calling that function for the ﬁrst time in a python session would be: /usr/lib/python21/site-packages/linuxpython_compiled /some/path/linuxpython_compiled ~/. On windows.2:] + b[1:-1.python21_compiled/linuxpython_compiled The default location is always included in the search path. These directories will be searched prior to the default directory for a compiled function catalog. The catalog ﬁle simply contains keys which are the C++ code strings with values that are lists of functions.13.

dev6665 To compile the expression. Future versions will allow the following: >>> result = weave.0. convert the expression to a string by putting quotes around it and then use weave. Futher.2.blitz. A number of other compilers such as KAI++ will also work. Currently Python only works on expressions that include assignment such as >>> result = b + c + d This means that the result array must exist before calling weave. This does not overwrite the previously compiled function – both of them are saved and available for exectution.46349 blitz (1st time compiling) 78. Particularly MSVC++ isn’t up to snuff. Because of the slow compile times.blitz. weave. Currently. and fabs functions might work (but haven’t been tested).blitz(expr) The ﬁrst time weave. the code most be compiled again. Note that there are no obvious reasons why most of this functionality cannot be added to scipy.1:-1] = (b[1:-1.blitz handles all standard mathematic operators except for the ** power operator.:-2]) / 5. The built-in trigonmetric. This provides the standard rapid prototyping strengths of Python and results in algorithms that run close to that of hand coded C or Fortran. This can take up to a couple of minutes depending on the complexity of the function.blitz has only been tested under Linux with gcc-2. It also handles all types of array indexing supported by the NumPy module. but numarray’s enhanced (array based) indexing modes are not supported.blitz works best when algorithms can be expressed in a “vectorized” form. Method Run Time (seconds) Standard NumPy 0. log. weave. put quotes around it and execute it using weave. Using slice() objects directly instead of start:stop:step is also not supported. but my suspicions are that gcc will get the most use. weave.1:-1] + b[:-2.blitz_eval("b + c + d") 3. Its compiler requirements are pretty heavy duty (see the blitz++ home page). etc. If the given expression is executed with a new set of array types. the generated module is saved between program executions so that the compilation is only done once for a given expression and associated set of array types. Requirements Currently. been implemented. so it will likely trickle into future versions. numarray’s NumPy compatible array indexing modes are likewise supported. Release 0. Further. Subsequent calls to the function are very fast. the weave.2). so it won’t work with just any compiler.95. C++ code that accomplishes the exact same task as the Python expression is generated and compiled to an extension module. the restrictions 122 Chapter 1.SciPy Reference Guide.10.95-3 and on Windows with Mingw32 (2. its probably most effective to develop algorithms as you usually do using the capabilities of scipy or the NumPy module. Once the algorithm is perfected.95526 blitz (subsequent calls) 0.blitz does not currently support operations that use array broadcasting.blitz is run for a given expression and set of arguements.1:-1] + b[2:. compress.1:-1]" \ "+ b[1:-1.2:] + b[1:-1." weave.blitz: import weave expr = "a[1:-1. ﬂoor/ceil. Limitations 1. The following table compares the run times for standard NumPy code and compiled code for the 5 point averaging. nor have any of the special purpose functions in NumPy such as take. SciPy Tutorial .weave.05843 (factor of 8 speedup) These numbers are for a 512x512 double precision image run on a 400 MHz Celeron processor under RedHat Linux 6. 2. Algorithms that have a large number of if/thens and other conditions are better hand written in C or Fortran.

.. 0. 100.. 100. 10. 0. 1. Here is an example.10..]. 0.dev6665 imposed by requiring vectorized expressions sometimes preclude the use of more efﬁcient data structures or algorithms.. [ 0.25 [ 0.8125 . 0.."\ . does a “running” calculation of the array elements assigning values from the right hand side to the elements on the left hand side immediately after they are calculated. where this happens: # 4 point average. 100.].:] = 100 >>> temp = zeros((4. hand-coded C or Fortran code is the only way to go. .:] = 100 >>> exec (expr) >>> u array([[ 100. 5). . ’d’).. >>> u = zeros((5. 0. [ 0.. 1:-1] + \ .734375 [ 0. This focused scope concentrates effort on the compuationally intensive regions of the program and sidesteps the difﬁcult issues associated with a general purpose Python->C compiler.. 31. 25. 9. 25. 0.3203125... ]. 1:-1] + "\ . [ 0.5625 . 100.0:-2] + u[1:-1. 0.. NumPy efﬁciency issues: What compilation buys you Some might wonder why compiling NumPy expressions to C++ is beneﬁcial since operations on NumPy array operations are already executed within C loops. ’d’). 0. >>> expr = "u[1:-1. 5). 5)..]]) 5.25 .. ’d’). 0.. 0. The problem is that anything other than the simplest expression are executed in less than optimal fashion. >>> expr = "temp = (u[0:-2.. ].0:-2] + u[1:-1.. ]. 2. 0.blitz (expr) >>> u array([[ 100. 0.].blitz can produce different results than NumPy in certain situations. 4.. . 0. 0. [ 0. . .13. 0. "u[1:-1. 6.:] = 100 >>> weave. weave.546875 . . [ 0. u[0.]. 0. For maximum speed in these cases. on the other hand. 0. 25. 0. . 25.. ]. 25. 100.. 100.].SciPy Reference Guide.. 0. 0. 100. 0. 0.blitz (expr) >>> u array([[ 100. ’d’).25. 100. 100. 2:])*0.]... The NumPy behavior is to carry out the entire calculation on the right hand side of an equation and store it in a temporary array... 1:-1] = (u[0:-2. "u[1:-1.. Consider the following NumPy expression: 1. provided by Prabhu Ramachandran.]. 0.. 0... u[0. 0. 2:])*0.. 100. 0..0.. 0. u[0. ]]) You can prevent this behavior by using a temporary array. . 1:-1] + u[2:. blitz. [ 0. .. . 0. weave.. 1:-1] + u[2:. 0. 3. 0. 25. One other point deserves mention lest people be confused... [ 0. 25. 100. .. 100...]]) >>> u = zeros((5.. . 4). It only works for expressions that contain NumPy arrays and/or Python scalar values. "u[1:-1. 32. 0.].. [ 0.. Weave 123 .25" >>> u = zeros((5. This temprorary array is assigned to the array on the left hand side of the equation... 0.. [ 0.. It can happen when the array receiving the results of a calculation is also used during the calculation.1:-1] = temp" >>> weave. Release 0.blitz is not a general purpose Python->C compiler. . .. 0.375 [ 0.

suite("a = b * c + d") >>> ast_list = ast.2 * b[i. 124 Chapter 1.SciPy Reference Guide. [’simple_stmt’.dev6665 a = 1. Parser Tearing NumPy expressions apart. i++) for(int j = 0. because it’s C++. but it’d likely be ugly and fragile. >>> import parser >>> import scipy. there are several available tools that simplify the process. (take a peak in NumPy for conﬁrmation). Blitz++ uses a jaw dropping array of template techniques (metaprogramming. The second thing is that we have 3 loops executing. Python solves this problem for us. i < M. it does the following steps: temp1 = 1. Release 0.translate_symbols(ast_list) >>> pprint. etc) to convert innocent looking and readable C++ expressions into to code that usually executes within a few percentage points of Fortran code for the same problem. and then rebuilding them as C++ (blitz) expressions requires a parser of some sort. SciPy Tutorial .2 * b. converting NumPy expressions into C/C++ loops that fuse the loops and eliminate temporary arrays can provide big gains. it’s much slower than C or Fortran. Luckily. [’small_stmt’. the 3 loops have been fused into a single loop and there is no longer a need for a temporary array. The same is true for temp2. compile them in an extension module.weave.2 * b + c * d When NumPy calculates the value for the 2d array. template expression. So. I can imagine someone attacking this problem with regular expressions.j] = 1. j < N.j] Here. The bad news is that NumPy is generally much more powerful than this simple example illustrates and handling all possible indexing possibilities results in loops that are less than straight forward to write. written in C++ (shhhh. Don’t assume that. On the Python side. This provides a signiﬁcant speed improvement over the above example (write me and tell me what you get). The good news is that there is an obvious correspondence between the NumPy expression above and the C loop.j] * d[i. one for temp2 and one for adding them up. Todd Veldhuizen’s blitz++ array library. weave. Unfortunately all the template raz-ma-taz is very expensive to compile.misc >>> ast = parser. so the 200 line extension modules often take 2 or more minutes to compile. It actually exposes its parsing engine to the world through the parser module. examining the pieces.misc. The Tools weave.2 * b temp2 = c * d a = temp1 + temp2 Two things to note.weave. does the heavy lifting. don’t tell David Beazley). This isn’t so good. The goal then. one to calculate temp1.is to convert NumPy expression to C/C++ loops. Since c is an (perhaps large) array. and then call the compiled extension function. On the compiled language side. a. Allocation is slow. This is good.j] + c[i. the main facilitators are Jermey Hylton’s parser module and Travis Oliphant’s NumPy module. The following fragment creates an Abstract Syntax Tree (AST) object for the expression and then converts to a (rather unpleasant looking) deeply nested list representation of the tree. [’stmt’. Amazingly.0. a large temporary array must be created to store the results of 1.10.blitz relies heavily on several remarkable tools.blitz works to minimize this issue by remembering where compiled modules live and reusing them instead of re-compiling every time a program is re-run. A C loop for the same problem might look like: for(int i = 0. j++) a[i.pprint(sym_list) [’file_input’.tolist() >>> sym_list = scipy.

Blitz and NumPy The other nice discovery in the project is that the data structure used for NumPy arrays and blitz arrays is nearly identical. [’expr’. [’power’. NumPy stores “strides” as byte offsets and blitz stores them as element offsets. Further. 1.13.4] In Blitz it is as follows: Array<2. ’b’]]]]. [’factor’.3.2)) + c.. [’EQUAL’. ’d’]]]]]]]]]]]]]]]]].int> a = b(Range(0.. [’and_expr’. but other than that. ’’]]].dev6665 [’expr_stmt’. [’testlist’. writing out the terminal symbols as you go. ’’]] [’atom’. [’xor_expr’. and then re-insert it in the parse tree. [’STAR’. ’+’]. [’term’. its possible to search these trees for speciﬁc patterns (subtrees). [’and_expr’. The parser module documentation has some details on how to do this. [’comparison’. [’atom’. [’comparison’. manipulate them converting python speciﬁc code fragments to blitz code fragments. [’factor’. [’testlist’.. Weave 125 . [’shift_expr’. [’atom’. with some tools developed by Jermey H. ’c’]]]]]. Despite its looks. It is also fortuitous. [’arith_expr’. [’xor_expr’. ’*’]. [’and_test’. most of the concept and capabilities of the two libraries are remarkably similar. Array<2.10. // . [’shift_expr’. extract the sub-tree. [’arith_expr’. [’NEWLINE’. consider the code for slicing an array in Python with a stride: >>> a = b[0:4:2] + c >>> a [0. [’NAME’. The work involved in converting NumPy expressions to blitz expressions was greatly diminished. [’NAME’. [’factor’.int> b(10). [’atom’.int> c(3). Traversing the new blitziﬁed tree. ’=’]. [’not_test’. [’not_test’. [’term’. [’expr’. [’factor’. they are the same. As an example. [’NAME’. [’ENDMARKER’. [’term’. [’test’. It is satisfying that two completely different implementations solved the problem with similar basic architectures.0.2. [’power’. [’power’. [’power’. [’test’. ’a’]]]]]]]]]]]]]]]. [’NAME’. [’and_test’. creates our new blitz++ expression string.SciPy Reference Guide. [’PLUS’. Release 0. Array<2.

While it needs ﬁxin’. In the following scenario.dev6665 Here the range object works exactly like Python slice objects with the exception that the top index (3) is inclusive where as Python’s (4) is exclusive.cases. when the top index is calculated from other values. This is likely very easy.:] = b[2:3.z) and re-inserted into the tree. static typing issue between Python and C++. C/C++.SciPy Reference Guide. a[i+j:i+j+1. converted to slice(x. A good rule of thumb is don’t use values that start with ‘_’ or ‘py_’ in compiled expressions and you’ll be ﬁne. all x:y:z slicing expression are removed from the AST.) are also preformed here.slice(_beg.:] becomes a more verbose: a[slice(i+j.blitz handles this issue by examining the types of the variables in the expression being executed. But the string replacement is slightly easier. Right now. It calculates and index that starts with a ‘-‘ sign by subtracting it from the maximum index in the array so that: upper index limit /-----\ b[:-1] -> b(Range(0._end)] = b[slice(2._end)] The second part does a simple string search/replace to convert to a blitz expression with the following translations: slice(_beg. is to write a PyRange class that behaves like Python’s range. Other differences include the type declaraions in C++ and parentheses instead of brackets for indexing arrays. etc.3). but cuts down on code.Nb[0]-1-1)) This approach fails. SciPy Tutorial . Currently no effort is made to detect name clashes. the compiled code will produce incorrect results and could even core. and compiling a function for those explicit types. The actual translation of the Python expressions to blitz expressions is currently a two part process.0. weave. Any math needed on these expressions (subtracting from the maximum index. In Python. so it hasn’t been done. however. An alternative that is likely more robust/maintainable in the long run. blitz::Range ( ) 1 _all is deﬁned in the compiled function as blitz::Range. The current implementation of the blitz() has a partial solution to this problem._end) slice [ ] _stp -> -> -> -> -> _all # not strictly needed. The stock blitz also doesn’t handle negative indices in ranges.10. Currently.i+j+1).dump. weave.all(). Type deﬁnitions and coersion So far we’ve glossed over the dynamic vs. I don’t think there is a ton of code where this is an issue.blitz handles the inclusive/exclusive issue by subtracting one from upper indices during the translation. These translations could of course happen directly in the syntax tree. if i+j evaluates to a negative value. First.slice(_beg. but haven’t looked into how much effort is involved yet. This is a little work and results in more code.y. I’m holding out to see if blitz++ can be modiﬁed to handle negative indexing. Note that name spaces are maintained in the C++ code to lessen the likelyhood of name clashes. For example: 126 Chapter 1. on the other hand. b[:i-j] -> b(Range(0. all calculated indices are assumed to be positive. forces you to declare the type of value a variables will hold prior at compile time. the type of value that a variable holds can change through the course of program execution. _beg and _end are used as special variables that are deﬁned as blitz::fromBegin and blitz::toEnd.i+j)) A solution is to calculate all indices up front using if/then to handle the +/. Release 0.

One other point of note. This is possible because NumPy treats each operation independently.blitz("b = a * 2. Currently.0.:] + c are not so trivial. the array being assigned to must be created prior to calling weave.10.Float32) >>> b = ones((5. and c have the same shape.Float32) weave. the size of the slices.inline() documentation.dev6665 a = ones((5.5). In this example. it compiles the function using the ﬂoat type (no attempt has been made to deal with 64 bit issues). not the input arrays must be checked. The following case is trivially easy: a = b + c It only requires that arrays a. This prevents issues with the following expression perhaps unexpectedly being calculated at a higher (more expensive) precision that can occur in Python: >>> a = array((1. As a result.1") the 2. When working with combined scalar/array operations. This is similar to the savespace ﬂag that was recently added to NumPy.blitz("a = a + b") When compiling this expression to C++. The binary operators in NumPy compare the shapes of their two operands just before they operate on them. you’ll just have to wait on it to compile a new version for your new types. Release 0. I’m pretty sure this is easily changed so that a compiled_eval expression can be deﬁned. If you really want to force the calculation to be a double. Weave 127 .blitz.3). Reductions have a similar effect as their results are different shapes than their input operand. but no effort has been made to allocate new arrays (and decern their type) on the ﬂy. >>> a = ones((5.1 # results in b being a Float64 array. Since slicing is involved. weave.Float32) >>> weave. See the catalog section in the inline() documentation to see how this is handled.Float32) b = ones((5. Cataloging Compiled Functions See The Catalog section in the weave. or ‘ﬂoat’ on a 32 bit architecture. as they are still accessible.2. b. Also. This doesn’t overwrite the old functions.1 is cast down to a float before carrying out the operation. The intermediate (temporary) arrays created during sub-operations in an expression are tested for the correct shape before they are 1.typecode = Float32) >>> b = a * 2.5).SciPy Reference Guide. Checking Array Sizes Surprisingly. the mechanism is transparent to the user and behaves like dynamic typing with the occasional wait for compiling newly typed functions. What happens if you call a compiled function with array types that are different than the ones for which it was originally compiled? No biggie.:] = b[2:3. one of the big initial problems with compiled code was making sure all the arrays in an operation were of compatible type. However. Broadcasting complicates things further because arrays and slices with different dimensions and shapes may be compatible for math operations (broadcasting isn’t yet supported by weave.5).blitz). Sufﬁce to say.blitz sees that the values for a and b in the local scope have type Float32. you must include both the right hand side and left hand side (assignment side) of your equation in the compiled expression. expressions like: a[i+j:i+j+1. deﬁne a and b as double arrays.13.5). the type of the array is always used.

py from weave import ext_tools def build_increment_ext(): """ Build a simple extension with functions that increment numbers. So.blitz to be slower than evaluating the expression in Python. For large arrays (ie. if the sizes aren’t compatible. 128 Chapter 1.dev6665 combined by another operation. this isn’t possible. The shape comparisons must be done and guaranteed compatible before evaluating the expression.9 Extension Modules weave. it can cause a core-dump.ext_tools. Binary operations on dummy arrays check that input array sizes are comptible and return a dummy array with the size correct size. not the data. the local and global dicts. A Simple Example The following simple example demonstrates how to build an extension module within a Python function: # examples/increment_example. SciPy Tutorial .ext_tools to help generate the extension module. 50x50x50).SciPy Reference Guide.size_check. These classes simplify the process of generating extension modules by handling most of the “boiler plate” code automatically. foregoing size_checking isn’t advisable until your code is well debugged. For small arrays (ie.13.ext_module(’increment_ext’) a = 1 # effectively a type declaration for ’a’ in the # following functions.inline to build the extension module. Under the covers. The solution chosen converts input arrays to “dummy arrays” that only represent the dimensions of the arrays. they use several classes from weave.blitz uses the same machinery as weave. Creating the Extension Module weave. but no effort has been made to do this.blitz are high level tools that generate extension modules automatically. It basically involves writing a new class (dummy array) and overloading it math operators to calculate the new sizes correctly. while inline always has two arguments.blitz with check_size=0 and the size checking isn’t done. the overhead imposed for checking the shapes with this method can cause the weave. The extension will be built in the local directory. Because weave. Evaluating an expression of dummy arrays traces the changing array sizes through all operations and fails if incompatible array sizes are ever found. However. The only difference is the code included in the function is automatically generated from the NumPy array expression instead of supplied by the user. This would likely remove most of the overhead penalty compared to NumPy (although there is also some calling overhead). 16x16). Release 0. and the grabs the variables that need to be convereted to C from these. """ mod = ext_tools. What can be done to reduce the overhead? (1) The size checking code could be moved into C. The main two classes are ext_module and ext_function (I’d like to add ext_class and ext_method also).blitz fuses all operations into a single loop.0. Note: inline actually sub-classes weave. 1. (2) You can also call weave.ext_function to generate slightly different code than the standard ext_function. All the code is in Python and there is a fair amount of logic (mainly to handle indexing and slicing) so the operation does impose some overhead. the overhead is negligible compared to evaluating the actual expression. The machinery for this is housed in weave. The main difference is that the standard class converts function arguments to C types.10.inline and weave.

increment_by_2(a) Note: If we were willing to always pay the penalty of building the C++ code for a module.13. a.ext_code. ext_module." func = ext_tools.SciPy Reference Guide.compile() The function build_increment_ext() creates an extension module named increment_ext and compiles it to a shared library (.[’a’]) creates a C/C++ extension function that is equivalent to the following Python function: def increment(a): return a + 1 func = A second method is also added to the module and then. Release 0. if __name__ == "__main__": try: import increment_ext except ImportError: build_increment_ext() import increment_ext a = 1 print ’a. increment_ext. The following ext_code = “return_val = Py::new_reference_to(Py::Int(a+1)).. etc. a.ext_module(‘increment_ext’) creates an ext_module instance that is ready to have ext_function instances added to it. increment and increment_by_2.compile() is called to build the extension module." func = ext_tools. the module is created in the current working directory.10.pyd) that can be loaded into Python. The ﬁrst line of build_increment_ext().add_function(func) mod. increment_ext. This example is available in the examples/increment_example.dev6665 ext_code = "return_val = Py::new_reference_to(Py::Int(a+1)). Then. Weave 129 .inline().ext_function(’increment_by_2’.increment(a) print ’a. At the bottom of the ﬁle in the module’s “main” program. the module is built by calling build_increment_ext().ext_function(‘increment’.py ﬁle found in the weave directory. The most common call includes a C/C++ code snippet and a list of the arguments for the function. This approach only takes the time consuming ( a few seconds for this example) process of building the module if it hasn’t been built before. ext_function instances are created much with a calling convention similar to weave.add_function(func) ext_code = "return_val = Py::new_reference_to(Py::Int(a+2)).ext_code.[’a’]) mod. By default. a+2:’.ext_code. If this fails (the module doesn’t exist in the PYTHONPATH). a+1:’. increment_ext contains two functions. we could store the md5 checksum of the C++ code along with some information about the compiler. an attempt to import increment_ext without building it is made.0.[’a’]) mod.” ext_tools. check the md5 checksum and other meta-data in the imported module with the meta-data of the code it just produced and only compile the code if the module didn’t exist or the meta-data didn’t match. mod = ext_tools.so or . platform. This would reduce the above code to: if __name__ == "__main__": build_increment_ext() a = 1 1.ext_function(’increment’.compile() could try importing the module before it actually compiles it. mod.

a.py provides a little more complex example of how to use ext_tools. SciPy Tutorial . it is just imported and used.py a. 1. """ mod = ext_tools. 8. so it would be beneﬁcial to use the C version for ﬁbonacci number calculations instead of the Python version.increment(a) print ’a.dev6665 print ’a. Needs some thought.ext_module(’fibonacci_ext’) a = 1 # this is effectively a type declaration # recursive fibonacci in C fib_code = """ int fib1(int a) { if(a <= 2) return 1. In Python. a+1:’. but it would only actually compile the code once. 3. it might be written as: def fib(a): if a <= 2: return 1 else: return fib(a-2) + fib(a-1) In C. the ﬁrst two numbers in the series are taken to be 1. the same function would look something like this: int fib(int a) { if(a <= 2) return 1. We need an extension function that calls this C function to do this. the module is created. If you run increment_example. increment_ext. Support code snippets (usually structure deﬁnitions. Here is how to build the C version of the ﬁbonacci number generator: def build_fibonacci(): """ Builds an extension module with fibonacci calculators. you get the following: [eric@n0]$ python increment_example.SciPy Reference Guide. else return fib1(a-2) + fib1(a-1). Fibonacci numbers are a series of numbers where each number in the series is the sum of the previous two: 1. 2.10. increment_ext.increment_by_2(a) Note: There would always be the overhead of building the C++ code. Release 0. You pay a little in overhead and get cleaner “import” code. 5. a+1: 1 2 a. Fibonacci Example examples/fibonacci. 130 Chapter 1. else return fib(a-2) + fib(a-1).py from the command line. This is possible by including the above code snippet as “support code” and then calling it from the extension function. If it did exist.0. etc. a+2: 1 3 If the module didn’t exist before it was run. a. } Recursion is much faster in C than in Python. Here. One approach to calculating Fibonacci numbers uses recursive function calls. helper functions and the like) are inserted into the extension module C/C++ ﬁle before the extension function code. a+2:’.

h also deﬁnes the name. Weave 131 .add_support_code(fib_code) mod. 1. Note: recursion is not the fastest way to calculate ﬁbonacci numbers.customize.13.ext_function(’fib’. and what xxx_info instances are good for. Other things.compile() XXX More about custom_info. """ fib = ext_tools.SciPy Reference Guide. return_val = Py::new_reference_to(Py::Int(val)). you’ll get a cryptic error report due to the fact that stdio..13.11 Things I wish weave did It is possible to get name clashes if you uses a variable name that is already deﬁned in a header automatically included (such as stdio.ext_code.10. Release 0. if you try to pass in a variable named stdout.0..10 Customizing Type Conversions – Type Factories not written 1.[’a’]) fib. but this approach serves nicely for this example.h) For instance.dev6665 } """ ext_code = """ int val = fib1(a).13. weave should probably try and handle this in some way.add_function(fib) mod. 1.

SciPy Reference Guide, Release 0.10.0.dev6665

132

Chapter 1. SciPy Tutorial

CHAPTER

TWO

RELEASE NOTES

2.1 SciPy 0.9.0 Release Notes

Contents • SciPy 0.9.0 Release Notes – Python 3 – Scipy source code location to be changed – New features * Delaunay tesselations (scipy.spatial) * N-dimensional interpolation (scipy.interpolate) * Nonlinear equation solvers (scipy.optimize) * New linear algebra routines (scipy.linalg) * Improved FIR ﬁlter design functions (scipy.signal) * Improved statistical tests (scipy.stats) – Deprecated features * Obsolete nonlinear solvers (in scipy.optimize) – Removed features * Old correlate/convolve behavior (in scipy.signal) * scipy.stats * scipy.sparse * scipy.sparse.linalg.arpack.speigs – Other changes * ARPACK interface changes SciPy 0.9.0 is the culmination of 6 months of hard work. It contains many new features, numerous bug-ﬁxes, improved test coverage and better documentation. There have been a number of deprecations and API changes in this release, which are documented below. All users are encouraged to upgrade to this release, as there are a large number of bugﬁxes and optimizations. Moreover, our development attention will now shift to bug-ﬁx releases on the 0.9.x branch, and on adding new features on the development trunk. This release requires Python 2.4 - 2.7 or 3.1 - and NumPy 1.5 or greater. Please note that SciPy is still considered to have “Beta” status, as we work toward a SciPy 1.0.0 release. The 1.0.0 release will mark a major milestone in the development of SciPy, after which changing the package structure or API will be much more difﬁcult. Whilst these pre-1.0 releases are considered to have “Beta” status, we are committed to making them as bug-free as possible. However, until the 1.0 release, we are aggressively reviewing and reﬁning the functionality, organization, and interface. This is being done in an effort to make the package as coherent, intuitive, and useful as possible. To achieve this, we

133

SciPy Reference Guide, Release 0.10.0.dev6665

need help from the community of users. Speciﬁcally, we need feedback regarding all aspects of the project - everything - from which algorithms we implement, to details about our function’s call signatures.

2.1.1 Python 3

Scipy 0.9.0 is the ﬁrst SciPy release to support Python 3. The only module that is not yet ported is scipy.weave.

**2.1.2 Scipy source code location to be changed
**

Soon after this release, Scipy will stop using SVN as the version control system, and move to Git. The development source code for Scipy can from then on be found at http://github.com/scipy/scipy

2.1.3 New features

Delaunay tesselations (scipy.spatial) Scipy now includes routines for computing Delaunay tesselations in N dimensions, powered by the Qhull computational geometry library. Such calculations can now make use of the new scipy.spatial.Delaunay interface. N-dimensional interpolation (scipy.interpolate) Support for scattered data interpolation is now signiﬁcantly improved. This version includes a scipy.interpolate.griddata function that can perform linear and nearest-neighbour interpolation for N-dimensional scattered data, in addition to cubic spline (C1-smooth) interpolation in 2D and 1D. An object-oriented interface to each interpolator type is also available. Nonlinear equation solvers (scipy.optimize) Scipy includes new routines for large-scale nonlinear equation solving in scipy.optimize. The following methods are implemented: • Newton-Krylov (scipy.optimize.newton_krylov) • (Generalized) secant methods: – Limited-memory Broyden scipy.optimize.broyden2) methods (scipy.optimize.broyden1,

– Anderson method (scipy.optimize.anderson) • Simple iterations (scipy.optimize.diagbroyden, scipy.optimize.linearmixing) scipy.optimize.excitingmixing,

The scipy.optimize.nonlin module was completely rewritten, and some of the functions were deprecated (see above). New linear algebra routines (scipy.linalg) Scipy now contains routines for (scipy.linalg.solve_triangular). effectively solving triangular equation systems

134

Chapter 2. Release Notes

SciPy Reference Guide, Release 0.10.0.dev6665

Improved FIR ﬁlter design functions (scipy.signal) The function scipy.signal.firwin was enhanced to allow the design of highpass, bandpass, bandstop and multi-band FIR ﬁlters. The function scipy.signal.firwin2 was added. This function uses the window method to create a linear phase FIR ﬁlter with an arbitrary frequency response. The functions scipy.signal.kaiser_atten and scipy.signal.kaiser_beta were added. Improved statistical tests (scipy.stats) A new function scipy.stats.fisher_exact was added, that provides Fisher’s exact test for 2x2 contingency tables. The function scipy.stats.kendalltau was rewritten to make it much faster (O(n log(n)) vs O(n^2)).

2.1.4 Deprecated features

Obsolete nonlinear solvers (in scipy.optimize) The following nonlinear solvers from scipy.optimize are deprecated: • broyden_modified (bad performance) • broyden1_modified (bad performance) • broyden_generalized (equivalent to anderson) • anderson2 (equivalent to anderson) • broyden3 (obsoleted by new limited-memory broyden methods) • vackar (renamed to diagbroyden)

2.1.5 Removed features

The deprecated modules helpmod, pexec and ppimport were removed from scipy.misc. The output_type keyword in many scipy.ndimage interpolation functions has been removed. The econ keyword in scipy.linalg.qr has been removed. The same functionality is still available by specifying mode=’economic’. Old correlate/convolve behavior (in scipy.signal) The old behavior for scipy.signal.convolve, scipy.signal.convolve2d, scipy.signal.correlate and scipy.signal.correlate2d was deprecated in 0.8.0 and has now been removed. Convolve and correlate used to swap their arguments if the second argument has dimensions larger than the ﬁrst one, and the mode was relative to the input with the largest dimension. The current behavior is to never swap the inputs, which is what most people expect, and is how correlation is usually deﬁned.

2.1. SciPy 0.9.0 Release Notes

135

SciPy Reference Guide, Release 0.10.0.dev6665

scipy.stats Many functions in scipy.stats that are either available from numpy or have been superseded, and have been deprecated since version 0.7, have been removed: std, var, mean, median, cov, corrcoef, z, zs, stderr, samplestd, samplevar, pdfapprox, pdf_moments and erfc. These changes are mirrored in scipy.stats.mstats. scipy.sparse Several methods of the sparse matrix classes in scipy.sparse which had been deprecated since version 0.7 were removed: save, rowcol, getdata, listprint, ensure_sorted_indices, matvec, matmat and rmatvec. The functions spkron, speye, spidentity, lil_eye and lil_diags were removed from scipy.sparse. The ﬁrst three functions are still available as scipy.sparse.kron, scipy.sparse.eye and scipy.sparse.identity. The dims and nzmax keywords were removed from the sparse matrix constructor. The colind and rowind attributes were removed from CSR and CSC matrices respectively. scipy.sparse.linalg.arpack.speigs A duplicated interface to the ARPACK library was removed.

2.1.6 Other changes

ARPACK interface changes The interface to the ARPACK eigenvalue routines in scipy.sparse.linalg was changed for more robustness. The eigenvalue and SVD routines now raise ArpackNoConvergence if the eigenvalue iteration fails to converge. If partially converged results are desired, they can be accessed as follows:

import numpy as np from scipy.sparse.linalg import eigs, ArpackNoConvergence m = np.random.randn(30, 30) try: w, v = eigs(m, 6) except ArpackNoConvergence, err: partially_converged_w = err.eigenvalues partially_converged_v = err.eigenvectors

Several bugs were also ﬁxed. The routines were moreover renamed as follows: • eigen –> eigs • eigen_symmetric –> eigsh • svd –> svds

2.2 SciPy 0.8.0 Release Notes

136

Chapter 2. Release Notes

SciPy Reference Guide, Release 0.10.0.dev6665

Contents • SciPy 0.8.0 Release Notes – Python 3 – Major documentation improvements – Deprecated features * Swapping inputs for correlation functions (scipy.signal) * Obsolete code deprecated (scipy.misc) * Additional deprecations – New features * DCT support (scipy.fftpack) * Single precision support for fft functions (scipy.fftpack) * Correlation functions now implement the usual deﬁnition (scipy.signal) * Additions and modiﬁcation to LTI functions (scipy.signal) * Improved waveform generators (scipy.signal) * New functions and other changes in scipy.linalg * New function and changes in scipy.optimize * New sparse least squares solver * ARPACK-based sparse SVD * Alternative behavior available for scipy.constants.find * Incomplete sparse LU decompositions * Faster matlab ﬁle reader and default behavior change * Faster evaluation of orthogonal polynomials * Lambert W function * Improved hypergeometric 2F1 function * More ﬂexible interface for Radial basis function interpolation – Removed features * scipy.io SciPy 0.8.0 is the culmination of 17 months of hard work. It contains many new features, numerous bug-ﬁxes, improved test coverage and better documentation. There have been a number of deprecations and API changes in this release, which are documented below. All users are encouraged to upgrade to this release, as there are a large number of bug-ﬁxes and optimizations. Moreover, our development attention will now shift to bug-ﬁx releases on the 0.8.x branch, and on adding new features on the development trunk. This release requires Python 2.4 - 2.6 and NumPy 1.4.1 or greater. Please note that SciPy is still considered to have “Beta” status, as we work toward a SciPy 1.0.0 release. The 1.0.0 release will mark a major milestone in the development of SciPy, after which changing the package structure or API will be much more difﬁcult. Whilst these pre-1.0 releases are considered to have “Beta” status, we are committed to making them as bug-free as possible. However, until the 1.0 release, we are aggressively reviewing and reﬁning the functionality, organization, and interface. This is being done in an effort to make the package as coherent, intuitive, and useful as possible. To achieve this, we need help from the community of users. Speciﬁcally, we need feedback regarding all aspects of the project - everything - from which algorithms we implement, to details about our function’s call signatures.

2.2.1 Python 3

Python 3 compatibility is planned and is currently technically feasible, since Numpy has been ported. However, since the Python 3 compatible Numpy 1.5 has not been released yet, support for Python 3 in Scipy is not yet included in Scipy 0.8. SciPy 0.9, planned for fall 2010, will very likely include experimental support for Python 3.

2.2. SciPy 0.8.0 Release Notes

137

SciPy Reference Guide, Release 0.10.0.dev6665

**2.2.2 Major documentation improvements
**

SciPy documentation is greatly improved.

2.2.3 Deprecated features

Swapping inputs for correlation functions (scipy.signal) Concern correlate, correlate2d, convolve and convolve2d. If the second input is larger than the ﬁrst input, the inputs are swapped before calling the underlying computation routine. This behavior is deprecated, and will be removed in scipy 0.9.0. Obsolete code deprecated (scipy.misc) The modules helpmod, ppimport and pexec from scipy.misc are deprecated. They will be removed from SciPy in version 0.9. Additional deprecations • linalg: The function solveh_banded currently returns a tuple containing the Cholesky factorization and the solution to the linear system. In SciPy 0.9, the return value will be just the solution. • The function constants.codata.ﬁnd will generate a DeprecationWarning. In Scipy version 0.8.0, the keyword argument ‘disp’ was added to the function, with the default value ‘True’. In 0.9.0, the default will be ‘False’. • The qshape keyword argument of signal.chirp is deprecated. Use the argument vertex_zero instead. • Passing the coefﬁcients of a polynomial as the argument f0 to signal.chirp is deprecated. Use the function signal.sweep_poly instead. • The io.recaster module has been deprecated and will be removed in 0.9.0.

2.2.4 New features

DCT support (scipy.fftpack) New realtransforms have been added, namely dct and idct for Discrete Cosine Transform; type I, II and III are available. Single precision support for fft functions (scipy.fftpack) fft functions can now handle single precision inputs as well: fft(x) will return a single precision array if x is single precision. At the moment, for FFT sizes that are not composites of 2, 3, and 5, the transform is computed internally in double precision to avoid rounding error in FFTPACK. Correlation functions now implement the usual deﬁnition (scipy.signal) The outputs should now correspond to their matlab and R counterparts, and do what most people expect if the old_behavior=False argument is passed: • correlate, convolve and their 2d counterparts do not swap their inputs depending on their relative shape anymore;

138

Chapter 2. Release Notes

SciPy Reference Guide, Release 0.10.0.dev6665

• correlation functions now conjugate their second argument while computing the slided sum-products, which correspond to the usual deﬁnition of correlation. Additions and modiﬁcation to LTI functions (scipy.signal) • The functions impulse2 and step2 were added to scipy.signal. They use the function scipy.signal.lsim2 to compute the impulse and step response of a system, respectively. • The function scipy.signal.lsim2 was changed to pass any additional keyword arguments to the ODE solver. Improved waveform generators (scipy.signal) Several improvements to the chirp function in scipy.signal were made: • The waveform generated when method=”logarithmic” was corrected; it now generates a waveform that is also known as an “exponential” or “geometric” chirp. (See http://en.wikipedia.org/wiki/Chirp.) • A new chirp method, “hyperbolic”, was added. • Instead of the keyword qshape, chirp now uses the keyword vertex_zero, a boolean. • chirp no longer handles an arbitrary polynomial. This functionality has been moved to a new function, sweep_poly. A new function, sweep_poly, was added. New functions and other changes in scipy.linalg The functions cho_solve_banded, circulant, companion, hadamard and leslie were added to scipy.linalg. The function block_diag was enhanced to accept scalar and 1D arguments, along with the usual 2D arguments. New function and changes in scipy.optimize The curve_ﬁt function has been added; it takes a function and uses non-linear least squares to ﬁt that to the provided data. The leastsq and fsolve functions now return an array of size one instead of a scalar when solving for a single parameter. New sparse least squares solver The lsqr function was added to scipy.sparse. This routine ﬁnds a least-squares solution to a large, sparse, linear system of equations. ARPACK-based sparse SVD A naive implementation of SVD for sparse matrices is available in scipy.sparse.linalg.eigen.arpack. It is based on using an symmetric solver on <A, A>, and as such may not be very precise.

2.2. SciPy 0.8.0 Release Notes

139

SciPy Reference Guide, Release 0.10.0.dev6665

Alternative behavior available for scipy.constants.find The keyword argument disp was added to the function scipy.constants.find, with the default value True. When disp is True, the behavior is the same as in Scipy version 0.7. When False, the function returns the list of keys instead of printing them. (In SciPy version 0.9, the default will be reversed.) Incomplete sparse LU decompositions Scipy now wraps SuperLU version 4.0, which supports incomplete sparse LU decompositions. These can be accessed via scipy.sparse.linalg.spilu. Upgrade to SuperLU 4.0 also ﬁxes some known bugs. Faster matlab ﬁle reader and default behavior change We’ve rewritten the matlab ﬁle reader in Cython and it should now read matlab ﬁles at around the same speed that Matlab does. The reader reads matlab named and anonymous functions, but it can’t write them. Until scipy 0.8.0 we have returned arrays of matlab structs as numpy object arrays, where the objects have attributes named for the struct ﬁelds. As of 0.8.0, we return matlab structs as numpy structured arrays. You can get the older behavior by using the optional struct_as_record=False keyword argument to scipy.io.loadmat and friends. There is an inconsistency in the matlab ﬁle writer, in that it writes numpy 1D arrays as column vectors in matlab 5 ﬁles, and row vectors in matlab 4 ﬁles. We will change this in the next version, so both write row vectors. There is a FutureWarning when calling the writer to warn of this change; for now we suggest using the oned_as=’row’ keyword argument to scipy.io.savemat and friends. Faster evaluation of orthogonal polynomials Values of orthogonal polynomials can be evaluated with new vectorized functions in scipy.special: eval_legendre, eval_chebyt, eval_chebyu, eval_chebyc, eval_chebys, eval_jacobi, eval_laguerre, eval_genlaguerre, eval_hermite, eval_hermitenorm, eval_gegenbauer, eval_sh_legendre, eval_sh_chebyt, eval_sh_chebyu, eval_sh_jacobi. This is faster than constructing the full coefﬁcient representation of the polynomials, which was previously the only available way. Note that the previous orthogonal polynomial routines will now also invoke this feature, when possible. Lambert W function scipy.special.lambertw can now be used for evaluating the Lambert W function. Improved hypergeometric 2F1 function Implementation of scipy.special.hyp2f1 for real parameters was revised. The new version should produce accurate values for all real parameters. More ﬂexible interface for Radial basis function interpolation The scipy.interpolate.Rbf class now accepts a callable as input for the “function” argument, in addition to the built-in radial basis functions which can be selected with a string argument.

140

Chapter 2. Release Notes

SciPy Reference Guide, Release 0.10.0.dev6665

2.2.5 Removed features

scipy.stsci: the package was removed The module scipy.misc.limits was removed. The IO code in both NumPy and SciPy is being extensively reworked. NumPy will be where basic code for reading and writing NumPy arrays is located, while SciPy will house ﬁle readers and writers for various data formats (data, audio, video, images, matlab, etc.). Several functions in scipy.io are removed in the 0.8.0 release including: npﬁle, save, load, create_module, create_shelf, objload, objsave, fopen, read_array, write_array, fread, fwrite, bswap, packbits, unpackbits, and convert_objectarray. Some of these functions have been replaced by NumPy’s raw reading and writing capabilities, memory-mapping capabilities, or array methods. Others have been moved from SciPy to NumPy, since basic array reading and writing capability is now handled by NumPy.

**2.3 SciPy 0.7.2 Release Notes
**

Contents • SciPy 0.7.2 Release Notes SciPy 0.7.2 is a bug-ﬁx release with no new features compared to 0.7.1. The only change is that all C sources from Cython code have been regenerated with Cython 0.12.1. This ﬁxes the incompatibility between binaries of SciPy 0.7.1 and NumPy 1.4.

**2.4 SciPy 0.7.1 Release Notes
**

Contents • SciPy 0.7.1 Release Notes – scipy.io – scipy.odr – scipy.signal – scipy.sparse – scipy.special – scipy.stats – Windows binaries for python 2.6 – Universal build for scipy SciPy 0.7.1 is a bug-ﬁx release with no new features compared to 0.7.0. Bugs ﬁxed: • Several ﬁxes in Matlab ﬁle IO Bugs ﬁxed: • Work around a failure with Python 2.6 Memory leak in lﬁlter have been ﬁxed, as well as support for array object Bugs ﬁxed:

2.3. SciPy 0.7.2 Release Notes

141

SciPy Reference Guide, Release 0.10.0.dev6665

• #880, #925: lﬁlter ﬁxes • #871: bicgstab fails on Win32 Bugs ﬁxed: • #883: scipy.io.mmread with scipy.sparse.lil_matrix broken • lil_matrix and csc_matrix reject now unexpected sequences, cf. http://thread.gmane.org/gmane.comp.python.scientiﬁc.user/19996 Several bugs of varying severity were ﬁxed in the special functions: • #503, #640: iv: problems at large arguments ﬁxed by new implementation • #623: jv: ﬁx errors at large arguments • #679: struve: ﬁx wrong output for v < 0 • #803: pbdv produces invalid output • #804: lqmn: ﬁx crashes on some input • #823: betainc: ﬁx documentation • #834: exp1 strange behavior near negative integer values • #852: jn_zeros: more accurate results for large s, also in jnp/yn/ynp_zeros • #853: jv, yv, iv: invalid results for non-integer v < 0, complex x • #854: jv, yv, iv, kv: return nan more consistently when out-of-domain • #927: ellipj: ﬁx segfault on Windows • #946: ellpj: ﬁx segfault on Mac OS X/python 2.6 combination. • ive, jve, yve, kv, kve: with real-valued input, return nan for out-of-domain instead of returning only the real part of the result. Also, when scipy.special.errprint(1) has been enabled, warning messages are now issued as Python warnings instead of printing them to stderr. • linregress, mannwhitneyu, describe: errors ﬁxed • kstwobign, norm, expon, exponweib, exponpow, frechet, genexpon, rdist, truncexpon, planck: improvements to numerical accuracy in distributions

**2.4.1 Windows binaries for python 2.6
**

python 2.6 binaries for windows are now included. The binary for python 2.5 requires numpy 1.2.0 or above, and and the one for python 2.6 requires numpy 1.3.0 or above.

**2.4.2 Universal build for scipy
**

Mac OS X binary installer is now a proper universal build, and does not depend on gfortran anymore (libgfortran is statically linked). The python 2.5 version of scipy requires numpy 1.2.0 or above, the python 2.6 version requires numpy 1.3.0 or above.

142

Chapter 2. Release Notes

SciPy Reference Guide, Release 0.10.0.dev6665

**2.5 SciPy 0.7.0 Release Notes
**

Contents • SciPy 0.7.0 Release Notes – Python 2.6 and 3.0 – Major documentation improvements – Running Tests – Building SciPy – Sandbox Removed – Sparse Matrices – Statistics package – Reworking of IO package – New Hierarchical Clustering module – New Spatial package – Reworked fftpack package – New Constants package – New Radial Basis Function module – New complex ODE integrator – New generalized symmetric and hermitian eigenvalue problem solver – Bug ﬁxes in the interpolation package – Weave clean up – Known problems SciPy 0.7.0 is the culmination of 16 months of hard work. It contains many new features, numerous bug-ﬁxes, improved test coverage and better documentation. There have been a number of deprecations and API changes in this release, which are documented below. All users are encouraged to upgrade to this release, as there are a large number of bug-ﬁxes and optimizations. Moreover, our development attention will now shift to bug-ﬁx releases on the 0.7.x branch, and on adding new features on the development trunk. This release requires Python 2.4 or 2.5 and NumPy 1.2 or greater. Please note that SciPy is still considered to have “Beta” status, as we work toward a SciPy 1.0.0 release. The 1.0.0 release will mark a major milestone in the development of SciPy, after which changing the package structure or API will be much more difﬁcult. Whilst these pre-1.0 releases are considered to have “Beta” status, we are committed to making them as bug-free as possible. For example, in addition to ﬁxing numerous bugs in this release, we have also doubled the number of unit tests since the last release. However, until the 1.0 release, we are aggressively reviewing and reﬁning the functionality, organization, and interface. This is being done in an effort to make the package as coherent, intuitive, and useful as possible. To achieve this, we need help from the community of users. Speciﬁcally, we need feedback regarding all aspects of the project - everything - from which algorithms we implement, to details about our function’s call signatures. Over the last year, we have seen a rapid increase in community involvement, and numerous infrastructure improvements to lower the barrier to contributions (e.g., more explicit coding standards, improved testing infrastructure, better documentation tools). Over the next year, we hope to see this trend continue and invite everyone to become more involved.

2.5.1 Python 2.6 and 3.0

A signiﬁcant amount of work has gone into making SciPy compatible with Python 2.6; however, there are still some issues in this regard. The main issue with 2.6 support is NumPy. On UNIX (including Mac OS X), NumPy 1.2.1 mostly works, with a few caveats. On Windows, there are problems related to the compilation process. The upcoming

2.5. SciPy 0.7.0 Release Notes

143

SciPy Reference Guide, Release 0.10.0.dev6665

NumPy 1.3 release will ﬁx these problems. Any remaining issues with 2.6 support for SciPy 0.7 will be addressed in a bug-ﬁx release. Python 3.0 is not supported at all; it requires NumPy to be ported to Python 3.0. This requires immense effort, since a lot of C code has to be ported. The transition to 3.0 is still under consideration; currently, we don’t have any timeline or roadmap for this transition.

**2.5.2 Major documentation improvements
**

SciPy documentation is greatly improved; you can view a HTML reference manual online or download it as a PDF ﬁle. The new reference guide was built using the popular Sphinx tool. This release also includes an updated tutorial, which hadn’t been available since SciPy was ported to NumPy in 2005. Though not comprehensive, the tutorial shows how to use several essential parts of Scipy. It also includes the ndimage documentation from the numarray manual. Nevertheless, more effort is needed on the documentation front. Luckily, contributing to Scipy documentation is now easier than before: if you ﬁnd that a part of it requires improvements, and want to help us out, please register a user name in our web-based documentation editor at http://docs.scipy.org/ and correct the issues.

2.5.3 Running Tests

NumPy 1.2 introduced a new testing framework based on nose. Starting with this release, SciPy now uses the new NumPy test framework as well. Taking advantage of the new testing framework requires nose version 0.10, or later. One major advantage of the new framework is that it greatly simpliﬁes writing unit tests - which has all ready paid off, given the rapid increase in tests. To run the full test suite:

>>> import scipy >>> scipy.test(’full’)

For more information, please see The NumPy/SciPy Testing Guide. We have also greatly improved our test coverage. There were just over 2,000 unit tests in the 0.6.0 release; this release nearly doubles that number, with just over 4,000 unit tests.

2.5.4 Building SciPy

Support for NumScons has been added. NumScons is a tentative new build system for NumPy/SciPy, using SCons at its core. SCons is a next-generation build system, intended to replace the venerable Make with the integrated functionality of autoconf/automake and ccache. Scons is written in Python and its conﬁguration ﬁles are Python scripts. NumScons is meant to replace NumPy’s custom version of distutils providing more advanced functionality, such as autoconf, improved fortran support, more tools, and support for numpy.distutils/scons cooperation.

2.5.5 Sandbox Removed

While porting SciPy to NumPy in 2005, several packages and modules were moved into scipy.sandbox. The sandbox was a staging ground for packages that were undergoing rapid development and whose APIs were in ﬂux. It was also a place where broken code could live. The sandbox has served its purpose well, but was starting to create confusion. Thus scipy.sandbox was removed. Most of the code was moved into scipy, some code was made into a scikit, and the remaining code was just deleted, as the functionality had been replaced by other code.

144

Chapter 2. Release Notes

SciPy Reference Guide, Release 0.10.0.dev6665

2.5.6 Sparse Matrices

Sparse matrices have seen extensive improvements. There is now support for integer dtypes such int8, uint32, etc. Two new sparse formats were added: • new class dia_matrix : the sparse DIAgonal format • new class bsr_matrix : the Block CSR format Several new sparse matrix construction functions were added: • sparse.kron : sparse Kronecker product • sparse.bmat : sparse version of numpy.bmat • sparse.vstack : sparse version of numpy.vstack • sparse.hstack : sparse version of numpy.hstack Extraction of submatrices and nonzero values have been added: • sparse.tril : extract lower triangle • sparse.triu : extract upper triangle • sparse.find : nonzero values and their indices csr_matrix and csc_matrix now support slicing and fancy indexing (e.g., A[1:3, 4:7] and A[[3,2,6,8],:]). Conversions among all sparse formats are now possible: • using member functions such as .tocsr() and .tolil() • using the .asformat() member function, e.g. A.asformat(’csr’) • using constructors A = lil_matrix([[1,2]]); B = csr_matrix(A) All sparse constructors now accept dense matrices and lists of lists. For example: • A = csr_matrix( rand(3,3) ) and B = lil_matrix( [[1,2],[3,4]] ) The handling of diagonals in the spdiags function has been changed. It now agrees with the MATLAB(TM) function of the same name. Numerous efﬁciency improvements to format conversions and sparse matrix arithmetic have been made. Finally, this release contains numerous bugﬁxes.

2.5.7 Statistics package

Statistical functions for masked arrays have been added, and are accessible through scipy.stats.mstats. The functions are similar to their counterparts in scipy.stats but they have not yet been veriﬁed for identical interfaces and algorithms. Several bugs were ﬁxed for statistical functions, of those, kstest and percentileofscore gained new keyword arguments. Added deprecation warning for mean, median, var, std, cov, and corrcoef. These functions should be replaced by their numpy counterparts. Note, however, that some of the default options differ between the scipy.stats and numpy versions of these functions. Numerous bug ﬁxes to stats.distributions: all generic methods now work correctly, several methods in individual distributions were corrected. However, a few issues remain with higher moments (skew, kurtosis) and entropy. The maximum likelihood estimator, fit, does not work out-of-the-box for some distributions - in some cases, starting values have to be carefully chosen, in other cases, the generic implementation of the maximum likelihood method might not be the numerically appropriate estimation method.

2.5. SciPy 0.7.0 Release Notes

145

SciPy Reference Guide, Release 0.10.0.dev6665

We expect more bugﬁxes, increases in numerical precision and enhancements in the next release of scipy.

2.5.8 Reworking of IO package

The IO code in both NumPy and SciPy is being extensively reworked. NumPy will be where basic code for reading and writing NumPy arrays is located, while SciPy will house ﬁle readers and writers for various data formats (data, audio, video, images, matlab, etc.). Several functions in scipy.io have been deprecated and will be removed in the 0.8.0 release including npfile, save, load, create_module, create_shelf, objload, objsave, fopen, read_array, write_array, fread, fwrite, bswap, packbits, unpackbits, and convert_objectarray. Some of these functions have been replaced by NumPy’s raw reading and writing capabilities, memory-mapping capabilities, or array methods. Others have been moved from SciPy to NumPy, since basic array reading and writing capability is now handled by NumPy. The Matlab (TM) ﬁle readers/writers have a number of improvements: • default version 5 • v5 writers for structures, cell arrays, and objects • v5 readers/writers for function handles and 64-bit integers • new struct_as_record keyword argument to loadmat, which loads struct arrays in matlab as record arrays in numpy • string arrays have dtype=’U...’ instead of dtype=object • loadmat no longer squeezes singleton dimensions, i.e. squeeze_me=False by default

**2.5.9 New Hierarchical Clustering module
**

This module adds new hierarchical clustering functionality to the scipy.cluster package. The function interfaces are similar to the functions provided MATLAB(TM)’s Statistics Toolbox to help facilitate easier migration to the NumPy/SciPy framework. Linkage methods implemented include single, complete, average, weighted, centroid, median, and ward. In addition, several functions are provided for computing inconsistency statistics, cophenetic distance, and maximum distance between descendants. The fcluster and fclusterdata functions transform a hierarchical clustering into a set of ﬂat clusters. Since these ﬂat clusters are generated by cutting the tree into a forest of trees, the leaders function takes a linkage and a ﬂat clustering, and ﬁnds the root of each tree in the forest. The ClusterNode class represents a hierarchical clusterings as a ﬁeld-navigable tree object. to_tree converts a matrix-encoded hierarchical clustering to a ClusterNode object. Routines for converting between MATLAB and SciPy linkage encodings are provided. Finally, a dendrogram function plots hierarchical clusterings as a dendrogram, using matplotlib.

**2.5.10 New Spatial package
**

The new spatial package contains a collection of spatial algorithms and data structures, useful for spatial statistics and clustering applications. It includes rapidly compiled code for computing exact and approximate nearest neighbors, as well as a pure-python kd-tree with the same interface, but that supports annotation and a variety of other algorithms. The API for both modules may change somewhat, as user requirements become clearer. It also includes a distance module, containing a collection of distance and dissimilarity functions for computing distances between vectors, which is useful for spatial statistics, clustering, and kd-trees. Distance and dissimilarity functions provided include Bray-Curtis, Canberra, Chebyshev, City Block, Cosine, Dice, Euclidean, Hamming,

146

Chapter 2. Release Notes

SciPy Reference Guide, Release 0.10.0.dev6665

Jaccard, Kulsinski, Mahalanobis, Matching, Minkowski, Rogers-Tanimoto, Russell-Rao, Squared Euclidean, Standardized Euclidean, Sokal-Michener, Sokal-Sneath, and Yule. The pdist function computes pairwise distance between all unordered pairs of vectors in a set of vectors. The cdist computes the distance on all pairs of vectors in the Cartesian product of two sets of vectors. Pairwise distance matrices are stored in condensed form; only the upper triangular is stored. squareform converts distance matrices between square and condensed forms.

**2.5.11 Reworked fftpack package
**

FFTW2, FFTW3, MKL and DJBFFT wrappers have been removed. Only (NETLIB) fftpack remains. By focusing on one backend, we hope to add new features - like ﬂoat32 support - more easily.

**2.5.12 New Constants package
**

scipy.constants provides a collection of physical constants and conversion factors. These constants are taken from CODATA Recommended Values of the Fundamental Physical Constants: 2002. They may be found at physics.nist.gov/constants. The values are stored in the dictionary physical_constants as a tuple containing the value, the units, and the relative precision - in that order. All constants are in SI units, unless otherwise stated. Several helper functions are provided.

**2.5.13 New Radial Basis Function module
**

scipy.interpolate now contains a Radial Basis Function module. Radial basis functions can be used for smoothing/interpolating scattered data in n-dimensions, but should be used with caution for extrapolation outside of the observed data range.

**2.5.14 New complex ODE integrator
**

scipy.integrate.ode now contains a wrapper for the ZVODE complex-valued ordinary differential equation solver (by Peter N. Brown, Alan C. Hindmarsh, and George D. Byrne).

**2.5.15 New generalized symmetric and hermitian eigenvalue problem solver
**

scipy.linalg.eigh now contains wrappers for more LAPACK symmetric and hermitian eigenvalue problem solvers. Users can now solve generalized problems, select a range of eigenvalues only, and choose to use a faster algorithm at the expense of increased memory usage. The signature of the scipy.linalg.eigh changed accordingly.

**2.5.16 Bug ﬁxes in the interpolation package
**

The shape of return values from scipy.interpolate.interp1d used to be incorrect, if interpolated data had more than 2 dimensions and the axis keyword was set to a non-default value. This has been ﬁxed. Moreover, interp1d returns now a scalar (0D-array) if the input is a scalar. Users of scipy.interpolate.interp1d may need to revise their code if it relies on the previous behavior.

2.5.17 Weave clean up

There were numerous improvements to scipy.weave. blitz++ was relicensed by the author to be compatible with the SciPy license. wx_spec.py was removed. 2.5. SciPy 0.7.0 Release Notes 147

SciPy Reference Guide, Release 0.10.0.dev6665

2.5.18 Known problems

Here are known problems with scipy 0.7.0: • weave test failures on windows: those are known, and are being revised. • weave test failure with gcc 4.3 (std::labs): this is a gcc 4.3 bug. A workaround is to add #include <cstdlib> in scipy/weave/blitz/blitz/funcs.h (line 27). You can make the change in the installed scipy (in site-packages).

148

Chapter 2. Release Notes

CHAPTER

THREE

REFERENCE

3.1 Clustering package (scipy.cluster)

3.1.1 Hierarchical clustering (scipy.cluster.hierarchy)

Warning: This documentation is work-in-progress and unorganized.

Function Reference These functions cut hierarchical clusterings into ﬂat clusterings or ﬁnd the roots of the forest formed by a cut by providing the ﬂat cluster ids of each observation. fcluster(Z, t[, criterion, depth, R, monocrit]) fclusterdata(X, t[, criterion, metric, ...]) leaders(Z, T) Forms ﬂat clusters from the hierarchical clustering deﬁned by Cluster observation data using a given metric. (L, M) = leaders(Z, T):

scipy.cluster.hierarchy.fcluster(Z, t, criterion=’inconsistent’, depth=2, R=None, monocrit=None) Forms ﬂat clusters from the hierarchical clustering deﬁned by the linkage matrix Z. Parameters Z : ndarray The hierarchical clustering encoded with the matrix returned by the linkage function. t : ﬂoat The threshold to apply when forming ﬂat clusters. criterion : str, optional The criterion to use in forming ﬂat clusters. This can be any of the following values: ‘inconsistent’: If a cluster node and all its descendants have an inconsistent value less than or equal to t then all its leaf descendants belong to the same ﬂat cluster. When no non-singleton cluster meets this criterion, every node is assigned to its own cluster. (Default) ‘distance’: Forms ﬂat clusters so that the original observations in each ﬂat cluster have no greater a cophenetic distance than t.

149

8. and forms ﬂat clusters using the inconsistency method with t as the cut-off threshold. monocrit must be monotonic. R) cluster(Z. For example.0. R=None) Cluster observation data using a given metric.10. ‘monocrit’: Forms a ﬂat cluster from a cluster node c with index i when monocrit[j] <= t.fclusterdata(X. t=3.dev6665 ‘maxclust’: Finds a minimum threshold r so that the cophenetic distance between any two original observations in the same ﬂat cluster is no more than r and no more than t ﬂat clusters are formed. optional The maximum depth to perform the inconsistency calculation. to minimize the threshold t on maximum inconsistency values so that no more than 3 ﬂat clusters are formed. 3) cluster(Z. monocrit=MI) depth : int.SciPy Reference Guide. to threshold on the maximum mean distance as computed in the inconsistency matrix R with a threshold of 0. Release 0. R : ndarray. Default is 2. T[i] is the index of the ﬂat cluster to which the original observation i belongs. Returns fcluster : ndarray An array of length n. t=0. criterion=’maxclust_monocrit’. performs hierarchical clustering using the single linkage algorithm. A one-dimensional array T of length n is returned. t. monocrit : ndarray. method=’single’. scipy. 150 Chapter 3. monocrit[i] is the statistics upon which non-singleton i is thresholded. R. metric=’euclidean’. i. do: MI = maxinconsts(Z. It has no meaning for the other criteria. monocrit=MR) ‘maxclust_monocrit’: Forms a ﬂat cluster from a non-singleton cluster node c when monocrit[i] <= r for all cluster indices i below and including c.hierarchy. Reference . optional The inconsistency matrix to use for the ‘inconsistent’ criterion. criterion=’inconsistent’. The monocrit vector must be monotonic. given a node c with index i. using the euclidean distance metric to calculate distances between original observations. depth=2. optional An array of length n-1. monocrit[i] >= monocrit[j]. For example. This matrix is computed if not provided. for all node indices j corresponding to nodes below c.cluster. r is minimized such that no more than t ﬂat clusters are formed. T[i] is the ﬂat cluster number to which original observation i belongs.8 do: MR = maxRstat(Z.e. Clusters the original observations in the n-by-m data matrix X (n observations in m dimensions). criterion=’monocrit’.

metric : str. criterion : str.leaders(Z. this function ﬁnds the lowest cluster node i in the linkage tree Z such that: •leaf descendents belong only to ﬂat cluster j (i.SciPy Reference Guide. weighted. Returns T : ndarray A vector of length n. T[q]!=j for all q not in S(i)). optional The maximum depth for the inconsistency calculation. For each ﬂat cluster j of the k ﬂat clusters represented in the n-sized ﬂat cluster assignment vector T.cluster) 151 . optional The linkage method to use (single.dev6665 Parameters X : ndarray n by m data matrix with n observations in m dimensions.cluster. optional The distance metric for calculating pairwise distances. If this condition is violated. complete. and an exception will be thrown. Notes This function is similar to the MATLAB function clusterdata. ‘distance’.e. See linkage for more information. scipy. See inconsistent for more information. See the fcluster function for more information on the format of T.10. median centroid. T[i] is the ﬂat cluster number to which original observation i belongs.pdist for descriptions and linkage to verify compatibility with the linkage method.hierarchy. See fcluster for descriptions. optional Speciﬁes the criterion for forming ﬂat clusters. or ‘maxclust’ cluster formation algorithms. T[p]==j for all p in S(i) where S(i) is the set of leaf ids of leaf nodes descendent with cluster node i) •there does not exist a leaf that is not descendent with i that also belongs to cluster j (i. average. R : ndarray. M) = leaders(Z. ward). T) (L. depth : int. T): Returns the root nodes in a hierarchical clustering corresponding to a cut deﬁned by a ﬂat cluster assignment vector T. T is not a valid cluster assignment vector.1.0. optional The cut-off threshold for the cluster function or the maximum number of clusters (criterion=’maxclust’). See distance. t : double.e. method : str. 3. Release 0. t : ﬂoat The threshold to apply when forming ﬂat clusters. It will be computed if necessary if it is not passed. Default is “single”. optional The inconsistency matrix. Valid values are ‘inconsistent’ (default). Clustering package (scipy.

Reference . Returns A tuple (L. The following linkage methods are used to compute the distance d(s.SciPy Reference Guide. s and t are removed from the 152 Chapter 3. y must be a n sized vector where n is the number of original observations 2 paired in the distance matrix. 0] and Z[i. Release 0. See linkage for more Performs Ward’s linkage on a condensed or redundant distance scipy. See linkage for more information. The behavior of this function is very similar to the MATLAB(TM) linkage function. If i < n. The algorithm begins with a forest of clusters that have yet to be used in the hierarchy being formed. L[j]=i is the linkage cluster node id that is the leader of ﬂat cluster with id M[j]. otherwise it corresponds to a non-singleton cluster. M) with : L : ndarray The leader linkage node id’s stored as a k-element 1D array where k is the number of ﬂat clusters found in T. Performs single/min/nearest linkage on the condensed distance matrix y. linkage(y[. At the i-th iteration. M : ndarray The leader linkage node id’s stored as a k-element 1D array where k is the number of ﬂat clusters found in T. Performs complete complete/max/farthest point linkage on the condensed distance matrix y. These are routines for agglomerative clustering.0. metric]) single(y) complete(y) average(y) weighted(y) centroid(y) median(y) ward(y) Performs hierarchical/agglomerative clustering on the condensed distance matrix y. method=’single’. This allows the set of ﬂat cluster ids to be any arbitrary set of k integers. See linkage for more Performs median/WPGMC linkage. metric=’euclidean’) Performs hierarchical/agglomerative clustering on the condensed distance matrix y. method. T : ndarray The ﬂat cluster assignment vector.hierarchy. When two clusters s and t from this forest are combined into a single cluster u.10. A cluster with an index less than n corresponds to one of the n original observations. the ﬂat cluster with id 8’s leader is linkage node 2. 1] are combined to form cluster n+i. The fourth value Z[i.cluster. t) between two clusters s and t. 0] and Z[i. 3] represents the number of original observations in the newly formed cluster. The distance between clusters Z[i. A 4 by (n − 1) matrix Z is returned. 2].dev6665 Parameters Z : ndarray The hierarchical clustering encoded as a matrix. Performs average/UPGMA linkage on the condensed distance matrix Performs weighted/WPGMA linkage on the condensed distance matrix Performs centroid/UPGMC linkage. 1] is given by Z[i. clusters with indices Z[i.linkage(y. For example: if L[3]=2 and M[3]=8. i corresponds to an original observation.

t) like the centroid method. v))/2 where cluster u was formed with cluster s and t and v is a remaining cluster in the forest. u[|u| − 1] in cluster u and |v| original objects v[0]. • method=’median’ assigns math:d(s. 3. v) = (dist(s.j] entry corresponds to the distance between cluster i and j in the original forest. (also called WPGMA) • method=’centroid’ assigns dist(s. t) = ||cs − ct ||2 where cs and ct are the centroids of clusters s and t.SciPy Reference Guide. When only one cluster remains in the forest.1. . The distance then becomes the Euclidean distance between the centroid of u and the centroid of a remaining cluster v in the forest. v[j])) for all points i in cluster u and j in cluster v. . v[j])) for all points i in cluster u and j in cluster v. v) = max(dist(u[i]. respectively. At each iteration. the algorithm must update the distance matrix to reﬂect the distance of the newly formed cluster u with the remaining clusters in the forest. • method=’single’ assigns d(u.10. . When two clusters s and t are combined into a new cluster u. When two clusters s and t are combined into a new cluster u. v[|v| − 1] in cluster v. A distance matrix is maintained at each iteration. Let v be any remaining cluster in the forest that is not u. • method=’complete’ assigns d(u. This is also known as the WPGMC algorithm.0. v) = ij d(u[i].cluster) 153 . v) = min(dist(u[i]. This is also known as the Nearest Point Algorithm. . This is also called the UPGMA algorithm. . the new centroid is computed over all the original objects in clusters s and t. the algorithm stops. This is called UPGMA. . . This is also known by the Farthest Point Algorithm or Voor Hees Algorithm. and u is added to the forest.dev6665 forest. v[j]) (|u| ∗ |v|) for all points i and j where |u| and |v| are the cardinalities of clusters u and v. . and this cluster becomes the root. v) + dist(t. • method=’average’ assigns d(u. respectively. The d[i. This is also known as the UPGMC algorithm. • method=’weighted’ assigns d(u. Suppose there are |u| original observations u[0]. Clustering package (scipy. the average of centroids s and t give the new centroid u. Release 0. The following are methods for calculating the distance between the newly formed cluster u and each v. Recall s and t are combined to form cluster u.

pdist function for a list of valid distance metrics.cluster. See linkage for more information on the return structure and algorithm. metric [str] The distance metric to use.hierarchy.0. Parameters y : ndarray The upper triangular of the distance matrix. t)2 T T T where u is the newly joined cluster consisting of clusters s and t. The new entry d(u. Alternatively. A condensed distance matrix is a ﬂat array containing the upper triangular of the distance matrix. v) = |v| + |t| |v| |v| + |s| d(v. there may be two or more pairs with the same minimum distance. Release 0.dev6665 • method=’ward’ uses the Ward variance minimization algorithm. 154 Chapter 3. t)2 + d(s. Reference . s)2 + d(v. This is the form that pdist returns. d(u. Warning: When the minimum distance pair in the forest is chosen. v) is computed as follows. Returns Z : ndarray The hierarchical clustering encoded as a linkage matrix. scipy. scipy. See linkage for more information on the return structure and algorithm. T = |v| + |s| + |t|. See the distance. See Also: linkage for advanced creation of hierarchical clusterings. See the Linkage Methods section below for full descriptions. method [str] The linkage algorithm to use. This implementation may chose a different minimum than the MATLAB(TM) version.complete(y) Performs complete complete/max/farthest point linkage on the condensed distance matrix y.hierarchy. Returns Z : ndarray The linkage matrix.single(y) Performs single/min/nearest linkage on the condensed distance matrix y. The result of pdist is returned in this form.cluster. Parameters y : ndarray A condensed or redundant distance matrix. a collection of m observation vectors in n dimensions may be passed as an m by n array. This is also known as the incremental algorithm.SciPy Reference Guide. and | ∗ | is the cardinality of its argument. v is an unused cluster in the forest.10.

Returns Z : ndarray A linkage matrix containing the hierarchical clustering. Parameters y : ndarray The upper triangular of the distance matrix.hierarchy. The result of pdist is returned in this form. See linkage for more information on the return structure and algorithm.cluster. See linkage for more information on the return structure and algorithm. See the linkage function documentation for more information on its structure.dev6665 Parameters y : ndarray The upper triangular of the distance matrix.cluster) 155 . See Also: linkage for advanced creation of hierarchical clusterings. Release 0. The result of pdist is returned in this form.10.1.0. scipy. Returns Z : ndarray A linkage matrix containing the hierarchical clustering. See Also: linkage for advanced creation of hierarchical clusterings. The result of pdist is returned in this form.Z = centroid(y) 3.average(y) Performs average/UPGMA linkage on the condensed distance matrix y. scipy. Clustering package (scipy.centroid(y) Performs centroid/UPGMC linkage.cluster. See the linkage function documentation for more information on its structure.SciPy Reference Guide. Returns Z : ndarray A linkage matrix containing the hierarchical clustering. The following are common calling conventions: 1.weighted(y) Performs weighted/WPGMA linkage on the condensed distance matrix y. See linkage for more information on the return structure and algorithm.hierarchy. Parameters y : ndarray The upper triangular of the distance matrix.hierarchy. scipy.cluster. See the linkage function documentation for more information on its structure.

Z = median(X) Performs median/WPGMC linkage on the observation matrix X using Euclidean distance as the distance metric. Returns Z : ndarray A linkage matrix containing the hierarchical clustering.hierarchy. See Also: 156 Chapter 3. a collection of m observation vectors in n dimensions may be passed as a m by n array. Release 0. a collection of m observation vectors in n dimensions may be passed as a m by n array. See linkage for more information on the return structure and algorithm.SciPy Reference Guide.Z = median(y) Performs median/WPGMC linkage on the condensed distance matrix y. A condensed distance matrix is a ﬂat array containing the upper triangular of the distance matrix. This is the form that pdist returns. This is the form that pdist returns.median(y) Performs median/WPGMC linkage. See Also: linkage for advanced creation of hierarchical clusterings. See linkage for more information on the return structure and algorithm. Alternatively.cluster. See linkage for more information on the return structure and algorithm. See linkage for more information on the return structure and algorithm.10. Alternatively. Reference .0. 2. scipy.Z = centroid(X) Performs centroid/UPGMC linkage on the observation matrix X using Euclidean distance as the distance metric. 2.dev6665 Performs centroid/UPGMC linkage on the condensed distance matrix y. See linkage for more information on the return structure and algorithm. Parameters Q : ndarray A condensed or redundant distance matrix. See the linkage function documentation for more information on its structure. The following are common calling conventions: 1. Parameters Q : ndarray A condensed or redundant distance matrix. A condensed distance matrix is a ﬂat array containing the upper triangular of the distance matrix. Returns Z : ndarray The hierarchical clustering encoded as a linkage matrix.

Parameters Q : ndarray A condensed or redundant distance matrix. d]) maxinconsts(Z. See linkage for more information on the return structure and algorithm.cluster. The cophenetic distance between observations i and j is simply the distance between clusters s and t.1.Z = ward(y) Performs Ward’s linkage on the condensed distance matrix Z. The following are common calling conventions: 1. to_mlab_linkage(Z) Converts a linkage matrix Z generated by the linkage function scipy. Calculates inconsistency statistics on a linkage. See linkage for more information on the return structure and algorithm.dev6665 linkage for advanced creation of hierarchical clusterings. Clustering package (scipy. 2. Returns Z : ndarray The hierarchical clustering encoded as a linkage matrix.ward(y) Performs Ward’s linkage on a condensed or redundant distance matrix. See Also: linkage for advanced creation of hierarchical clusterings.hierarchy.0. See linkage for more information on the return structure and algorithm. scipy.SciPy Reference Guide. A condensed distance matrix is a ﬂat array containing the upper triangular of the distance matrix. Parameters Z : ndarray The hierarchical clustering encoded as an array (see linkage function).hierarchy. Suppose p and q are original observations in disjoint clusters s and t. R. respectively and s and t are joined by a direct parent cluster u. R) Returns the maximum inconsistency coefﬁcient for each non-singleton cluster and its descendents. a collection of m observation vectors in n dimensions may be passed as a m by n array. cophenet(Z[. Alternatively. Release 0.cluster. maxdists(Z) Returns the maximum distance between any cluster for each non-singleton cluster. These routines compute statistics on hierarchies. i) Returns the maximum statistic for each non-singleton cluster and its descendents. Y]) Calculates the cophenetic distances between each observation in from_mlab_linkage(Z) Converts a linkage matrix generated by MATLAB(TM) to a new inconsistent(Z[. Y=None) Calculates the cophenetic distances between each observation in the hierarchical clustering deﬁned by the linkage Z. maxRstat(Z.10.Z = ward(X) Performs Ward’s linkage on the observation matrix X using Euclidean distance as the distance metric. This is the form that pdist returns.cluster) 157 .cophenet(Z. Y : ndarray (optional) 3.

R[i.(N-1) form. Y is the condensed distance matrix from which Z was generated.dev6665 Calculates the cophenetic correlation coefﬁcient c of a hierarchical clustering deﬁned by the linkage matrix Z of a set of n observations in m dimensions. Z : ndarray The (n − 1) by 4 matrix encoding the linkage (hierarchical clustering). racZ[i. The ij th entry is the cophenetic distance between original observations i and j. Returns R : ndarray A (n − 1) by 5 matrix where the i‘th row contains the link statistics for the nonsingleton cluster i.from_mlab_linkage(Z) Converts a linkage matrix generated by MATLAB(TM) to a new linkage matrix compatible with this module.10. 0]R[i. scipy.. 2] − R[i. This function is useful when loading in linkages from legacy data ﬁles generated by MATLAB.3] is represents the number of original observations (leaves) in the non-singleton cluster i. Parameters d : int The number of links up to d levels below each non-singleton cluster.hierarchy.0. linkage documentation for more information on its form. R[i. and •a fourth column Z[:. See 158 Chapter 3.SciPy Reference Guide. Note: This function behaves similarly to the MATLAB(TM) inconsistent function. The link statistics are computed over the link heights for links d levels below the cluster i.0] and R[i.hierarchy. Reference .2] is the number of links included in the calculation.3] is the inconsistency coefﬁcient. • d [ndarray] The cophenetic distance matrix in condensed form. Returns ZS : ndarray A linkage matrix compatible with this library. Parameters Z : ndarray A linkage matrix generated by MATLAB(TM).3] is added where Z[i. The conversion does two things: •the indices are converted from 1. Returns res : tuple A tuple (c.cluster.N to 0. respectively..cluster. scipy.1] are the mean and standard deviation of the link heights. Release 0. 1].inconsistent(Z. d=2) Calculates inconsistency statistics on a linkage. and R[i. {d}): • c [ndarray] The cophentic correlation distance (if y is passed).

i : int The column of R to use as the statistic. scipy. 3.10. R. Parameters Z : ndarray The hierarchical clustering encoded as a matrix. R : ndarray The inconsistency matrix.. MD[i] = Z[Q(i)-n.to_mlab_linkage(Z) Converts a linkage matrix Z generated by the linkage function of this module to a MATLAB(TM) compatible one.SciPy Reference Guide. See linkage for more information. See linkage for more information. Returns MI : ndarray A monotonic (n-1)-sized numpy array of doubles. Release 0.0.cluster. Parameters Z : ndarray The hierarchical clustering encoded as a matrix. 2]. More speciﬁcally.maxRstat(Z. i] where Q(j) the set of all node ids corresponding to nodes below and including j. Parameters Z : ndarray The hierarchical clustering encoded as a matrix.1.cluster) 159 .maxdists(Z) Returns the maximum distance between any cluster for each non-singleton cluster. See linkage for more information. R) Returns the maximum inconsistency coefﬁcient for each non-singleton cluster and its descendents.hierarchy.cluster.N indexing.hierarchy. The return linkage matrix has the last column removed and the cluster indices are converted to 1. Clustering package (scipy.cluster.cluster.hierarchy.max() where Q(i) is the set of all node indices below and including node i. scipy. scipy.dev6665 scipy. Returns MR : ndarray Calculates the maximum statistic for the i’th column of the inconsistency matrix R for each non-singleton cluster node.maxinconsts(Z. R : ndarray The inconsistency matrix.hierarchy. MD[i] represents the maximum distance between any cluster (including singletons) below and including the node with index i. MR[j] is the maximum over R[Q(j)-n. Returns MD : ndarray A (n-1) sized numpy array of doubles. i) Returns the maximum statistic for each non-singleton cluster and its descendents.

they correspond to to rows Z[n-p-2:end] in Z. It is expected that the distances in Z[:. leaf_font_size=None. p=30. truncate_mode=None. Reference .. Release 0.. All other non-singleton clusters are contracted into leaf nodes. color_threshold=None. (not implemented yet) • ‘level’/’mtica’: no more than p levels of the dendrogram tree are displayed. optional The p parameter for truncate_mode. labels=None. The height of the top of the U-link is the distance between its children clusters. color_list=None. leaf_rotation=None. optional 160 Chapter 3.]) Plots the hiearchical clustering deﬁned by the linkage Z as a scipy. . get_leaves=True.SciPy Reference Guide.2] be monotonic. color_threshold : double. show_contracted=False.cluster. Parameters Z : ndarray The linkage matrix encoding the hierarchical clustering to render as a dendrogram. no_leaves=False. leaf_label_func=None. show_leaf_counts=True. truncate_mode : str. Returns ZM : ndarray A linkage matrix compatible with MATLAB(TM)’s hierarchical clustering functions. dendrogram(Z[. See the linkage function for more information on the format of Z. Routines for visualizing ﬂat clusters. link_color_func=None) Plots the hiearchical clustering deﬁned by the linkage Z as a dendrogram. no_labels=False. Truncation is used to condense the dendrogram. optional The dendrogram can be hard to read when the original observation matrix from which the linkage is derived is large. truncate_mode. p. • ‘mlab’: This corresponds to MATLAB(TM) behavior. This corresponds to Mathematica(TM) behavior.dendrogram(Z. orientation=’top’. It is also the cophenetic distance between original observations in the two children clusters.dev6665 Parameters Z : ndarray A linkage matrix generated by this library.hierarchy. no_plot=False.0. p : int. otherwise crossings appear in the dendrogram. The dendrogram illustrates how each cluster is composed by drawing a U-shaped link between a non-singleton cluster and its children. distance_sort=False. count_sort=False.10. There are several modes: • None/’none’: no truncation is performed (Default) • ‘lastp’: the last p non-singleton formed in the linkage are the only non-leaf nodes in the linkage.

SciPy Reference Guide.cluster) 161 . and plot descendent links going right. where j < 2n − 1 and i < n. • ‘descendent’: the child with the maximum number of original objects in its cluster is plotted ﬁrst. orientation : str.2]).1. Note distance_sort and count_sort cannot both be True. get_leaves : bool. For each i. from left-to-right) n’s two descendent links are plotted is determined by this parameter. (default). this is an n -sized list (or tuple). If t is less than or equal to zero. the threshold is set to 0. and plot descendent links going left. and plot descendent links going downwards. Colors all the descendent links below a cluster node k the same color if k is the ﬁrst node below the cut threshold t. optional For each node n. count_sort : str or bool. which can be any of the following values: • False: nothing is done. • ‘bottom’: plots the root at the bottom.dev6665 For brevity. the order (visually.7*max(Z[:. The labels[i] value is the text to put under the i th leaf node only if it corresponds to an original observation and not a non-singleton cluster. from left-to-right) n’s two descendent links are plotted is determined by this parameter. labels : ndarray. Release 0. cluster node j appears in the i th position in the left-to-right traversal of the leaves. let t be the color_threshold. If color_threshold is None or ‘default’. Otherwise. • ‘right’: plots the root at the right. optional For each node n. • ‘ascending’/True: the child with the minimum number of original objects in its cluster is plotted ﬁrst. which can be any of the following strings • ‘top’: plots the root at the top. optional Includes a list R[’leaves’]=H in the result dictionary. optional By default labels is None so the index of the original observation is used to label the leaf nodes. optional The direction to plot the dendrogram. the order (visually. 3. distance_sort : str or bool. corresponding with MATLAB(TM) behavior. • ‘left’: plots the root at the left. which can be any of the following values: • False: nothing is done. and plot descendent links going upwards. H[i] == j.0. All links connecting nodes with distances greater than or equal to the threshold are colored blue.10. all nodes are colored blue. Clustering package (scipy.

leaf_label_func=llf. no_plot : bool. leaf_label_rotation : double. optional When leaf_label_func is a callable function. optional When True. count. optional Speciﬁes the angle (in degrees) to rotate the leaf labels. R[n-id. leaf_rotation=90) show_contracted : bool When True the heights of non-singleton nodes contracted into a leaf node are plotted as crosses along the link connecting that leaf node. show_leaf_counts : bool. count. leaf nodes representing k > 1 original observation are labeled with the number of observations they contain in parentheses.2f]’ % (id.0.3]) # The text for the leaf nodes is going to be big so force # a rotation of 90 degrees. optional When True. no labels appear next to the leaf nodes in the rendering of the dendrogram. the size based on the number of nodes in the dendrogram. to label singletons with their node id and non-singletons with their id. for each leaf with cluster index k < 2n − 1. and inconsistency coefﬁcient. Indices k < n correspond to original observations while indices k ≥ n correspond to non-singleton clusters. (Default=0) leaf_font_size : int. When unspeciﬁed. The function is expected to return a string with the label for the leaf. leaf_label_func : lambda or function. the rotation based on the number of nodes in the dendrogram. Release 0. no_labels : bool.SciPy Reference Guide.dev6665 • ‘ascending’/True: the child with the minimum distance between its direct descendents is plotted ﬁrst. For example. optional When True. Note distance_sort and count_sort cannot both be True. Reference . This really is only useful when truncation is used (see truncate_mode parameter). simply do: # First define the leaf label function. link_color_func : lambda/function 162 Chapter 3. This is useful if only the data structures computed for the rendering are needed or if matplotlib is not available. the ﬁnal rendering is not performed. dendrogram(Z.10. • ‘descending’: the child with the maximum distance between its direct descendents is plotted ﬁrst. When unspeciﬁed. optional Speciﬁes the font size (in points) of the leaf labels. def llf(id): if id < n: return str(id) else: return ’[%d %d %1.

Ip] where Ik is a list of 4 independent variable coordinates corresponding to the line that represents the k’th link painted. link_color_function is called with each non-singleton id corresponding to each U-shaped link it will paint.SciPy Reference Guide. . • ‘leaves’: for each i.. the i th leaf node corresponds to an original observation. See Also: to_tree for converting a linkage matrix Z into a tree object. Converts a hierarchical clustering encoded in the matrix Z (by class scipy. where j < 2n − 1 and i < n.1. For example: dendrogram(Z. rd]) A tree node class for representing a cluster. Its has the following keys: • ‘icoords’: a list of lists [I1. • ‘dcoords’: a list of lists [I2. These are data structures and routines for representing hierarchies as tree objects. I2. left. count=1) A tree node class for representing a cluster..ClusterNode(id. • ‘ivl’: a list of labels corresponding to the leaf nodes. Returns R : dict A dictionary of data structures computed to render the dendrogram.. If j is less than n. Release 0. The function is expected to return the color to paint the link. Leaf nodes correspond to original observations. it corresponds to a non-singleton cluster. dist..cluster) 163 . The to_tree function converts a matrix returned by the linkage function into an easy-to-use tree representation.0.cluster. count]) leaves_list(Z) to_tree(Z[. while non-leaf nodes correspond to non-singleton clusters. Clustering package (scipy.. Returns a list of leaf node ids (corresponding to observation vector index) as they appear in the tree from left to right. left=None. Ip] where Ik is a list of 4 independent variable coordinates corresponding to the line that represents the k’th link painted. right. encoded as a matplotlib color string code. . ClusterNode(id[. Otherwise. H[i] == j. Methods get_count get_id get_left get_right is_leaf pre_order 3. right=None.hierarchy..10. dist=0.dev6665 When a callable function. cluster node j appears in the i th position in the left-to-right traversal of the leaves. I2. link_color_func=lambda k: colors[k]) colors the direct links below each untruncated non-singleton node k using colors[k].

name]) is_valid_linkage(Z[. and its distance is meaningless but set to 0. throw. id. throw=False.2] must be positive and no greater than n − 1. If both are None then the ClusterNode object is a leaf node. and count attribute.cluster. Parameters Z : ndarray The linkage matrix in proper form (see the linkage function documentation). The standard deviations R[:. warning. The left and right attributes point to ClusterNode objects that were combined to generate the cluster. The link counts R[:.is_valid_im(R. 164 Chapter 3. a reference to the root ClusterNode object is returned.cluster. rd : bool. Release 0. Y) num_obs_linkage(Z) Returns True if the inconsistency matrix passed is valid. Z is a linkage matrix. Note: This function is provided for the convenience of the library user. The reference r to the root ClusterNode object is returned. ClusterNodes are not used as input to any of the functions in this library.to_tree(Z. r is a reference to the root node while d is a dictionary mapping cluster ids to ClusterNode references. If a cluster id is less than n. its count must be 1. T2) is_monotonic(Z) correspond(Z. Checks the validity of a linkage matrix. name=None) Returns True if the inconsistency matrix passed is valid. dist. throw.leaves_list(Z) Returns a list of leaf node ids (corresponding to observation vector index) as they appear in the tree from left to right. See linkage for more information. Parameters Z : ndarray The hierarchical clustering encoded as a matrix.10. scipy.cluster. Returns L : ndarray The list of leaf node ids. Otherwise.0. Returns L : list The pre-order traversal. These are predicates for checking the validity of linkage and inconsistency matrices as well as for checking isomorphism of two ﬂat cluster assignments.hierarchy. The linkage Checks if a linkage matrix Z and condensed distance matrix Returns the number of original observations of the linkage matrix passed. a tuple (r.dev6665 scipy. optional When False. See linkage for more information on the assignment of cluster ids to clusters. Reference .hierarchy. warning=False.hierarchy.1] must be nonnegative. then it corresponds to a singleton cluster (leaf node). name]) is_isomorphic(T1.SciPy Reference Guide. scipy. right. rd=False) Converts a hierarchical clustering encoded in the matrix Z (by linkage) into an easy-to-use tree object. is_valid_im(R[. It must be a n by 4 numpy array of doubles. warning.d) is returned. Each ClusterNode object has a left. Determines if two different cluster assignments T1 and Returns True if the linkage passed is monotonic.

cluster) 165 .hierarchy. optional When True. warning : bool. optional When True. Clustering package (scipy. warning=False.0. The ﬁrst two columns must contain indices between 0 and 2n − 1. For a given row i.dev6665 Parameters R : ndarray The inconsistency matrix to check for validity. scipy. issues a Python warning if the linkage matrix passed is invalid.) Parameters Z : array_like Linkage matrix. Returns b : bool 3. Parameters T1 : ndarray An assignment of singleton cluster ids to ﬂat cluster ids. Release 0. throw=False.10. name=None) Checks the validity of a linkage matrix.SciPy Reference Guide. throws a Python exception if the linkage matrix passed is invalid. name : str. a cluster cannot join another cluster unless the cluster being joined has been generated. 1] ≤ i + n − 1 (i. Returns b : bool True iff the inconsistency matrix is valid. optional When True. optional When True. scipy.is_isomorphic(T1. optional This string refers to the variable name of the invalid linkage matrix.is_valid_linkage(Z.cluster. Returns b : bool True if the inconsistency matrix is valid.hierarchy. T2 : ndarray An assignment of singleton cluster ids to ﬂat cluster ids. throws a Python exception if the linkage matrix passed is invalid. A linkage matrix is valid if it is a two dimensional nd-array (type double) with n rows and 4 columns.cluster. warning : bool. name : str. throw : bool. 0 ≤ Z[i. throw : bool.1. 0] ≤ i + n − 1 and 0 ≤ Z[i. T2) Determines if two different cluster assignments T1 and T2 are equivalent. optional This string refers to the variable name of the invalid linkage matrix. issues a Python warning if the linkage matrix passed is invalid.e.

New BSD License. scipy. Parameters Z : ndarray The linkage matrix on which to perform the operation. the distance between them is no less than the distance between any previously joined clusters. Inc. • Mathematica is a registered trademark of The Wolfram Research. Parameters Z : ndarray The linkage matrix to check for correspondance. Returns b : bool A boolean indicating whether the linkage is monotonic. The linkage is monotonic if for every cluster s and t joined. scipy.cluster. They must have the same number of original observations for the check to succeed. Release 0. Parameters Z : ndarray The linkage matrix to check for monotonicity.0.num_obs_linkage(Z) Returns the number of original observations of the linkage matrix passed. This function is useful as a sanity check in algorithms that make extensive use of linkage and distance matrices that must correspond to the same set of original observations. 166 Chapter 3. scipy. References Copyright Notice Copyright (C) Damian Eads. Y) Checks if a linkage matrix Z and condensed distance matrix Y could possibly correspond to one another. Reference . Returns b : bool A boolean indicating whether the linkage matrix and distance matrix could possibly correspond to one another.hierarchy.SciPy Reference Guide.is_monotonic(Z) Returns True if the linkage passed is monotonic. Y : ndarray The condensed distance matrix to check for correspondance.correspond(Z.hierarchy. Returns n : int The number of original observations in the linkage. • MATLAB and MathWorks are registered trademarks of The MathWorks.dev6665 Whether the ﬂat cluster assignments T1 and T2 are equivalent.cluster.hierarchy. Inc.cluster. 2007-2008.10.

If the node is a leaf. i corresponds to non-singleton cluster formed at iteration i − n. count=1) A tree node class for representing a cluster. Release 0. while non-leaf nodes correspond to non-singleton clusters. If the target node is a leaf. Returns leafness : bool True if the target node is a leaf node.10. For n ≤ i < 2n − 1. 1 is returned.dev6665 class scipy. i corresponds to original observation i. For 0 ≤ i < n.1. If the node is a leaf. Returns id : int The identiﬁer of the target node. right=None. See Also: to_tree for converting a linkage matrix Z into a tree object.cluster.SciPy Reference Guide. Returns right : ClusterNode The left child of the target node. None is returned. Returns c : int The number of leaf nodes below the target node. get_left() Returns a reference to the left child tree object.ClusterNode(id. is_leaf() Returns True iff the target node is a leaf.cluster) 167 . get_right() Returns a reference to the right child tree object. left=None. The to_tree function converts a matrix returned by the linkage function into an easy-to-use tree representation. Clustering package (scipy. get_id() The identiﬁer of the target node.0. Returns left : ClusterNode The left child of the target node. Methods get_count get_id get_left get_right is_leaf pre_order get_count() The number of leaf nodes (original observations) belonging to the cluster node nd.hierarchy. Leaf nodes correspond to original observations. dist=0. 3. None is returned.

centroid(y) Performs centroid/UPGMC linkage. Returns L : list The pre-order traversal. Parameters Q : ndarray 168 Chapter 3.average(y) Performs average/UPGMA linkage on the condensed distance matrix y. func is called with the leaf node as its argument. For example. See linkage for more information on the return structure and algorithm. the result of func(n[i]) is stored in L[i]. See linkage for more information on the return structure and algorithm.cluster.hierarchy. When a leaf node is ﬁrst encountered.id) returns a list of the node ids corresponding to the leaf nodes of the tree as they appear from left to right. scipy. See the linkage function documentation for more information on its structure. and its result is appended to the list. 2. scipy.10. Release 0. See linkage for more information on the return structure and algorithm. Given the i’th leaf node in the pre-order traversal n[i].dev6665 pre_order(func=<function <lambda> at 0x31e9758>) Performs preorder traversal without recursive function calls.SciPy Reference Guide. the index of the original observation to which the node corresponds is used. The result of pdist is returned in this form.0. The following are common calling conventions: 1.Z = centroid(y) Performs centroid/UPGMC linkage on the condensed distance matrix y. See Also: linkage for advanced creation of hierarchical clusterings.hierarchy. Returns Z : ndarray A linkage matrix containing the hierarchical clustering.Z = centroid(X) Performs centroid/UPGMC linkage on the observation matrix X using Euclidean distance as the distance metric. Parameters func : function Applied to each leaf ClusterNode object in the pre-order traversal. See linkage for more information on the return structure and algorithm. the statement: ids = root. Parameters y : ndarray The upper triangular of the distance matrix.pre_order(lambda x: x. If not provided.cluster. Reference .

This is the form that pdist returns. The result of pdist is returned in this form.1. Parameters y : ndarray The upper triangular of the distance matrix. scipy.cluster) 169 . See the linkage function documentation for more information on its structure. A condensed distance matrix is a ﬂat array containing the upper triangular of the distance matrix. See the linkage function documentation for more information on its structure.hierarchy. a collection of m observation vectors in n dimensions may be passed as a m by n array. Y : ndarray (optional) Calculates the cophenetic correlation coefﬁcient c of a hierarchical clustering deﬁned by the linkage matrix Z of a set of n observations in m dimensions. Y=None) Calculates the cophenetic distances between each observation in the hierarchical clustering deﬁned by the linkage Z.hierarchy. Y is the condensed distance matrix from which Z was generated. See linkage for more information on the return structure and algorithm.SciPy Reference Guide.dev6665 A condensed or redundant distance matrix.10. {d}): • c [ndarray] The cophentic correlation distance (if y is passed). 3.cluster. The cophenetic distance between observations i and j is simply the distance between clusters s and t. See Also: linkage for advanced creation of hierarchical clusterings.0. Returns Z : ndarray A linkage matrix containing the hierarchical clustering. Suppose p and q are original observations in disjoint clusters s and t.complete(y) Performs complete complete/max/farthest point linkage on the condensed distance matrix y. Returns Z : ndarray A linkage matrix containing the hierarchical clustering. respectively and s and t are joined by a direct parent cluster u. Alternatively. scipy. Release 0. Parameters Z : ndarray The hierarchical clustering encoded as an array (see linkage function).cluster. Clustering package (scipy.cophenet(Z. Returns res : tuple A tuple (c.

Y) Checks if a linkage matrix Z and condensed distance matrix Y could possibly correspond to one another. distance_sort=False. Reference . link_color_func=None) Plots the hiearchical clustering deﬁned by the linkage Z as a dendrogram. no_plot=False. get_leaves=True. Truncation is used to condense the dendrogram. optional The p parameter for truncate_mode. no_labels=False.2] be monotonic. The dendrogram illustrates how each cluster is composed by drawing a U-shaped link between a non-singleton cluster and its children. leaf_rotation=None. Y : ndarray The condensed distance matrix to check for correspondance.dendrogram(Z. Release 0.cluster. This function is useful as a sanity check in algorithms that make extensive use of linkage and distance matrices that must correspond to the same set of original observations. Parameters Z : ndarray The linkage matrix to check for correspondance. scipy. The ij th entry is the cophenetic distance between original observations i and j.0. show_leaf_counts=True.hierarchy. otherwise crossings appear in the dendrogram.correspond(Z.hierarchy.cluster. p : int. optional The dendrogram can be hard to read when the original observation matrix from which the linkage is derived is large. p=30. It is expected that the distances in Z[:. It is also the cophenetic distance between original observations in the two children clusters.dev6665 • d [ndarray] The cophenetic distance matrix in condensed form. truncate_mode=None. leaf_font_size=None. no_leaves=False. They must have the same number of original observations for the check to succeed. color_threshold=None. scipy. Returns b : bool A boolean indicating whether the linkage matrix and distance matrix could possibly correspond to one another. The height of the top of the U-link is the distance between its children clusters. leaf_label_func=None.10. truncate_mode : str. There are several modes: • None/’none’: no truncation is performed (Default) • ‘lastp’: the last p non-singleton formed in the linkage 170 Chapter 3. show_contracted=False. Parameters Z : ndarray The linkage matrix encoding the hierarchical clustering to render as a dendrogram. count_sort=False.SciPy Reference Guide. color_list=None. orientation=’top’. See the linkage function for more information on the format of Z. labels=None.

• ‘mlab’: This corresponds to MATLAB(TM) behavior. cluster node j appears in the i th position in the left-to-right traversal of the leaves. optional For brevity. corresponding with MATLAB(TM) behavior. Release 0. all nodes are colored blue. If t is less than or equal to zero.dev6665 are the only non-leaf nodes in the linkage. and plot descendent links going downwards.0. All other non-singleton clusters are contracted into leaf nodes. If color_threshold is None or ‘default’. they correspond to to rows Z[n-p-2:end] in Z. Colors all the descendent links below a cluster node k the same color if k is the ﬁrst node below the cut threshold t. where j < 2n − 1 and i < n. optional The direction to plot the dendrogram. Otherwise. • ‘left’: plots the root at the left. The labels[i] value is the text to put under the i th leaf node only if it corresponds to an original observation and not a non-singleton cluster. For each i. the order (visually. and plot descendent links going upwards. count_sort : str or bool. get_leaves : bool. labels : ndarray. this is an n -sized list (or tuple). 3.SciPy Reference Guide. let t be the color_threshold. • ‘bottom’: plots the root at the bottom. (default).1. from left-to-right) n’s two descendent links are plotted is determined by this parameter.10. optional By default labels is None so the index of the original observation is used to label the leaf nodes. and plot descendent links going right. (not implemented yet) • ‘level’/’mtica’: no more than p levels of the dendrogram tree are displayed. which can be any of the following values: • False: nothing is done. Clustering package (scipy.cluster) 171 . • ‘ascending’/True: the child with the minimum number of original objects in its cluster is plotted ﬁrst.2]). color_threshold : double.7*max(Z[:. orientation : str. which can be any of the following strings • ‘top’: plots the root at the top. optional For each node n. and plot descendent links going left. H[i] == j. • ‘right’: plots the root at the right. the threshold is set to 0. This corresponds to Mathematica(TM) behavior. optional Includes a list R[’leaves’]=H in the result dictionary. All links connecting nodes with distances greater than or equal to the threshold are colored blue.

optional Speciﬁes the angle (in degrees) to rotate the leaf labels. no_plot : bool. leaf_label_rotation : double. to label singletons with their node id and non-singletons with their id. When unspeciﬁed. Indices k < n correspond to original observations while indices k ≥ n correspond to non-singleton clusters. leaf nodes representing k > 1 original observation are labeled with the number of observations they contain in parentheses. leaf_label_func : lambda or function. for each leaf with cluster index k < 2n − 1. no labels appear next to the leaf nodes in the rendering of the dendrogram. Note distance_sort and count_sort cannot both be True. • ‘descending’: the child with the maximum distance between its direct descendents is plotted ﬁrst.3]) 172 Chapter 3. (Default=0) leaf_font_size : int. Release 0. count. which can be any of the following values: • False: nothing is done.SciPy Reference Guide. no_labels : bool. the rotation based on the number of nodes in the dendrogram. When unspeciﬁed. R[n-id. optional When True. the order (visually. optional Speciﬁes the font size (in points) of the leaf labels.0. count. For example. optional When True.2f]’ % (id. • ‘ascending’/True: the child with the minimum distance between its direct descendents is plotted ﬁrst. optional For each node n. the ﬁnal rendering is not performed. Note distance_sort and count_sort cannot both be True. simply do: # First define the leaf label function. def llf(id): if id < n: return str(id) else: return ’[%d %d %1.dev6665 • ‘descendent’: the child with the maximum number of original objects in its cluster is plotted ﬁrst. optional When True.10. and inconsistency coefﬁcient. Reference . from left-to-right) n’s two descendent links are plotted is determined by this parameter. distance_sort : str or bool. optional When leaf_label_func is a callable function. show_leaf_counts : bool. This is useful if only the data structures computed for the rendering are needed or if matplotlib is not available. The function is expected to return a string with the label for the leaf. the size based on the number of nodes in the dendrogram.

H[i] == j. Otherwise. • ‘dcoords’: a list of lists [I2.. the i th leaf node corresponds to an original observation. it corresponds to a non-singleton cluster. leaf_label_func=llf.0. • ‘ivl’: a list of labels corresponding to the leaf nodes. Ip] where Ik is a list of 4 independent variable coordinates corresponding to the line that represents the k’th link painted. This really is only useful when truncation is used (see truncate_mode parameter). t : ﬂoat The threshold to apply when forming ﬂat clusters. Parameters Z : ndarray The hierarchical clustering encoded with the matrix returned by the linkage function. Release 0. monocrit=None) Forms ﬂat clusters from the hierarchical clustering deﬁned by the linkage matrix Z.1. t. • ‘leaves’: for each i. optional The criterion to use in forming ﬂat clusters. link_color_function is called with each non-singleton id corresponding to each U-shaped link it will paint. . encoded as a matplotlib color string code... The function is expected to return the color to paint the link. criterion=’inconsistent’. depth=2. scipy. Its has the following keys: • ‘icoords’: a list of lists [I1. If j is less than n.. cluster node j appears in the i th position in the left-to-right traversal of the leaves.cluster) 173 . criterion : str.cluster. where j < 2n − 1 and i < n. Returns R : dict A dictionary of data structures computed to render the dendrogram.10... . This can be any of the following values: 3. link_color_func : lambda/function When a callable function.dev6665 # The text for the leaf nodes is going to be big so force # a rotation of 90 degrees. I2. leaf_rotation=90) show_contracted : bool When True the heights of non-singleton nodes contracted into a leaf node are plotted as crosses along the link connecting that leaf node.SciPy Reference Guide.hierarchy. Ip] where Ik is a list of 4 independent variable coordinates corresponding to the line that represents the k’th link painted. dendrogram(Z. link_color_func=lambda k: colors[k]) colors the direct links below each untruncated non-singleton node k using colors[k]. For example: dendrogram(Z. I2.fcluster(Z. R=None. Clustering package (scipy.

Returns fcluster : ndarray An array of length n. ‘monocrit’: Forms a ﬂat cluster from a cluster node c with index i when monocrit[j] <= t. i. R.dev6665 ‘inconsistent’: If a cluster node and all its descendants have an inconsistent value less than or equal to t then all its leaf descendants belong to the same ﬂat cluster. 174 Chapter 3. to minimize the threshold t on maximum inconsistency values so that no more than 3 ﬂat clusters are formed. monocrit : ndarray. criterion=’monocrit’. When no non-singleton cluster meets this criterion. Release 0. do: MI = maxinconsts(Z. optional The maximum depth to perform the inconsistency calculation. to threshold on the maximum mean distance as computed in the inconsistency matrix R with a threshold of 0.SciPy Reference Guide.0. It has no meaning for the other criteria. monocrit[i] is the statistics upon which non-singleton i is thresholded.8 do: MR = maxRstat(Z. monocrit[i] >= monocrit[j]. Reference . R) cluster(Z. (Default) ‘distance’: Forms ﬂat clusters so that the original observations in each ﬂat cluster have no greater a cophenetic distance than t.e. given a node c with index i.10. ‘maxclust’: Finds a minimum threshold r so that the cophenetic distance between any two original observations in the same ﬂat cluster is no more than r and no more than t ﬂat clusters are formed. for all node indices j corresponding to nodes below c. monocrit=MR) ‘maxclust_monocrit’: Forms a ﬂat cluster from a non-singleton cluster node c when monocrit[i] <= r for all cluster indices i below and including c. 3) cluster(Z. Default is 2. The monocrit vector must be monotonic. monocrit must be monotonic. optional The inconsistency matrix to use for the ‘inconsistent’ criterion. T[i] is the ﬂat cluster number to which original observation i belongs.8. every node is assigned to its own cluster. optional An array of length n-1. r is minimized such that no more than t ﬂat clusters are formed. For example. For example. criterion=’maxclust_monocrit’. monocrit=MI) depth : int. R : ndarray. t=3. t=0. This matrix is computed if not provided.

method : str.. R=None) Cluster observation data using a given metric.. A one-dimensional array T of length n is returned. median centroid. metric=’euclidean’. See fcluster for descriptions. method=’single’. ‘distance’. or ‘maxclust’ cluster formation algorithms. t. T[i] is the index of the ﬂat cluster to which the original observation i belongs.dev6665 scipy.hierarchy. See distance. and 3. weighted. Release 0. optional The cut-off threshold for the cluster function or the maximum number of clusters (criterion=’maxclust’). and forms ﬂat clusters using the inconsistency method with t as the cut-off threshold. ward). R : ndarray. Parameters X : ndarray n by m data matrix with n observations in m dimensions. using the euclidean distance metric to calculate distances between original observations.fclusterdata(X.N to 0. See inconsistent for more information.(N-1) form. t : ﬂoat The threshold to apply when forming ﬂat clusters. Valid values are ‘inconsistent’ (default).0.hierarchy. criterion=’inconsistent’. Default is “single”. optional The linkage method to use (single. performs hierarchical clustering using the single linkage algorithm. optional The maximum depth for the inconsistency calculation.cluster. Returns T : ndarray A vector of length n. scipy. complete. optional Speciﬁes the criterion for forming ﬂat clusters.1. It will be computed if necessary if it is not passed. T[i] is the ﬂat cluster number to which original observation i belongs. depth : int. See linkage for more information.from_mlab_linkage(Z) Converts a linkage matrix generated by MATLAB(TM) to a new linkage matrix compatible with this module. t : double. Notes This function is similar to the MATLAB function clusterdata. criterion : str.10. depth=2. optional The distance metric for calculating pairwise distances.pdist for descriptions and linkage to verify compatibility with the linkage method. metric : str.SciPy Reference Guide. average. The conversion does two things: •the indices are converted from 1. optional The inconsistency matrix. Clustering package (scipy. Clusters the original observations in the n-by-m data matrix X (n observations in m dimensions).cluster.cluster) 175 .

Returns b : bool Whether the ﬂat cluster assignments T1 and T2 are equivalent. The linkage is monotonic if for every cluster s and t joined. R[i. Returns R : ndarray A (n − 1) by 5 matrix where the i‘th row contains the link statistics for the nonsingleton cluster i.0.3] is the inconsistency coefﬁcient. This function is useful when loading in linkages from legacy data ﬁles generated by MATLAB.is_isomorphic(T1.dev6665 •a fourth column Z[:. 2] − R[i.10.2] is the number of links included in the calculation. scipy.inconsistent(Z. T2) Determines if two different cluster assignments T1 and T2 are equivalent.hierarchy. Z : ndarray The (n − 1) by 4 matrix encoding the linkage (hierarchical clustering). the distance between them is no less than the distance between any previously joined clusters.cluster. R[i.0] and R[i. See 176 Chapter 3.hierarchy.3] is added where Z[i.is_monotonic(Z) Returns True if the linkage passed is monotonic. racZ[i. Note: This function behaves similarly to the MATLAB(TM) inconsistent function. respectively.3] is represents the number of original observations (leaves) in the non-singleton cluster i.SciPy Reference Guide. Release 0. Parameters T1 : ndarray An assignment of singleton cluster ids to ﬂat cluster ids. T2 : ndarray An assignment of singleton cluster ids to ﬂat cluster ids.cluster. 1]. linkage documentation for more information on its form. The link statistics are computed over the link heights for links d levels below the cluster i. Parameters d : int The number of links up to d levels below each non-singleton cluster. and R[i.1] are the mean and standard deviation of the link heights. Returns ZS : ndarray A linkage matrix compatible with this library.cluster. Reference . d=2) Calculates inconsistency statistics on a linkage. scipy. 0]R[i. Parameters Z : ndarray A linkage matrix generated by MATLAB(TM). scipy.hierarchy.

SciPy Reference Guide. A linkage matrix is valid if it is a two dimensional nd-array (type double) with n rows and 4 columns. optional When True. Returns b : bool True if the inconsistency matrix is valid. Parameters R : ndarray The inconsistency matrix to check for validity. a cluster cannot join another cluster unless the cluster being joined has been generated. warning=False.) Parameters Z : array_like Linkage matrix.hierarchy. throw=False.cluster. The ﬁrst two columns must contain indices between 0 and 2n − 1.dev6665 Parameters Z : ndarray The linkage matrix to check for monotonicity.is_valid_im(R.1] must be nonnegative.2] must be positive and no greater than n − 1. optional When True. Clustering package (scipy. The link counts R[:. name : str. 3. 1] ≤ i + n − 1 (i. throw=False. warning : bool. issues a Python warning if the linkage matrix passed is invalid. warning : bool. optional This string refers to the variable name of the invalid linkage matrix.10. Release 0. throws a Python exception if the linkage matrix passed is invalid. throws a Python exception if the linkage matrix passed is invalid. optional When True. optional When True.e.cluster) 177 . throw : bool. Returns b : bool True iff the inconsistency matrix is valid.hierarchy. The standard deviations R[:.1. Returns b : bool A boolean indicating whether the linkage is monotonic.0. warning=False. name=None) Checks the validity of a linkage matrix. For a given row i. scipy. name : str. issues a Python warning if the linkage matrix passed is invalid. optional This string refers to the variable name of the invalid linkage matrix. 0] ≤ i + n − 1 and 0 ≤ Z[i. scipy. name=None) Returns True if the inconsistency matrix passed is valid.is_valid_linkage(Z. throw : bool. It must be a n by 4 numpy array of doubles. 0 ≤ Z[i.cluster.

10. Returns A tuple (L. Returns L : ndarray The list of leaf node ids.cluster. M : ndarray The leader linkage node id’s stored as a k-element 1D array where k is the number of ﬂat clusters found in T. See linkage for more information.dev6665 scipy. T : ndarray The ﬂat cluster assignment vector.e. M) = leaders(Z. If i < n. this function ﬁnds the lowest cluster node i in the linkage tree Z such that: •leaf descendents belong only to ﬂat cluster j (i. and an exception will be thrown. If this condition is violated. L[j]=i is the linkage cluster node id that is the leader of ﬂat cluster with id M[j].e.leaves_list(Z) Returns a list of leaf node ids (corresponding to observation vector index) as they appear in the tree from left to right.hierarchy. T): Returns the root nodes in a hierarchical clustering corresponding to a cut deﬁned by a ﬂat cluster assignment vector T.SciPy Reference Guide. i corresponds to an original observation. otherwise it corresponds to a non-singleton cluster. T is not a valid cluster assignment vector. 178 Chapter 3. For each ﬂat cluster j of the k ﬂat clusters represented in the n-sized ﬂat cluster assignment vector T. Parameters Z : ndarray The hierarchical clustering encoded as a matrix.0. T[q]!=j for all q not in S(i)). Z is a linkage matrix. For example: if L[3]=2 and M[3]=8. scipy. the ﬂat cluster with id 8’s leader is linkage node 2. M) with : L : ndarray The leader linkage node id’s stored as a k-element 1D array where k is the number of ﬂat clusters found in T. This allows the set of ﬂat cluster ids to be any arbitrary set of k integers. T) (L. Reference .leaders(Z.hierarchy. T[p]==j for all p in S(i) where S(i) is the set of leaf ids of leaf nodes descendent with cluster node i) •there does not exist a leaf that is not descendent with i that also belongs to cluster j (i. Parameters Z : ndarray The hierarchical clustering encoded as a matrix. See the fcluster function for more information on the format of T. See linkage for more information. Release 0.cluster.

A distance matrix is maintained at each iteration.1. respectively. y must be a n sized vector where n is the number of original observations 2 paired in the distance matrix. 3] represents the number of original observations in the newly formed cluster. . the algorithm stops. At each iteration. . v) = (dist(s. At the i-th iteration. This is also called the UPGMA algorithm. When only one cluster remains in the forest. 0] and Z[i. The behavior of this function is very similar to the MATLAB(TM) linkage function. and this cluster becomes the root. . t) between two clusters s and t. Recall s and t are combined to form cluster u. Let v be any remaining cluster in the forest that is not u. (also called WPGMA) 3. metric=’euclidean’) Performs hierarchical/agglomerative clustering on the condensed distance matrix y. v) = ij d(u[i]. This is called UPGMA. 2]. and u is added to the forest. A cluster with an index less than n corresponds to one of the n original observations. • method=’weighted’ assigns d(u.linkage(y. . Suppose there are |u| original observations u[0].cluster) 179 . The fourth value Z[i. This is also known as the Nearest Point Algorithm. v[|v| − 1] in cluster v. Release 0. s and t are removed from the forest. 1] are combined to form cluster n+i. 1] is given by Z[i. The algorithm begins with a forest of clusters that have yet to be used in the hierarchy being formed. .dev6665 scipy. . Clustering package (scipy. . v[j])) for all points i in cluster u and j in cluster v.SciPy Reference Guide. v[j])) for all points i in cluster u and j in cluster v. • method=’average’ assigns d(u. .0. • method=’complete’ assigns d(u.10. u[|u| − 1] in cluster u and |v| original objects v[0]. v))/2 where cluster u was formed with cluster s and t and v is a remaining cluster in the forest.j] entry corresponds to the distance between cluster i and j in the original forest. v[j]) (|u| ∗ |v|) for all points i and j where |u| and |v| are the cardinalities of clusters u and v. clusters with indices Z[i. The d[i. • method=’single’ assigns d(u. v) = min(dist(u[i]. method=’single’. v) = max(dist(u[i]. This is also known by the Farthest Point Algorithm or Voor Hees Algorithm.cluster. When two clusters s and t from this forest are combined into a single cluster u.hierarchy. The following linkage methods are used to compute the distance d(s. A 4 by (n − 1) matrix Z is returned. the algorithm must update the distance matrix to reﬂect the distance of the newly formed cluster u with the remaining clusters in the forest. The following are methods for calculating the distance between the newly formed cluster u and each v. v) + dist(t. 0] and Z[i. The distance between clusters Z[i.

Warning: When the minimum distance pair in the forest is chosen. Alternatively. A condensed distance matrix is a ﬂat array containing the upper triangular of the distance matrix.t) like the centroid method. v) = |v| + |s| |v| + |t| |v| d(v.0.maxRstat(Z. When two clusters s and t are combined into a new cluster u. metric [str] The distance metric to use. t)2 T T T where u is the newly joined cluster consisting of clusters s and t. Release 0. method [str] The linkage algorithm to use.pdist function for a list of valid distance metrics.10. the average of centroids s and t give the new centroid u. This is also known as the incremental algorithm. R. a collection of m observation vectors in n dimensions may be passed as an m by n array. Parameters Z : ndarray The hierarchical clustering encoded as a matrix. and | ∗ | is the cardinality of its argument. scipy. the new centroid is computed over all the original objects in clusters s and t.dev6665 • method=’centroid’ assigns dist(s. v is an unused cluster in the forest.hierarchy. t)2 + d(s.SciPy Reference Guide. • method=’median’ assigns math:d(s. This implementation may chose a different minimum than the MATLAB(TM) version. This is also known as the UPGMC algorithm. d(u. The new entry d(u.cluster. This is also known as the WPGMC algorithm. • method=’ward’ uses the Ward variance minimization algorithm. The distance then becomes the Euclidean distance between the centroid of u and the centroid of a remaining cluster v in the forest. s)2 + d(v. respectively. T = |v| + |s| + |t|. there may be two or more pairs with the same minimum distance. Reference . Returns Z : ndarray The hierarchical clustering encoded as a linkage matrix. R : ndarray 180 Chapter 3. v) is computed as follows. Parameters y : ndarray A condensed or redundant distance matrix. See the Linkage Methods section below for full descriptions. When two clusters s and t are combined into a new cluster u. This is the form that pdist returns. i) Returns the maximum statistic for each non-singleton cluster and its descendents. t) = ||cs − ct ||2 where cs and ct are the centroids of clusters s and t. See the distance. See linkage for more information.

i : int The column of R to use as the statistic. See linkage for more information on the return structure and algorithm. More speciﬁcally. scipy.max() where Q(i) is the set of all node indices below and including node i. Parameters Z : ndarray The hierarchical clustering encoded as a matrix.Z = median(y) Performs median/WPGMC linkage on the condensed distance matrix y.cluster) 181 .hierarchy. MD[i] represents the maximum distance between any cluster (including singletons) below and including the node with index i.hierarchy. Clustering package (scipy. 2. scipy.1.cluster. 3. The following are common calling conventions: 1. MR[j] is the maximum over R[Q(j)-n.dev6665 The inconsistency matrix. R) Returns the maximum inconsistency coefﬁcient for each non-singleton cluster and its descendents. See linkage for more information.hierarchy.cluster. See linkage for more information on the return structure and algorithm.10. See linkage for more information on the return structure and algorithm.maxinconsts(Z.SciPy Reference Guide. Returns MI : ndarray A monotonic (n-1)-sized numpy array of doubles.cluster.maxdists(Z) Returns the maximum distance between any cluster for each non-singleton cluster. i] where Q(j) the set of all node ids corresponding to nodes below and including j. Returns MR : ndarray Calculates the maximum statistic for the i’th column of the inconsistency matrix R for each non-singleton cluster node. See linkage for more information. MD[i] = Z[Q(i)-n. 2]. scipy.Z = median(X) Performs median/WPGMC linkage on the observation matrix X using Euclidean distance as the distance metric. Release 0. R : ndarray The inconsistency matrix.0.median(y) Performs median/WPGMC linkage. Returns MD : ndarray A (n-1) sized numpy array of doubles. Parameters Z : ndarray The hierarchical clustering encoded as a matrix.

This is the form that pdist returns. scipy. Parameters Z : ndarray The linkage matrix on which to perform the operation.0. scipy.set_link_color_palette(palette) Changes the list of matplotlib color codes to use when coloring links with the dendrogram color_threshold feature.SciPy Reference Guide. See linkage for more information on the return structure and algorithm. Returns Z : ndarray The hierarchical clustering encoded as a linkage matrix.hierarchy. The order of the color codes is the order in which the colors are cycled through when color thresholding in the dendrogram.hierarchy. Release 0.hierarchy. See Also: linkage for advanced creation of hierarchical clusterings.10.cluster.single(y) Performs single/min/nearest linkage on the condensed distance matrix y. See Also: linkage for advanced creation of hierarchical clusterings. Parameters y : ndarray The upper triangular of the distance matrix.cluster. The result of pdist is returned in this form.cluster.num_obs_linkage(Z) Returns the number of original observations of the linkage matrix passed. 182 Chapter 3. Parameters palette : A list of matplotlib color codes. Reference . Returns Z : ndarray The linkage matrix. Alternatively. A condensed distance matrix is a ﬂat array containing the upper triangular of the distance matrix. Returns n : int The number of original observations in the linkage.dev6665 Parameters Q : ndarray A condensed or redundant distance matrix. scipy. a collection of m observation vectors in n dimensions may be passed as a m by n array.

rd : bool.d) is returned. See linkage for more information on the return structure and algorithm.dev6665 scipy.1.to_mlab_linkage(Z) Converts a linkage matrix Z generated by the linkage function of this module to a MATLAB(TM) compatible one. ClusterNodes are not used as input to any of the functions in this library.hierarchy.hierarchy. scipy. a reference to the root ClusterNode object is returned. its count must be 1.N indexing. optional When False. A condensed distance matrix is a ﬂat array containing the upper triangular of the distance matrix. dist.cluster) 183 . Each ClusterNode object has a left. The reference r to the root ClusterNode object is returned. 2. Parameters Z : ndarray A linkage matrix generated by this library.. Note: This function is provided for the convenience of the library user. right.to_tree(Z.cluster.hierarchy. The return linkage matrix has the last column removed and the cluster indices are converted to 1. Parameters Q : ndarray A condensed or redundant distance matrix. This is the form that 3. See linkage for more information on the assignment of cluster ids to clusters. The left and right attributes point to ClusterNode objects that were combined to generate the cluster. and its distance is meaningless but set to 0. Returns L : list The pre-order traversal. rd=False) Converts a hierarchical clustering encoded in the matrix Z (by linkage) into an easy-to-use tree object. See linkage for more information on the return structure and algorithm. id. Release 0. See linkage for more information on the return structure and algorithm.SciPy Reference Guide. scipy.Z = ward(y) Performs Ward’s linkage on the condensed distance matrix Z. If both are None then the ClusterNode object is a leaf node. Otherwise. r is a reference to the root node while d is a dictionary mapping cluster ids to ClusterNode references. a tuple (r. Returns ZM : ndarray A linkage matrix compatible with MATLAB(TM)’s hierarchical clustering functions. The following are common calling conventions: 1.10. Parameters Z : ndarray The linkage matrix in proper form (see the linkage function documentation).cluster. then it corresponds to a singleton cluster (leaf node).Z = ward(X) Performs Ward’s linkage on the observation matrix X using Euclidean distance as the distance metric. and count attribute.0.cluster. Clustering package (scipy. If a cluster id is less than n.ward(y) Performs Ward’s linkage on a condensed or redundant distance matrix.

a set of centroids. Reference . information theory terminology is often used. Each step of the k-means algorithm reﬁnes the choices of centroids to reduce distortion. 3.2 K-means clustering and vector quantization (scipy. Quantization aims to ﬁnd an encoding of vectors that reduces the expected distortion. See the linkage function documentation for more information on its structure. A vector v belongs to cluster i if it is closer to centroid i than any other centroids. the k-means algorithm is not making sufﬁcient progress and terminates. scipy.vq) K-means Clustering and Vector Quantization Module Provides routines for k-means clustering.1. The k-means algorithm takes as input the number of clusters to generate. Returns Z : ndarray The hierarchical clustering encoded as a linkage matrix. and quantizing vectors by comparing them with centroids in a code book. See Also: linkage for advanced creation of hierarchical clusterings. one for each of the k clusters. One can also deﬁne a maximum number of iterations. k. Returns Z : ndarray A linkage matrix containing the hierarchical clustering. See linkage for more information on the return structure and algorithm.hierarchy.cluster. See Also: linkage for advanced creation of hierarchical clusterings.weighted(y) Performs weighted/WPGMA linkage on the condensed distance matrix y. Alternatively. Parameters y : ndarray The upper triangular of the distance matrix. An observation vector is classiﬁed with the cluster number or centroid index of the centroid closest to it. Since vector quantization is a natural application for k-means.cluster. and a set of observation vectors to cluster.SciPy Reference Guide. we say centroid i is the dominating centroid of v. The k-means algorithm tries to minimize distortion. If v belongs to i. It returns a set of centroids.10.dev6665 pdist returns. Release 0. The result of k-means. The result of pdist is returned in this form. a collection of m observation vectors in n dimensions may be passed as a m by n array. can be used to quantize vectors. which is deﬁned as the sum of the squared distances between each observation vector and its dominating centroid. generating code books from k-means models. The centroid index or cluster index is also referred to as a “code” and the table mapping codes to centroids and vice versa is often referred as a “code book”. The change in distortion is used as a stopping criterion: when the change is lower than a threshold.0. 184 Chapter 3.

A code book is generated that can be used to quantize vectors. Release 0. we can reduce the amount of data by two thirds.. Ideally. 4. kmeans2 : A different implementation of k-means with more methods for initializing centroids. which ﬁlls up all possible 8-bit sequences.1..].. Examples 3.]]) #o0 #o1 #o2 #o3 XXX perhaps should have an axis variable here. If the image of interest was of an ocean. The code book is also sent over the wire so each 8-bit code can be translated back to a 24-bit pixel value representation.. 3. more ﬂesh tone colors would be represented in the code book. suppose we wish to compress a 24-bit color image (each pixel is represented by one byte for red. The columns are the features seen during each observation.SciPy Reference Guide. we would expect many 24-bit blues to be represented by 8-bit codes. f2 1. Before running k-means. Returns result : ndarray Contains the values in obs scaled by the standard devation of each column. trying to minimize distortion. Each feature is divided by its standard deviation across all observations to give it unit variance. Parameters obs : ndarray Each row of the array is an observation. the colors for each of the 256 possible 8-bit encoding values should be chosen to minimize distortion of the color. 2. The codebook is a k by N array where the i’th row is the centroid of code word i. it is beneﬁcial to rescale each feature dimension of the observation set with whitening. The observation vectors and centroids have the same feature dimension.]. 4.10.whiten(obs) Normalize a group of observations on a per feature basis.cluster) 185 .. 4. Running k-means with k=256 generates a code book of 256 codes.0. Learns centroids with the k-means algorithm.vq. Uses maximum number of iterations as opposed to a distortion threshold as its stopping criterion. scipy. Clustering package (scipy. kmeans : Clusters a set of observation vectors.. 2. As an example. one for blue. # obs = [[ [ [ [ f0 1. and one for green) before sending it over the web. Functions whiten : Normalize a group of observations so each feature has unit variance.dev6665 All routines expect obs to be a M by N array where the rows are the observation vectors.. 2. Instead of sending a 3-byte value for each pixel. the 8-bit centroid index (or code word) of the dominating centroid is transmitted. By using a smaller 8-bit encoding. If it was an image of a human face.. 3.]. vq : Calculate code book membership of a set of observation vectors.cluster. 3. f1 1.

[ 1.]]) #c2 Returns code : ndarray A length N array holding the code book index for each observation.]... #c1 4.88897275]. [ 1.1. 1.2]. dist : ndarray The distortion (distance) between the observation and its nearest code. 0]. 1. 2.. 3. The features in obs should have unit variance.6.7]]) >>> vq(features.88897275]]) scipy. Release 0.....cluster. Notes This currently forces 32-bit math precision for speed..69407953.]]) >>> whiten(features) array([[ 3.83066239])) 186 Chapter 3.20300046..SciPy Reference Guide..vq.]. 0. # code_book = [[ [ [ f0 1.cluster. f3 4..vq import vq >>> code_book = array([[1. [ 2.8. Anyone know of a situation where this undermines the accuracy of the algorithm? Examples >>> from numpy import array >>> from scipy.cluster.57469577.2. Each observation vector in the M by N obs array is compared with the centroids in the code book and assigned the code of the closest centroid.9.41250074. The features must be whitened ﬁrst using the whiten function or something equivalent.1.. code_book : ndarray The code book is usually generated using the k-means algorithm.5.73484692..2. code_book) Vector Quantization: assign codes from a code book to observations.. #c0 4. Reference .43684242. 0. 2.vq(obs. [ 0. [2. 3. [ 0.39456571.]]) >>> features = array([[ 1.7].2]. 1. ..7.5.. and the columns are the features of the code.1.0.2. 7.code_book) (array([1.0.2.43588989.3. Parameters obs : ndarray Each row of the NxM array is an observation.6.2. . 5. 5. The columns are the “features” seen during each observation..10.. .3.7]. f2 3...8.1.vq import whiten >>> features = array([[ 1. array([ 0.’i’). Each row of the array holds a different code.1.62102355]. 2.2. Assigns a code from a code book to each observation. 2. [ 1. The code book can be created with the k-means algorithm or a different encoding algorithm.dev6665 >>> from numpy import array >>> from scipy.2.]. which can be acheived by passing them through the whiten function.5.2.. f1 2. .0... . 0.1.5.9.

The columns are the features seen during each observation.5.. The i’th centroid codebook[i] is represented with the code i. A code is assigned to each centroid. This yields a code book mapping centroids to codes and vice versa.. Returns codebook : ndarray A k by N array of k centroids. thresh : ﬂoat. iter : int. See Also: kmeans2 a different implementation of k-means clustering with more methods for generating initial centroids but without using a distortion change threshold as a stopping criterion. This argument is ignored if initial centroids are speciﬁed with an array for the k_or_guess parameter. The initial k centroids are chosen by randomly selecting observations from the observation matrix. Parameters obs : ndarray Each row of the M by N array is an observation vector.cluster. 3. Alternatively. the change in distortion since the last iteration is less than some threshold. . whiten must be called prior to passing an observation matrix to kmeans.2.1.vq. which is also the row index of the centroid in the code_book matrix generated.cluster) 187 . [ 1. passing a k by N array speciﬁes the initial k centroids. Clustering package (scipy. k_or_guess. not necessarily the globally minimal distortion. iter=20. whiten >>> features = array([[ 1.9.SciPy Reference Guide. k_or_guess : int or ndarray The number of centroids to generate. thresh=1.vq import vq. The centroids and codes generated represent the lowest distortion seen. distortion : ﬂoat The distortion between the observations passed and the centroids generated.5]. i.3]. The k-means algorithm adjusts the centroids until sufﬁcient progress cannot be made.0.e.kmeans(obs. Distortion is deﬁned as the sum of the squared differences between the observations and the corresponding centroid.10. The features must be whitened ﬁrst with the whiten function. Release 0.cluster.2. optional Terminates the k-means algorithm if the change in distortion since the last k-means iteration is less than or equal to thresh. Examples >>> from numpy import array >>> from scipy. optional The number of times to run k-means.0000000000000001e-05) Performs k-means on a set of observation vectors forming k clusters. This parameter does not represent the number of iterations of the k-means algorithm. returning the codebook with the lowest distortion. kmeans.dev6665 scipy.

86287398].32544402.cluster.10.1..3. 0. [ 2. 2.3110306 .86287398]. iter=10.0. . [ 1.6]. . ‘points’. 188 Chapter 3. k : int or ndarray The number of clusters to form as well as the number of centroids to generate. [ 0.3110306 .5]. thresh : ﬂoat (not used yet)..1]. .1.. 0.0.8]. Available methods are ‘random’. minit=’random’.93218041. [ 1...40782893.seed((1000. ‘points’: choose k observations (rows) at random from data for the initial centroids.8]. missing=’warn’) Classify a set of observations into k clusters using the k-means algorithm.SciPy Reference Guide.0.2000)) >>> codes = 3 >>> kmeans(whitened. . .24398691]]). ...4.0.2. and ‘matrix’: ‘random’: generate k centroids from a Gaussian with mean and variance estimated from the data. Note that this differs in meaning from the iters parameter to the kmeans function.5196582527686241) scipy.0.1.dev6665 .vq. [ 0. 2.whitened[2])) >>> kmeans(whitened.codes) (array([[ 2.85684700941625547) >>> from numpy import random >>> random.kmeans2(data.02786907]]). or if a ndarray is given instead. [ 0. minit : string Method for initialization. thresh=1.0. 1....1. k. Parameters data : ndarray A M by N array of M observations in N dimensions or a length M array of M onedimensional observations.65607529].book) (array([[ 2. If minit initialization string is ‘matrix’. 0. Reference .5].0]]) >>> whitened = whiten(features) >>> book = array((whitened[0]. iter : int Number of iterations of the k-means algrithm to run. ‘uniform’: generate k observations from the data from a uniform distribution deﬁned by the data set (unsupported). [ 0.. [ 0. ‘uniform’..0000000000000001e-05... it is interpreted as initial cluster to use instead.8. Several initialization methods are included. The algorithm attempts to minimize the Euclidian distance between observations and centroids. Release 0.1. 2. [ 0. [ 0.

The vq module only supports vector quantization and the k-means algorithms. Constants (scipy. computing distance matrices from observation vectors. 3.0. Returns centroid : ndarray A k by N array of centroids found at the last iteration of k-means. calculating statistics on clusters. cutting linkages to generate ﬂat clusters.1 Mathematical constants pi golden Pi Golden ratio 3. 3.2. Its features include generating hierarchical clusters from distance matrices.constants) Physical and mathematical constants and units.SciPy Reference Guide. and other areas. compression. 3.3 Vector Quantization / Kmeans Clustering algorithms are useful in information theory. target detection.1.2.1.constants) 189 . Release 0. 3. label : ndarray label[i] is the code or index of the centroid the i’th observation is closest to. and visualizing clusters with dendrograms.dev6665 ‘matrix’: interpret the k parameter as a k by M (or length k array for one-dimensional data) array of initial centroids. communications.4 Hierarchical Clustering The hierarchy module provides functions for hierarchical and agglomerative clustering.10. Development of self-organizing maps (SOM) and other approaches is underway.2 Constants (scipy.

which.2 Physical constants c mu_0 epsilon_0 h hbar G g e R alpha N_A k sigma Wien Rydberg m_e m_p m_n speed of light in vacuum the magnetic constant µ0 the electric constant (vacuum permittivity). Examples >>> from scipy. disp]) Value in physical_constants indexed by key Unit in physical_constants indexed by key Relative precision in physical_constants indexed by key Return list of codata.value(’elementary charge’) 1.0. scipy. does not itself possess a docstring.physical_constant keys containing a given string scipy. the Planck constant h ¯ = h/(2π) h Newtonian constant of gravitation standard acceleration of gravity elementary charge molar gas constant ﬁne-structure constant Avogadro constant Boltzmann constant Stefan-Boltzmann constant σ Wien displacement law constant Rydberg constant electron mass proton mass neutron mass 0 3.constants.dev6665 3. value(key) unit(key) precision(key) find([sub.3 Constants database In addition to the above variables containing physical constants. as a dictionary literal object.2. Release 0.602176487e-019 190 Chapter 3. Reference .SciPy Reference Guide.constants also contains a database of additional physical constants.2.value(key) Value in physical_constants indexed by key Parameters key : Python string or unicode Key in dictionary physical_constants Returns value : ﬂoat Value in physical_constants corresponding to key See Also: codata Contains the description of physical_constants.10.constants import codata >>> codata.

Examples >>> from scipy. return the list of keys without printing anything. which.2.constants.96226989798e-08 scipy. Release 0. and return None.unit(key) Unit in physical_constants indexed by key Parameters key : Python string or unicode Key in dictionary physical_constants Returns unit : Python string Unit in physical_constants corresponding to key See Also: codata Contains the description of physical_constants.constants.constants import codata >>> codata.0. disp=False) Return list of codata. print the keys that are found.10. disp : bool If True.SciPy Reference Guide. By default.constants import codata >>> codata. does not itself possess a docstring. Examples >>> from scipy. does not itself possess a docstring.constants) 191 .physical_constant keys containing a given string Parameters sub : str. 3. return all keys. unicode Sub-string to search keys for. Constants (scipy. as a dictionary literal object.unit(u’proton mass’) ’kg’ scipy. which.constants.precision(key) Relative precision in physical_constants indexed by key Parameters key : Python string or unicode Key in dictionary physical_constants Returns prec : ﬂoat Relative precision in physical_constants corresponding to key See Also: codata Contains the description of physical_constants. Otherwise.find(sub=None.precision(u’proton mass’) 4. as a dictionary literal object.dev6665 scipy.

SciPy Reference Guide. Otherwise.dev6665 Returns keys : None or list If disp is False. uncertainty).physical_constants Dictionary of physical constants. unit. scipy. does not itself possess a docstring.0. of the format physical_constants[name] = (value. None is returned.constants. See Also: codata Contains the description of physical_constants. Release 0. which. the list of keys is returned. Available constants: alpha particle mass alpha particle mass energy equivalent alpha particle mass energy equivalent in MeV alpha particle mass in u alpha particle molar mass alpha particle-electron mass ratio alpha particle-proton mass ratio Angstrom star atomic mass constant atomic mass constant energy equivalent atomic mass constant energy equivalent in MeV atomic mass unit-electron volt relationship atomic mass unit-hartree relationship atomic mass unit-hertz relationship atomic mass unit-inverse meter relationship atomic mass unit-joule relationship atomic mass unit-kelvin relationship atomic mass unit-kilogram relationship atomic unit of 1st hyperpolarizablity atomic unit of 2nd hyperpolarizablity atomic unit of action atomic unit of charge atomic unit of charge density atomic unit of current atomic unit of electric dipole moment atomic unit of electric field atomic unit of electric field gradient atomic unit of electric polarizablity atomic unit of electric potential atomic unit of electric quadrupole moment atomic unit of energy atomic unit of force atomic unit of length atomic unit of magnetic dipole moment atomic unit of magnetic flux density atomic unit of magnetizability atomic unit of mass atomic unit of momentum Continued on next page 192 Chapter 3. as a dictionary literal object.10. Reference .

Release 0.constants) 193 .dev6665 Table 3.1 – continued from previous page atomic unit of permittivity atomic unit of time atomic unit of velocity Avogadro constant Bohr magneton Bohr magneton in eV/T Bohr magneton in Hz/T Bohr magneton in inverse meters per tesla Bohr magneton in K/T Bohr radius Boltzmann constant Boltzmann constant in eV/K Boltzmann constant in Hz/K Boltzmann constant in inverse meters per kelvin characteristic impedance of vacuum classical electron radius Compton wavelength Compton wavelength over 2 pi conductance quantum conventional value of Josephson constant conventional value of von Klitzing constant Cu x unit deuteron magnetic moment deuteron magnetic moment to Bohr magneton ratio deuteron magnetic moment to nuclear magneton ratio deuteron mass deuteron mass energy equivalent deuteron mass energy equivalent in MeV deuteron mass in u deuteron molar mass deuteron rms charge radius deuteron-electron magnetic moment ratio deuteron-electron mass ratio deuteron-neutron magnetic moment ratio deuteron-proton magnetic moment ratio deuteron-proton mass ratio electric constant electron charge to mass quotient electron g factor electron gyromagnetic ratio electron gyromagnetic ratio over 2 pi electron magnetic moment electron magnetic moment anomaly electron magnetic moment to Bohr magneton ratio electron magnetic moment to nuclear magneton ratio electron mass electron mass energy equivalent electron mass energy equivalent in MeV electron mass in u electron molar mass electron to alpha particle mass ratio electron to shielded helion magnetic moment ratio Continued on next page 3.10.0.SciPy Reference Guide.2. Constants (scipy.

0.1 – continued from previous page electron to shielded proton magnetic moment ratio electron volt electron volt-atomic mass unit relationship electron volt-hartree relationship electron volt-hertz relationship electron volt-inverse meter relationship electron volt-joule relationship electron volt-kelvin relationship electron volt-kilogram relationship electron-deuteron magnetic moment ratio electron-deuteron mass ratio electron-muon magnetic moment ratio electron-muon mass ratio electron-neutron magnetic moment ratio electron-neutron mass ratio electron-proton magnetic moment ratio electron-proton mass ratio electron-tau mass ratio elementary charge elementary charge over h Faraday constant Faraday constant for conventional electric current Fermi coupling constant fine-structure constant first radiation constant first radiation constant for spectral radiance Hartree energy Hartree energy in eV hartree-atomic mass unit relationship hartree-electron volt relationship hartree-hertz relationship hartree-inverse meter relationship hartree-joule relationship hartree-kelvin relationship hartree-kilogram relationship helion mass helion mass energy equivalent helion mass energy equivalent in MeV helion mass in u helion molar mass helion-electron mass ratio helion-proton mass ratio hertz-atomic mass unit relationship hertz-electron volt relationship hertz-hartree relationship hertz-inverse meter relationship hertz-joule relationship hertz-kelvin relationship hertz-kilogram relationship inverse fine-structure constant inverse meter-atomic mass unit relationship inverse meter-electron volt relationship Continued on next page 194 Chapter 3.dev6665 Table 3.SciPy Reference Guide. Release 0. Reference .10.

constants) 195 .15 K.15 K. Release 0.325 kPa) magnetic constant magnetic flux quantum Mo x unit molar gas constant molar mass constant molar mass of carbon-12 molar Planck constant molar Planck constant times c molar volume of ideal gas (273. 101.1 – continued from previous page inverse meter-hartree relationship inverse meter-hertz relationship inverse meter-joule relationship inverse meter-kelvin relationship inverse meter-kilogram relationship inverse of conductance quantum Josephson constant joule-atomic mass unit relationship joule-electron volt relationship joule-hartree relationship joule-hertz relationship joule-inverse meter relationship joule-kelvin relationship joule-kilogram relationship kelvin-atomic mass unit relationship kelvin-electron volt relationship kelvin-hartree relationship kelvin-hertz relationship kelvin-inverse meter relationship kelvin-joule relationship kelvin-kilogram relationship kilogram-atomic mass unit relationship kilogram-electron volt relationship kilogram-hartree relationship kilogram-hertz relationship kilogram-inverse meter relationship kilogram-joule relationship kilogram-kelvin relationship lattice parameter of silicon Loschmidt constant (273.325 kPa) molar volume of silicon muon Compton wavelength muon Compton wavelength over 2 pi muon g factor muon magnetic moment muon magnetic moment anomaly muon magnetic moment to Bohr magneton ratio muon magnetic moment to nuclear magneton ratio muon mass muon mass energy equivalent muon mass energy equivalent in MeV muon mass in u Continued on next page 3. 100 kPa) molar volume of ideal gas (273. Constants (scipy.2.10. 101.0.15 K.dev6665 Table 3.SciPy Reference Guide.

Reference .dev6665 Table 3.10. Release 0.0.1 – continued from previous page muon molar mass muon-electron mass ratio muon-neutron mass ratio muon-proton magnetic moment ratio muon-proton mass ratio muon-tau mass ratio natural unit of action natural unit of action in eV s natural unit of energy natural unit of energy in MeV natural unit of length natural unit of mass natural unit of momentum natural unit of momentum in MeV/c natural unit of time natural unit of velocity neutron Compton wavelength neutron Compton wavelength over 2 pi neutron g factor neutron gyromagnetic ratio neutron gyromagnetic ratio over 2 pi neutron magnetic moment neutron magnetic moment to Bohr magneton ratio neutron magnetic moment to nuclear magneton ratio neutron mass neutron mass energy equivalent neutron mass energy equivalent in MeV neutron mass in u neutron molar mass neutron to shielded proton magnetic moment ratio neutron-electron magnetic moment ratio neutron-electron mass ratio neutron-muon mass ratio neutron-proton magnetic moment ratio neutron-proton mass ratio neutron-tau mass ratio Newtonian constant of gravitation Newtonian constant of gravitation over h-bar c nuclear magneton nuclear magneton in eV/T nuclear magneton in inverse meters per tesla nuclear magneton in K/T nuclear magneton in MHz/T Planck constant Planck constant in eV s Planck constant over 2 pi Planck constant over 2 pi in eV s Planck constant over 2 pi times c in MeV fm Planck length Planck mass Planck temperature Planck time Continued on next page 196 Chapter 3.SciPy Reference Guide.

2.10. Release 0.dev6665 Table 3.1 – continued from previous page proton charge to mass quotient proton Compton wavelength proton Compton wavelength over 2 pi proton g factor proton gyromagnetic ratio proton gyromagnetic ratio over 2 pi proton magnetic moment proton magnetic moment to Bohr magneton ratio proton magnetic moment to nuclear magneton ratio proton magnetic shielding correction proton mass proton mass energy equivalent proton mass energy equivalent in MeV proton mass in u proton molar mass proton rms charge radius proton-electron mass ratio proton-muon mass ratio proton-neutron magnetic moment ratio proton-neutron mass ratio proton-tau mass ratio quantum of circulation quantum of circulation times 2 Rydberg constant Rydberg constant times c in Hz Rydberg constant times hc in eV Rydberg constant times hc in J Sackur-Tetrode constant (1 K.325 kPa) second radiation constant shielded helion gyromagnetic ratio shielded helion gyromagnetic ratio over 2 pi shielded helion magnetic moment shielded helion magnetic moment to Bohr magneton ratio shielded helion magnetic moment to nuclear magneton ratio shielded helion to proton magnetic moment ratio shielded helion to shielded proton magnetic moment ratio shielded proton gyromagnetic ratio shielded proton gyromagnetic ratio over 2 pi shielded proton magnetic moment shielded proton magnetic moment to Bohr magneton ratio shielded proton magnetic moment to nuclear magneton ratio speed of light in vacuum standard acceleration of gravity standard atmosphere Stefan-Boltzmann constant tau Compton wavelength tau Compton wavelength over 2 pi tau mass tau mass energy equivalent tau mass energy equivalent in MeV tau mass in u Continued on next page 3. Constants (scipy.0. 100 kPa) Sackur-Tetrode constant (1 K.constants) 197 . 101.SciPy Reference Guide.

1 – continued from previous page tau molar mass tau-electron mass ratio tau-muon mass ratio tau-neutron mass ratio tau-proton mass ratio Thomson cross section unified atomic mass unit von Klitzing constant weak mixing angle Wien displacement law constant {220} lattice spacing of silicon 3.0.4 Unit preﬁxes SI yotta zetta exa peta tera giga mega kilo hecto deka deci centi milli micro nano pico femto atto zepto Binary kibi mebi gibi tebi pebi exbi zebi yobi 210 220 230 240 250 260 270 280 1024 1021 1018 1015 1012 109 106 103 102 101 10−1 10−2 10−3 10−6 10−9 10−12 10−15 10−18 10−21 198 Chapter 3.2.SciPy Reference Guide.10. Release 0. Reference .dev6665 Table 3.

25 days) in seconds degree in radians arc minute in radians arc second in radians 10−3 kg 103 kg one grain in kg one pound (avoirdupous) in kg one ounce in kg one stone in kg one grain in kg one long ton in kg one short ton in kg one Troy ounce in kg one Troy pound in kg one carat in kg atomic mass constant (in kg) 3.5 Units Weight gram metric_ton grain lb oz stone grain long_ton short_ton troy_ounce troy_pound carat m_u Angle degree arcmin arcsec Time minute hour day week year Julian_year Length inch foot yard mile mil pt survey_foot survey_mile nautical_mile fermi angstrom micron au light_year parsec one inch in meters one foot in meters one yard in meters one mile in meters one mil in meters one point in meters one survey foot in meters one survey mile in meters one nautical mile in meters one Fermi in meters one Ångström in meters one micron in meters one astronomical unit in meters one light year in meters one parsec in meters one minute in seconds one hour in seconds one day in seconds one week in seconds one year (365 days) in seconds one Julian year (365.2.dev6665 3.0. Release 0.constants) 199 . Constants (scipy.SciPy Reference Guide.10.2.

200 Chapter 3.dev6665 Pressure atm bar torr psi Area hectare acre Volume liter gallon gallon_imp fluid_ounce fluid_ounce_imp bbl Speed kmh mph mach knot kilometers per hour in meters per second miles per hour in meters per second one Mach (approx.SciPy Reference Guide. Reference ..constants. Returns K : ﬂoat or array of ﬂoats Equivalent Kelvin temperature(s).C2K(C) Convert Celsius to Kelvin Parameters C : array_like Celsius temperature(s) to be converted. 1 atm) in meters per second one knot in meters per second one liter in cubic meters one gallon (US) in cubic meters one gallon (UK) in cubic meters one ﬂuid ounce (US) in cubic meters one ﬂuid ounce (UK) in cubic meters one barrel in cubic meters one hectare in square meters one acre in square meters standard atmosphere in pascals one bar in pascals one torr (mmHg) in pascals one psi in pascals Temperature zero_Celsius degree_Fahrenheit C2K(C) K2C(K) F2C(F) C2F(C) F2K(F) K2F(K) zero of Celsius scale in Kelvin one Fahrenheit (only differences) in Kelvins Convert Celsius to Kelvin Convert Kelvin to Celsius Convert Fahrenheit to Celsius Convert Celsius to Fahrenheit Convert Fahrenheit to Kelvin Convert Kelvin to Fahrenheit scipy. Release 0. at 15 °C.0.10.

.dev6665 Notes Computes K = C + zero_Celsius where zero_Celsius = 273.constants) 201 .15]) scipy. (the absolute value of) temperature “absolute zero” as measured in Celsius.0.constants. 40.K2C(K) Convert Kelvin to Celsius Parameters K : array_like Kelvin temperature(s) to be converted.zero_Celsius where zero_Celsius = 273.15.constants import F2C >>> F2C(np.array([233.array([-40.44444444]) scipy.constants import K2C >>> K2C(np. Examples >>> from scipy.]) scipy.array([-40. (the absolute value of) temperature “absolute zero” as measured in Celsius. i.constants.C2F(C) Convert Celsius to Fahrenheit Parameters C : array_like 3. Returns C : ﬂoat or array of ﬂoats Equivalent Celsius temperature(s). . 40..15.10. Notes Computes C = K . Returns C : ﬂoat or array of ﬂoats Equivalent Celsius temperature(s).32) / 1. Constants (scipy.constants.15.0])) array([ 233.SciPy Reference Guide.F2C(F) Convert Fahrenheit to Celsius Parameters F : array_like Fahrenheit temperature(s) to be converted. i. Release 0.constants.15])) array([-40.0])) array([-40.2.constants. Notes Computes C = (F .e.8. Examples >>> from scipy. 313. 4. 313. Examples >>> from scipy.e.15.constants import C2K >>> C2K(np. 40..constants.

104])) array([ 233.32)/1.]) scipy.array([-40.8 * C + 32.SciPy Reference Guide. Examples 202 Chapter 3.dev6665 Celsius temperature(s) to be converted. Returns K : ﬂoat or array of ﬂoats Equivalent Kelvin temperature(s).F2K(F) Convert Fahrenheit to Kelvin Parameters F : array_like Fahrenheit temperature(s) to be converted.10. i.zero_Celsius) + 32 where zero_Celsius = 273.array([-40. Notes Computes F = 1. Reference .15]) scipy.constants import F2K >>> F2K(np. Returns F : ﬂoat or array of ﬂoats Equivalent Fahrenheit temperature(s). Notes Computes F = 1. Examples >>> from scipy.constants. i.8 * (K .15.K2F(K) Convert Kelvin to Fahrenheit Parameters K : array_like Kelvin temperature(s) to be converted. 40.constants. Notes Computes K = (F .constants.e. Returns F : ﬂoat or array of ﬂoats Equivalent Fahrenheit temperature(s).0.constants.. Release 0.. (the absolute value of) temperature “absolute zero” as measured in Celsius.15..constants import C2F >>> C2F(np. (the absolute value of) temperature “absolute zero” as measured in Celsius. Examples >>> from scipy.e.15. 104.0])) array([ -40. 313.8 + zero_Celsius where zero_Celsius = 273.

SciPy Reference Guide. Returns nu : ﬂoat or array of ﬂoats Equivalent optical frequency.constants) 203 . 313.00000000e+00]) scipy.]) Energy eV calorie calorie_IT erg Btu Btu_th ton_TNT Power hp Force dyn lbf kgf Optics lambda2nu(lambda_) nu2lambda(nu) Convert wavelength to optical frequency Convert optical frequency to wavelength.15])) array([ -40.lambda2nu(lambda_) Convert wavelength to optical frequency Parameters lambda : array_like Wavelength(s) to be converted.. the (vacuum) speed of light in meters/second.constants. 104. Constants (scipy.dev6665 >>> from scipy.10.constants import K2F >>> K2F(np..constants.0.constants import lambda2nu >>> lambda2nu(np.e.nu2lambda(nu) Convert optical frequency to wavelength.constants. i.0. 1956) in Joules one erg in Joules one British thermal unit (International Steam Table) in Joules one British thermal unit (thermochemical) in Joules one ton of TNT in Joules scipy.constants. speed_of_light))) array([ 2.array([233.15. Examples >>> from scipy. Release 0. one dyne in newtons one pound force in newtons one kilogram force in newtons one horsepower in watts one electron volt in Joules one calorie (thermochemical) in Joules one calorie (International Steam Table calorie. 1.99792458e+08.array((1.2. Notes Computes nu = c / lambda where c = 299792458. 3.

shape[axis]. overwrite_x=0) -> y Return inverse multi-dimensional discrete Fourier transform of 2-D discrete Fourier transform. axis.y(-(n1)/2)..constants import nu2lambda >>> nu2lambda(np. n.... Discrete Fourier transform of a real sequence. overwrite_x]) rfft(x[. shape=None.y(-n/2). 2-D discrete inverse Fourier transform of real or complex sequence.fftpack... x is truncated. overwrite_x]) irfft(x[. If n<x.00000000e+00]) 3. Release 0. Examples >>> from scipy. overwrite_x=0) -> y scipy.. Notes Computes lambda = c / nu where c = 299792458. n : int.y(-1)] if n is even [y(0). n. i. overwrite_x]) ifftn(x[.0. optional If True the contents of x can be destroyed. Returns lambda : ﬂoat or array of ﬂoats Equivalent wavelength(s). speed_of_light))) array([ 2.10. axes=None. axis. axes. overwrite_x]) fftn(x[.0.fftpack) 3. shape. the (vacuum) speed of light in meters/second....SciPy Reference Guide. x is zero-padded..3. axes.y(1). overwrite_x]) ifft(x[.. overwrite_x]) ifft2(x[.array((1.shape[axis].e. overwrite_x]) fft2(x[. optional Axis along which the fft’s are computed. fftn(x.y(n/2-1). (Default n=x.. axis=-1.dev6665 Parameters nu : array_like Optical frequency to be converted. n=None.constants. irfft(x. (default=-1) overwrite_x : bool. axes.y((n-1)/2). n. optional Length of the Fourier transform.y(1).. overwrite_x=0) Return discrete Fourier transform of arbitrary type sequence x. 1.y(-1)] if n is odd 204 Chapter 3. Reference If . shape. (default=False) Returns z : complex ndarray with the elements: [y(0).shape[axis]). n>x. axis. shape.1 Fast Fourier transforms fft(x[..3 Fourier transforms (scipy. axes. n.fft(x.99792458e+08. overwrite_x]) Return discrete Fourier transform of arbitrary type sequence x. axis : int. axis. n=None. Return discrete inverse Fourier transform of real or complex sequence. axis=-1. Parameters x : array-like array to fourier transform. shape.

fftpack. optional Length of the inverse Fourier transform..n_1-1..fftpack) 205 .. -3...3.e-15) #within numerical accuracy. shape=None.arange(5) >>> np. So for an 8-point transform. If n > x. axes=None. .abs(x-fft(ifft(x))<1. The returned array contains y[j_1.fftn(x. This is most efﬁcient for n a power of two.. axis : int. overwrite_x : bool. -1]. k_d=0. 2.ifft(x. in order of decreasingly negative frequency. scipy.. overwrite_x=0) fftn(x. x is truncated. axes=None. 3. optional Axis along which the ifft’s are computed... -2. n=None. y(1). the frequencies of the result are [ 0. True scipy. x is zero-padded. n : int.. the default is over the last axis (i. See Also: ifft Inverse FFT rfft FFT of a real sequence Notes The packing of the result is “standard”: If A = fft(a.e.dev6665 where y(j) = sum[k=0. overwrite_x=0) Return discrete inverse Fourier transform of real or complex sequence.shape[axis].d] exp(-sqrt(-1)*2*pi/n_i * j_i * k_i) 3.fftpack. j = 0. 1.mean(). Parameters x : array_like Transformed data to invert.arange(n)/n)). A[1:n/2+1] contains the positive-frequency terms. axis=-1.10.shape[axis]. The default results in n = x.. the default is False. axis=-1). optional If True the contents of x can be destroyed.. 4..n-1 Note that y(-j) = y(n-j).n-1] x[k] * exp(-sqrt(-1)*j*k* 2*pi/n). Examples >>> x = np.SciPy Reference Guide. y(n-1) where y(j) = (x * exp(2*pi*sqrt(-1)*j*np. n)...all(np. then A[0] contains the zero-frequency term.. and A[n/2+1:] contains the negative-frequency terms.j_d] = sum[k_1=0.n_d-1] x[k_1.k_d] * prod[i=1.shape[axis]. Release 0... The returned complex array contains y(0). Fourier transforms (scipy. overwrite_x=0) -> y Return multi-dimensional discrete Fourier transform of arbitrary type sequence x.0. If n < x. shape=None.conjugate()..

0.....n_d-1] x[k_1. n_i-j_i.] = y[.. scipy. If shape[i]<x.conjugate(). Release 0.j_d] = 1/p * sum[k_1=0. overwrite_x=0) 2-D discrete inverse Fourier transform of real or complex sequence.shape.10.d] n_i... the contents of x can be destroyed. The returned real arrays contains: 206 Chapter 3.. n=None.. axes=(-2. ifft scipy. scipy.. Reference .]...shape.SciPy Reference Guide. . shape=None. See Also: fftn for detailed information. See Also: fftn for detailed information.ifft2(x. n = x. Note that y[. Return inverse two-dimensional discrete Fourier transform of arbitrary type sequence x.shape..dev6665 where d = len(x.fftpack.shape) and n = x. shape=None.d] exp(sqrt(-1)*2*pi/n_i * j_i * k_i) where d = len(x.fftpack. . axes=(-2.. overwrite_x=0) Discrete Fourier transform of a real sequence.k_d] * prod[i=1. and p = prod[i=1..axis=0). overwrite_x=0) Return inverse multi-dimensional discrete Fourier transform of arbitrary type sequence x.. scipy.rfft(x.shape[i]..fftpack. If shape is not speciﬁed then shape=take(x. overwrite_x=0) 2-D discrete Fourier transform. The returned array contains: y[j_1.n_1-1. Notes: y == fftn(ifftn(y)) within numerical accuracy.fft2(x. See ifft for more information.ifftn(x. -j_i. k_d=0. then the i-th dimension is truncated to desired length shape[i]. Return the two-dimensional discrete Fourier transform of the 2-D argument x. axes=None. axis=-1. ..shape[i] then the i-th dimension is padded with zeros. See Also: fft2.fftpack. axes The transform is applied along the given axes of the input array (or the newly constructed array if shape argument was used).. -1).. shape=None... Optional input: shape Deﬁnes the shape of the Fourier transform.. -1).shape). overwrite_x If set to true. If shape[i]>x. For description of parameters see fftn.axes.

y == rfft(irfft(y)). The contents of x is interpreted as the output of rfft(.n/2-1] (x[2*k-1]+sqrt(-1)*x[2*k]) • exp(sqrt(-1)*j*k* 2*pi/n) • c. if n > x.Im(y(1)). axis : int. n : int.c..Im(y(1)).irfft(x.. x is zero-padded.n-1 Note that y(-j) == y(n-j). The returned real array contains [y(0)..shape[axis]. Fourier transforms (scipy..fftpack) 207 . n=None.dev6665 [y(0). axis=-1. overwrite_x : bool. The default is the last axis.SciPy Reference Guide. See Also: fft. real-valued The data to tranform. If n is not speciﬁed (the default) then n = x. optional The axis along which the transform is applied.fftpack. overwrite_x=0) -> y Return inverse discrete Fourier transform of real sequence x.0..(n-1)/2] (x[2*k-1]+sqrt(-1)*x[2*k]) • exp(sqrt(-1)*j*k* 2*pi/n) 3.10.y(1).. Default is False.Re(y(n/2))] [y(0).basic Notes Within numerical accuracy. x is truncated..n-1] x[k] * exp(-sqrt(-1)*j*k*2*pi/n) j = 0. irfft.fftpack. scipy.conjugate(). If n < x.3. optional If set to true..Re(y(1)). axis=-1. Release 0. optional Deﬁnes the length of the Fourier transform. n=None... the contents of x can be overwritten.. overwrite_x=0) irfft(x. scipy.shape[axis].) function..Re(y(1))...shape[axis]..Im(y(n/2))] if n is even if n is odd where y(j) = sum[k=0.y(n-1)] where for n is even y(j) = 1/n (sum[k=1.. Parameters x : array_like.Re(y(n/2)).. + x[0] + (-1)**(j) x[n-1]) and for n is odd y(j) = 1/n (sum[k=1.

fftpack. period=2*pi) -> y hilbert(x) -> y ihilbert(x) -> y cs_diff(x. If x_j and y_j are Fourier coefﬁcients of periodic functions x and y. _cache]) shift(x. b. period. order) * x_j y_0 = 0 if order is not 0. Reference . b.0. period=2*pi) -> y itilbert(x. period=2*pi) -> y Return h-Tilbert transform of a periodic sequence x. period=2*pi) -> y shift(x.b)-sinh/cosh pseudo-derivative of a periodic sequence x.SciPy Reference Guide. period=2*pi) -> y scipy.dev6665 • c. _cache]) diff(x. h[. b. b[. period=2*pi) -> y cc_diff(x. _cache={}) diff(x. _cache]) hilbert(x[. a. then integration is carried out under the assumption that x_0==0. order=1.fftpack.axis=0)=0 then diff(diff(x. order=1. Optional input: see rfft. denotes complex conjugate of preceeding expression.2 Differential and pseudo-differential operators diff(x[. h. a. _cache]) sc_diff(x. h. Default is 2*pi. order. period.tilbert(x. period=2*pi) -> y Return (a. a[. a.-k)==x (within numerical accuracy) For odd order and even len(x).k). b[. _cache]) tilbert(x. then y_j = sqrt(-1)*coth(j*h*2*pi/period) * x_j y_0 = 0 Input: h Deﬁnes the parameter of the Tilbert transform. + x[0]) c.__doc__ 3. period. period=None. then y_j = pow(sqrt(-1)*j*2*pi/period. 208 Chapter 3. _cache]) ss_diff(x. Optional input: order The order of differentiation. Notes: If sum(x. a. period=None. period The assumed period of the sequence. a. h. If x_j and y_j are Fourier coefﬁcients of periodic functions x and y. a.c. _cache]) itilbert(x. _cache]) ihilbert(x) cs_diff(x. period=2*pi) -> y tilbert(x. period. scipy. a. respectively.c. period=2*pi) -> y Return k-th derivative (or integral) of a periodic sequence x. period. ss_diff(x. Release 0. period.10. b[. period. h[.diff(x. _cache={}) tilbert(x. b[. respectively.3. Default order is 1. If order is negative. order=1. the Nyquist mode is taken zero. _cache]) cc_diff(x. period. h. a.

b Deﬁnes the parameters of the cosh/sinh pseudo-differential operator.itilbert(x.b)-cosh/sinh pseudo-derivative of a periodic sequence x. Notes: If sum(x.fftpack) 209 . Release 0. 3. h.10.fftpack. b. If x_j and y_j are Fourier coefﬁcients of periodic functions x and y. then y_j = -sqrt(-1)*tanh(j*h*2*pi/period) * x_j y_0 = 0 Optional input: see tilbert.ihilbert(x) ihilbert(x) -> y Return inverse Hilbert transform of a periodic sequence x. period=2*pi) -> y Return inverse h-Tilbert transform of a periodic sequence x. a. scipy.3.0. If x_j and y_j are Fourier coefﬁcients of periodic functions x and y. For even len(x). Default period is 2*pi.hilbert(x. scipy.__doc__ scipy. respectively. Fourier transforms (scipy. h. _cache={}) hilbert(x) -> y Return Hilbert transform of a periodic sequence x. _cache={}) itilbert(x. If x_j and y_j are Fourier coefﬁcients of periodic functions x and y. a. _cache={}) cs_diff(x. respectively.fftpack. b. the Nyquist mode of x is taken zero.dev6665 period The assumed period of the sequence. then y_j = -sqrt(-1)*cosh(j*a*2*pi/period)/sinh(j*b*2*pi/period) * x_j y_0 = 0 Input: a.fftpack. If x_j and y_j are Fourier coefﬁcients of periodic functions x and y.fftpack. period=2*pi) -> y Return (a. respectively.cs_diff(x. the Nyquist mode of x is taken zero. then y_j = sqrt(-1)*sign(j) * x_j y_0 = 0 Notes: If sum(x.axis=0)==0 then hilbert(ihilbert(x)) == x For even len(x). then y_j = -sqrt(-1)*sign(j) * x_j y_0 = 0 scipy. period=None. respectively.axis=0)==0 and n=len(x) is odd then tilbert(itilbert(x)) == x If 2*pi*h/period is approximately 10 or larger then numerically tilbert == hilbert (theoretically oo-Tilbert == Hilbert). period=None.SciPy Reference Guide.

SciPy Reference Guide.a.dev6665 period The period of the sequence. b.a) == x scipy. then y_j = cosh(j*a*2*pi/period)/cosh(j*b*2*pi/period) * x_j Input: 210 Chapter 3.b).b). Notes sc_diff(cs_diff(x. a. a.a) == x For even len(x). Default is 2*pi. respectively. a. period=2*pi) -> y Return (a. scipy.b)-sinh/sinh pseudo-derivative of a periodic sequence x. If x_j and y_j are Fourier coefﬁcients of periodic functions x and y.b. a.fftpack.ss_diff(x. If x_j and y_j are Fourier coefﬁcients of periodic functions x and y. respectively.fftpack. b. then y_j = sinh(j*a*2*pi/period)/sinh(j*b*2*pi/period) * x_j y_0 = a/b * x_0 Input: a. period=2*pi) -> y Return (a. _cache={}) cc_diff(x. b.b. Notes: For even len(x).10.0. Default is 2*pi. Default period is 2*pi. optional The period of the sequence x. a. b. period : ﬂoat. the Nyquist mode of x is taken zero.a. If x_j and y_j are Fourier coefﬁcients of periodic functions x and y.sc_diff(x. b. _cache={}) ss_diff(x. period=None. period The period of the sequence x. the Nyquist mode of x is taken as zero. _cache={}) Return (a.cc_diff(x. Release 0. then: y_j = sqrt(-1)*sinh(j*a*2*pi/period)/cosh(j*b*2*pi/period) * x_j y_0 = 0 Parameters x : array_like Input array.b : ﬂoat Deﬁnes the parameters of the sinh/cosh pseudo-differential operator.b)-sinh/cosh pseudo-derivative of a periodic sequence x. period=None. respectively.b)-cosh/cosh pseudo-derivative of a periodic sequence x.b Deﬁnes the parameters of the sinh/sinh pseudo-differential operator. scipy. a. Reference . Notes: ss_diff(ss_diff(x.fftpack. period=None.

b Deﬁnes the parameters of the sinh/sinh pseudo-differential operator. 3. Default period is 2*pi. Return the Discrete Fourier Transform sample frequencies.0) -> f scipy. axes : int or shape tuple. axes]) ifftshift(x[.dev6665 a. d=1. axes=None) Shift the zero-frequency component to the center of the spectrum. d]) rfftfreq(n[.SciPy Reference Guide. Notes: cc_diff(cc_diff(x. Default is None.0. Release 0. respectively. This function swaps half-spaces for all axes listed (defaults to all). axes]) fftfreq(n[. d]) Shift the zero-frequency component to the center of the spectrum. Optional input: period The period of the sequence x. period=None. Note that y[0] is the Nyquist component only if len(x) is even. Default is 2*pi. Fourier transforms (scipy. See Also: ifftshift The inverse of fftshift. rfftfreq(n. Parameters x : array_like Input array. period=2*pi) -> y Shift periodic sequence x by a: y(u) = x(u+a). 3. then y_j = exp(j*a*2*pi/period*sqrt(-1)) * x_f Optional input: period The period of the sequences x and y.10. _cache={}) shift(x.fftshift(x. which shifts all axes.fftpack.3 Helper functions fftshift(x[. If x_j and y_j are Fourier coefﬁcients of periodic functions x and y. a.b. The inverse of fftshift.3.fftpack. optional Axes over which to shift.fftpack) 211 .b).3.a) == x scipy. Returns y : ndarray The shifted array.shift(x.a. a.

-2.fft. 2. Reference .].. -4... . which shifts all axes. d=1.dev6665 Examples >>> freqs = np.0) Return the Discrete Fourier Transform sample frequencies. The returned ﬂoat array contains the frequency bins in cycles/unit (with zero at the start) given a window length n and a sample spacing d: f = [0. -4. . axes=(1.fftfreq(n... [-3. 3..0. -1.fftshift(freqs)) array([[ 0. -4..fftshift(freqs.reshape(3..fft. 2. .)) array([[ 2.]) >>> np. 3) >>> freqs array([[ 0. -2..reshape(3... -n/2. .fft.].. -1.]]) >>> np..fft. 0. -4. [-3.fftpack.fft.. Returns y : ndarray The shifted array.ifftshift(np.fftfreq(9. -1.. Examples >>> freqs = np... [ 3...fft. axes : int or shape tuple. (n-1)/2.. See Also: fftshift Shift zero-frequency component to the center of the spectrum. n/2-1.. [ 3.. 0. 4. -1] / (d*n) if n is even if n is odd 212 Chapter 3.fftfreq(10. -1] / (d*n) f = [0.. optional Axes over which to calculate..... 1.. Release 0.. 0.. 4. -2.]]) scipy... -1. 3.. 1. 2.. 1. d=1.. axes=None) The inverse of fftshift..].. -5. 1. 2.10.fftshift(freqs) array([-5. -3.].fftfreq(9. 4. 3) >>> freqs array([[ 0.]) Shift the zero-frequency component only along the second axis: >>> freqs = np. [-4... 4. Defaults to None.. -1.ifftshift(x. -2. -3... 1. [ 3.]..]]) >>> np.]]) scipy. -4.]. [-3..1) >>> freqs array([ 0. -(n-1)/2. 2. -2.]. -2... [-1. 1...SciPy Reference Guide. 4../9). 1.fftpack.. 1.fft./9).. d=1.]. 3. -3... 4. Parameters x : array_like Input array..

convolve) convolve convolve_z init_convolution_kernel destroy_convolve_cache convolve .1.Function signature: y = convolve(x. d : scalar Sample spacing.1. 6.. Returns out : ndarray The array of length n.0) -> f DFT sample frequencies (for usage with rfft.omega_imag. 3.1 >>> freq = np. .0.fft(signal) >>> n = signal.n/2]/(d*n) if n is odd 3.fft.10. 3.5 .n/2.n/2-1.size >>> timestep = 0. 8.1. -1.irfft).overwrite_x]) Required arguments: x : input rank-1 array(‘d’) with bounds (n) omega : input rank-1 array(‘d’) with bounds (n) Optional arguments: overwrite_x := 0 input int swap_real_imag := 0 input int Return objects: y : rank-1 array(‘d’) with bounds (n) and x storage scipy. d=timestep) >>> freq array([ 0.Function signature: destroy_convolve_cache . 5]. d=1.fft.75.[swap_real_imag.n/2-1. 4.dev6665 Parameters n : int Window length.n/2-1.4 Convolutions (scipy. -5.3. -3... 1.convolve.Function signature: scipy..1.n/2-1.convolve convolve .75.fftpack...25]) scipy. Release 0.25.fftfreq(n.2.5 .fftpack) 213 ..fftpack.3. . dtype=float) >>> fourier = np. 0. Examples >>> signal = np.convolve_z convolve_z .2.Function signature: init_convolution_kernel .fftpack.rfftfreq(n. -2.Function signature: convolve_z . 2. containing the sample frequencies.array([-2..2.omega.0) rfftfreq(n.Function signature: y = convolve_z(x.convolve.fftpack. The returned ﬂoat array contains the frequency bins in cycles/unit (with zero at the start) given a window length n and a sample spacing d: f = [0.omega_real.[overwrite_x]) 3. Fourier transforms (scipy.SciPy Reference Guide. 1. d=1.n/2]/(d*n) if n is even f = [0.2.

_fftpack.3.kernel_func_extra_args]) Required arguments: n : input int kernel_func : call-back function Optional arguments: d := 0 input int kernel_func_extra_args := () input tuple zero_nyquist := d%2 input int Return objects: omega : rank-1 array(‘d’) with bounds (n) Call-back functions: def kernel_func(k): return kernel_func Required arguments: k : input int Return objects: kernel_func : ﬂoat scipy.Function signature: scipy.Function signature: y = drfft(x.Function signature: omega = init_convolution_kernel(n.5 Other (scipy.drfft drfft . Release 0.Function signature: destroy_drfft_cache ._fftpack) drfft zfft zrfft zfftnd destroy_drfft_cache destroy_zfft_cache destroy_zfftnd_cache drfft .Function signature: zfft .[n.convolve.fftpack.zero_nyquist. Reference .overwrite_x]) Required arguments: x : input rank-1 array(‘d’) with bounds (*) Optional arguments: overwrite_x := 0 input int n := size(x) input int direction := 1 input int normalize := (direction<0) input int Return objects: y : rank-1 array(‘d’) with bounds (*) and x storage 214 Chapter 3.Function signature: destroy_zfftnd_cache .10.0.destroy_convolve_cache destroy_convolve_cache .convolve.Function signature: zfftnd .Function signature: destroy_convolve_cache() 3.fftpack.[d.dev6665 Required arguments: x : input rank-1 array(‘d’) with bounds (n) omega_real : input rank-1 array(‘d’) with bounds (n) omega_imag : input rank-1 array(‘d’) with bounds (n) Optional arguments: overwrite_x := 0 input int Return objects: y : rank-1 array(‘d’) with bounds (n) and x storage scipy.init_convolution_kernel init_convolution_kernel .SciPy Reference Guide.Function signature: destroy_zfft_cache .kernel_func.Function signature: zrfft .fftpack.normalize.fftpack.direction.

destroy_drfft_cache destroy_drfft_cache .fftpack) 215 .direction._fftpack.overwrite_x]) Required arguments: x : input rank-1 array(‘D’) with bounds (*) Optional arguments: overwrite_x := 0 input int s := old_shape(x.Function signature: y = zfft(x.zfftnd zfftnd .normalize.fftpack.SciPy Reference Guide. Fourier transforms (scipy.Function signature: destroy_drfft_cache() scipy._fftpack._fftpack.fftpack._fftpack.normalize.10.destroy_zfftnd_cache destroy_zfftnd_cache .zrfft zrfft .dev6665 scipy.direction.destroy_zfft_cache destroy_zfft_cache .Function signature: destroy_zfft_cache() scipy.fftpack.3.zfft zfft .overwrite_x]) Required arguments: x : input rank-1 array(‘D’) with bounds (*) Optional arguments: overwrite_x := 1 input int n := size(x) input int direction := 1 input int normalize := (direction<0) input int Return objects: y : rank-1 array(‘D’) with bounds (*) and x storage scipy.j++) input rank-1 array(‘i’) with bounds (r) direction := 1 input int normalize := (direction<0) input int Return objects: y : rank-1 array(‘D’) with bounds (*) and x storage scipy.normalize.fftpack.overwrite_x]) Required arguments: x : input rank-1 array(‘D’) with bounds (*) Optional arguments: overwrite_x := 0 input int n := size(x) input int direction := 1 input int normalize := (direction<0) input int Return objects: y : rank-1 array(‘D’) with bounds (*) and x storage scipy.direction.[n.[n.Function signature: destroy_zfftnd_cache() 3._fftpack.fftpack.[s.Function signature: y = zrfft(x.Function signature: y = zfftnd(x.0._fftpack. Release 0.fftpack.

Romberg integration of a callable function or method.. Parameters func : function A Python function or method to integrate. it is integrated along the axis corresponding to the ﬁrst argument. args=(). hfun. .quad_explain() for more information. Returns y : ﬂoat The integral of func from a to b. b..10. b : ﬂoat Upper limit of integration (use scipy.quad(func. Compute a double integral. rtol. Release 0.integrate) 3. a.. qfun. points=None. Integrate func from a to b (possibly inﬁnite interval) using a technique from the Fortran library QUADPACK. a. .4899999999999999e-08. args. epsabs=1. infodict : dict a dictionary containing additional information. optional extra arguments to pass to func full_output : int Non-zero to return a dictionary of integration information. wopts=None. a. explain : : 216 Chapter 3. full_output=0. args.4 Integration and ODEs (scipy. tol..0. gfun. a..Inf for -inﬁnity)..4899999999999999e-08. args : tuple. a.]) Compute a deﬁnite integral.4. a : ﬂoat Lower limit of integration (use -scipy.integrate.]) romberg(function. args. .integrate. n]) quadrature(func. args. b[. weight=None.1 Integrating functions. given function object quad(func. warning messages are also suppressed and the message is appended to the output tuple. limlst=50) Compute a deﬁnite integral. abserr : ﬂoat an estimate of the absolute error in the result. b[. tol.dev6665 3.integrate. a. If func takes many arguments. args. b[. epsrel=1. Use the keyword argument args to pass the other arguments.]) dblquad(func. a. gfun.. Run scipy. wvar=None. Compute a deﬁnite integral using ﬁxed-tolerance Gaussian quadrature. hfun[.integrate.quad_explain() for more information on the more esoteric inputs and outputs. scipy. rfun) fixed_quad(func.. rtol.]) tplquad(func. b. full_output. Compute a deﬁnite integral using ﬁxed-order Gaussian quadrature.integrate. b[. limit=50. Run scipy. If non-zero. maxp1=50.Inf for +inﬁnity). Compute a triple (deﬁnite) integral. . message : : a convergence message. b. Reference .SciPy Reference Guide.

maxp1 : : An upper bound on the number of Chebyshev moments. limlst : : Upper bound on the number of cylces (>=3) for use with a sinusoidal weighting and an inﬁnite end-point. wvar : : variables for use with weighting functions. Release 0. it contains an explanation of the codes in infodict[’ierlst’] Other Parameters epsabs : : absolute error tolerance. trapz. discontinuities).dev6665 appended only with ‘cos’ or ‘sin’ weighting and inﬁnite integration limits. The sequence does not have to be sorted.333333333333332. 2.4. romb scipy. points : : a sequence of break points in the bounded integration interval where local difﬁculties of the integrand may occur (e. singularities.0.SciPy Reference Guide. weight : : string indicating weighting function.special for coefﬁcients and roots of orthogonal polynomials Examples Calculate 4 0 x2 dx and compare with an analytic result >>> from scipy import integrate >>> x2 = lambda x: x**2 >>> integrate.g.integrate) 217 . ode. tplquad fixed_quad ﬁxed-order Gaussian quadrature quadrature adaptive Gaussian quadrature odeint. Integration and ODEs (scipy.) (21. epsrel : : relative error tolerance.quad(x.0. simps. limit : : an upper bound on the number of subintervals used in the adaptive algorithm..3684757858670003e-13) 3. wopts : : Optional input for reusing Chebyshev moments.4. See Also: dblquad.10..

3333333333 Calculate ∞ −x e dx 0 >>> invexp = lambda x: exp(-x) >>> integrate. Returns y : ﬂoat The resultant integral. args=(). Release 0. 0. args=(1. Default is 1.quad(f. (a.integrate. err = integrate.**3/3 21.. err = integrate. Reference . abserr : ﬂoat An estimate of the error.x) from x=a. epsrel : ﬂoat Relative tolerance of the inner 1-D integrals.49e-8.4899999999999999e-08) Compute a double integral.5 >>> >>> 1.. Parameters func : callable A Python function or method of at least two variables: y must be the ﬁrst argument and x the second argument. 1. 1. hfun : callable The upper boundary curve in y (same requirements as gfun). 0.99999999999999989.dblquad(func.b and y=gfun(x).)) y y. epsrel=1.0. hfun.)) y scipy. gfun.SciPy Reference Guide. args : sequence. See Also: 218 Chapter 3.a : a*x y.inf) (0.8426061711142159e-11) >>> >>> >>> 0. b.dev6665 >> print 4.10. Return the double (deﬁnite) integral of func(y. optional Absolute tolerance passed directly to the inner 1-D quadrature integration.quad(invexp. epsabs=1.49e-8.4899999999999999e-08. a.b) : tuple The limits of integration in x: a < b gfun : callable The lower boundary curve in y which is a function taking a single ﬂoating point argument (x) and returning a ﬂoating point result: a lambda function can be useful here. args=(3.0. 5. epsabs : ﬂoat.hfun(x).5 f = lambda x.quad(f. Default is 1. optional Extra arguments to pass to func2d.

x) from x=a. optional Relative tolerance of the innermost 1-D integrals. y) and returns a ﬂoat. gfun.hfun(x).) args : Arguments Extra arguments to pass to func3d.49e-8.. b.integrate) 219 . rfun.0. Release 0. (a. y=gfun(x). x). args=().b) : tuple The limits of integration in x: a < b gfun : function The lower boundary curve in y which is a function taking a single ﬂoating point argument (x) and returning a ﬂoating point result: a lambda function can be useful here. and z=qfun(x. Default is 1. qfun.4899999999999999e08.49e-8. rfun : function The upper boundary surface in z.y). a. epsabs=1. Integration and ODEs (scipy. Default is 1. Return the triple integral of func(z. epsabs : ﬂoat. y.4.b. epsrel=1. qfun : function The lower boundary surface in z.10. optional Absolute tolerance passed directly to the innermost 1-D quadrature integration. It must be a function that takes two ﬂoats in the order (x.4899999999999999e-08) Compute a triple (deﬁnite) integral. y. hfun : function The upper boundary curve in y (same requirements as gfun).y) Parameters func : function A Python function or method of at least three variables in the order (z.. romb scipy. Returns y : ﬂoat 3.. simps.rfun(x. (Same requirements as qfun.SciPy Reference Guide. ode.tplquad(func.dev6665 quad single integral tplquad triple integral fixed_quad ﬁxed-order Gaussian quadrature quadrature adaptive Gaussian quadrature odeint. hfun. epsrel : ﬂoat.special for coefﬁcients and roots of orthogonal polynomials scipy.integrate. trapz.

dev6665 The resultant integral. optional Order of quadrature integration. args : tuple. n : int.integrate. See Also: quad Adaptive quadrature using QUADPACK quadrature Adaptive Gaussian quadrature fixed_quad Fixed-order Gaussian quadrature dblquad Double integrals romb Integrators for sampled data trapz Integrators for sampled data simps Integrators for sampled data ode ODE integrators odeint ODE integrators scipy. optional Extra arguments to pass to function.10. Parameters func : callable A Python function or method to integrate (must accept vector inputs). Reference . b. a : ﬂoat Lower limit of integration. Returns val : ﬂoat 220 Chapter 3.fixed_quad(func. args=(). a.special For coefﬁcients and roots of orthogonal polynomials scipy. if any.SciPy Reference Guide. Default is 5. n=5) Compute a deﬁnite integral using ﬁxed-order Gaussian quadrature.0. abserr : ﬂoat An estimate of the error. Integrate func from a to b using Gaussian quadrature of order n. b : ﬂoat Upper limit of integration. Release 0.

0.4899999999999999e-08. trapz cumtrapz cumulative integration for sampled data ode. Returns val : ﬂoat Gaussian quadrature approximation (within tolerance) to integral. maxiter=50.10.SciPy Reference Guide. maxiter : int. Integration and ODEs (scipy. optional Iteration stops when error between last two iterates is less than tol OR the relative change is less than rtol. Default is True.4899999999999999e-08.quadrature(func. tol. optional Maximum number of iterations. vec_func=True) Compute a deﬁnite integral using ﬁxed-tolerance Gaussian quadrature. tol=1. err : ﬂoat Difference between last two estimates of the integral. odeint scipy. Release 0. optional Extra arguments to pass to function.4. rtol=1. 3. tplquad romberg adaptive Romberg quadrature quadrature adaptive Gaussian quadrature romb. b.dev6665 Gaussian quadrature approximation to the integral See Also: quad adaptive quadrature using QUADPACK dblquad. args=().integrate) 221 . Parameters func : function A Python function or method to integrate. a : ﬂoat Lower limit of integration. Integrate func from a to b using Gaussian quadrature with absolute tolerance tol.integrate. rol : ﬂoat. a. args : tuple. optional True or False if func handles arrays as arguments (is a “vector” function). simps. b : ﬂoat Upper limit of integration. vec_func : bool.

If vec_func is True (default is False). vec_func=False) Romberg integration of a callable function or method. Returns results : ﬂoat Result of the integration.romberg(function.10. tol=1. Parameters function : callable Function to be integrated. show=False. If show is 1. then function is assumed to support vector arguments.48e-08. Release 0.0. Other Parameters args : tuple. divmax=10. b). a : ﬂoat Lower limit of integration. optional 222 Chapter 3.SciPy Reference Guide. Returns the integral of function (a function of one variable) over the interval (a.48e-08.dev6665 See Also: romberg adaptive Romberg quadrature fixed_quad ﬁxed-order Gaussian quadrature quad adaptive quadrature using QUADPACK dblquad double integrals tplquad triple integrals romb integrator for sampled data simps integrator for sampled data trapz integrator for sampled data cumtrapz cumulative integration for sampled data ode ODE integrator odeint ODE integrator scipy.integrate. rtol=1. Reference . the triangular array of the intermediate results will be printed. b. args=(). b : ﬂoat Upper limit of integration. a.

special import erf >>> gaussian = lambda x: 1/np. divmax : int. >>> from scipy.421368 0.421350 0.sqrt(np.421356 0. 1.421350 0.125000 0. See Also: fixed_quad Fixed-order Gaussian quadrature.dev6665 Extra arguments to pass to function.385872 0. Default is 10.421350 0. tplquad.419184 0.421350396475 after 33 function evaluations. >>> print 2*result. show : bool. rtol : ﬂoat.421350 0.421350 0. 1] Steps 1 2 4 8 16 32 StepSize 1.84270079295 3.412631 0.421317 0.421350 0.421215 0.000000 0.062500 0.031250 Results 0.84270079295 0. quad Adaptive quadrature using QUADPACK.421551 0.421350 0.e whether it is a “vector” function).SciPy Reference Guide. Default is False. Default is to pass no extra arguments. optional The desired absolute and relative tolerances. optional Whether func handles arrays as arguments (i.10.integrate) 223 .250000 0.erf(1) 0.exp(-x**2) >>> result = romberg(gaussian. simps.48e-8.pi) * np. optional Whether to print the results. trapz cumtrapz Cumulative integration for sampled data. odeint References [R1] Examples Integrate a gaussian from 0 to 1 and compare to the error function. Integration and ODEs (scipy. ode.421350 0.500000 0.4. vec_func : bool. show=True) Romberg integration of <function vfunc at 0x101eceaa0> from [0.421350 The ﬁnal result is 0. 0. romb. Release 0.0.421352 0. Each element of args will be passed as a single argument to func.421350 0. Defaults are 1. tol. optional Maximum order of extrapolation. Default is False. dblquad.420810 0.421350 0.

optional If x is None. x : array_like. [R3] Examples >>> np. x. cumsum Notes Image [R3] illustrates trapezoidal rule – y-axis locations of points will be taken from y array. by default x-axis distances between points will be 1. x. Integrate y(x) using samples along the given axis and the composite Romberg integration using samples of a function.8]) 8. 4. optional If x is None.0 >>> a = np.0.2.trapz(y.arange(6).0. Reference .SciPy Reference Guide. [3.0 >>> np. x=None.2. dx. show]) Integrate along the given axis using the composite trapezoidal rule. 3) >>> a array([[0.dev6665 3.3].2. Default is 1.3]. dx. axis.trapz([1. References [R2]. even]) romb(y[. Integrate y (x) along given axis. dx. alternatively they can be provided with x array or with dx scalar.trapz([1. Return value will be equal to combined area under the red lines. See Also: sum. Cumulatively integrate y(x) using samples along the given axis and the composite trapezoidal rule.2 Integrating functions.10. dx : scalar. scipy.4. 1. given ﬁxed samples trapz(y[. dx=1. x. x=[4. Release 0. optional Specify the axis. dx=2) 8. 5]]) 224 Chapter 3. axis=-1) Integrate along the given axis using the composite trapezoidal rule.0 >>> np. axis]) simps(y[.trapz([1.0. 2]. then spacing between all y elements is dx. axis : int. Returns out : ﬂoat Deﬁnite integral as approximated by trapezoidal rule.3]) 4. Parameters y : array_like Input array to integrate.reshape(2. dx. axis]) cumtrapz(y[.integrate. axis.6. spacing given by dx is assumed.

Integration and ODEs (scipy.5. Release 0.integrate. axis=1) array([ 2. optional dx : int.10. spacing given by dx is assumed. axis=-1) Cumulatively integrate y(x) using samples along the given axis and the composite trapezoidal rule.5. Parameters y : array x : array.cumtrapz(y.trapz(a. dx=1.. If x is None.integrate) 225 . 2. axis=0) array([ 1. 8.]) scipy.5]) >>> np. optional Speciﬁes the axis to cumulate: • -1 –> X axis • 0 –> Z axis • 1 –> Y axis See Also: quad adaptive quadrature using QUADPACK romberg adaptive Romberg quadrature quadrature adaptive Gaussian quadrature fixed_quad ﬁxed-order Gaussian quadrature dblquad double integrals tplquad triple integrals romb integrators for sampled data trapz integrators for sampled data cumtrapz cumulative integration for sampled data ode ODE integrators odeint ODE integrators 3.SciPy Reference Guide. x=None.0. optional axis : int.0.trapz(a. 3.4.dev6665 >>> np.

‘str’}. If x is None. the points at which y is sampled. optional Spacing of integration points along axis of y. Default is the last axis. optional If given. axis : int. dx : int. Only used when x is None. then there are an odd number of intervals (N-1). ‘ﬁrst’. but Simpson’s rule requires an even number of intervals. optional ‘avg’ [Average two results:1) use the ﬁrst N-2 intervals with] a trapezoidal rule on the last interval and 2) use the last N-2 intervals with a trapezoidal rule on the ﬁrst interval. even : {‘avg’. optional Axis along which to integrate. x=None.integrate. ‘ﬁrst’ [Use Simpson’s rule for the ﬁrst N-2 intervals with] a trapezoidal rule on the last interval. dx=1. N.10.dev6665 scipy. Default is 1. Release 0. axis=-1.0. even=’avg’) Integrate y(x) using samples along the given axis and the composite Simpson’s rule. ‘last’ [Use Simpson’s rule for the last N-2 intervals with a] trapezoidal rule on the ﬁrst interval. x : array_like.SciPy Reference Guide. See Also: quad adaptive quadrature using QUADPACK romberg adaptive Romberg quadrature quadrature adaptive Gaussian quadrature fixed_quad ﬁxed-order Gaussian quadrature dblquad double integrals tplquad triple integrals romb integrators for sampled data 226 Chapter 3.simps(y. If there are an even number of samples. Parameters y : array_like Array to be integrated. The parameter ‘even’ controls how this is handled. spacing of dx is assumed. Reference .

0.10. y0. fixed_quad.3 Integrators of ODE systems odeint(func.4. optional The sample spacing. args. show=False) Romberg integration using samples of a function. tplquad. romberg. optional The axis along which to integrate. Returns ret : array_like? The integrated result for each axis.4. axis : array_like?.SciPy Reference Guide. odeint See Also: scipy. show : bool. t[. axis=-1. trapz. Default is -1 (last axis). then the result is exact only if the function is a polynomial of order 2 or less. Dfun.. . See Also: quad. Release 0.romb(y. Integration and ODEs (scipy.]) ode(f[.0. optional When y is a single 1-D array..special for orthogonal polynomials (special) for Gaussian quadrature roots and weights for other weighting factors and regions. Default is 1. then if this argument is True print the table showing Richardson extrapolation from the samples.integrate. dx=1. dblquad. 3. A generic interface class to numeric integrators. Parameters y : array_like A vector of 2**k + 1 equally-spaced samples of a function. col_deriv. If the samples are not equally spaced. dx : array_like. cumtrapz. jac]) Integrate a system of ordinary differential equations. 3. simps.integrate) 227 . scipy. ode.dev6665 trapz integrators for sampled data cumtrapz cumulative integration for sampled data ode ODE integrators odeint ODE integrators Notes For an odd number of samples that are equally spaced the result is exact if the function is a polynomial of order 3 or less. quadrature. Default is False.

rtol=None. hmin=0. t : array A sequence of time points for which to solve for y. shape (len(y0). Dfun : callable(y.0. Dfun=None.SciPy Reference Guide. args : tuple Extra arguments to pass to function. mxhnil=0.. Parameters func : callable(y. hmax=0.) Computes the derivative of y at t0.. y0 : array Initial condition on y (can be a vector).. col_deriv=0. printmessg=0) Integrate a system of ordinary differential equations. mxords=5.0.0. tcrit=None.t0. y0. with the initial value y0 in the ﬁrst row.dev6665 scipy. only returned if full_output == True Dictionary containing additional output information 228 Chapter 3. ml=None. mxordn=12.. len(t)) Array containing the value of y for each desired time in t... Solves the initial value problem for stiff or non-stiff systems of ﬁrst order ode-s: dy/dt = func(y.) Gradient (Jacobian) of func.odeint(func. full_output=0. args=(). t0. Solve a system of ordinary differential equations using lsoda from the FORTRAN library odepack. t. . Release 0. ixpr=0. Reference . full_output : boolean True if to return a dictionary of optional outputs as the second output printmessg : boolean Whether to print the convergence message Returns y : array.) where y can be a vector. .10. col_deriv : boolean True if Dfun deﬁnes derivatives down columns (faster). mxstep=0. mu=None.integrate.0. t0.. otherwise Dfun should deﬁne derivatives across rows. atol=None. The initial value point should be the ﬁrst element of this sequence. infodict : dict. h0=0.

Thus. 3. ‘leniw’ the length of integer work array required. hmax : ﬂoat. 2: bdf (stiff) Other Parameters ml. Dfun should return a matrix whose columns contain the non-zero bands (starting with the lowest diagonal). -1 otherwise.integrate) 229 . (0: solver-determined) Maximum number of (internally deﬁned) steps allowed for each integration point in t. of estimated local errors in y.49012e-8. vector with the value of t reached for each time step. (0: solver-determined) The step size to be attempted on the ﬁrst step. h0 : ﬂoat.4. ‘tolsf’ vector of tolerance scale factors.dev6665 key ‘hu’ ‘tcur’ meaning vector of step sizes successfully used for each time step. ‘imxer’ index of the component of largest magnitude in the weighted local error vector (e / ewt) on an error return.0.10. greater than 1. Integration and ODEs (scipy. computed when a request for too much accuracy was detected.g. Release 0. (0: solver-determined) The maximum absolute step size allowed. Defaults to 1. tcrit : array Vector of critical points (e. ‘tsw’ value of t at the time of the last method switch (given for each time step) ‘nst’ cumulative number of time steps ‘nfe’ cumulative number of function evaluations for each time step ‘nje’ cumulative number of jacobian evaluations for each time step ‘nqu’ a vector of method orders for each successful step. hmin : ﬂoat. (will always be at least as large as the input times).0. mxstep : integer. For the banded case. e.SciPy Reference Guide. ‘mused’a vector of method indicators for each successful time step: 1: adams (nonstiff). (0: solver-determined) The minimum absolute step size allowed. the return matrix from Dfun should have shape len(y0) * (ml + mu + 1) when ml >=0 or mu >=0 rtol. These give the number of lower and upper non-zero diagonals in this banded matrix. singularities) where integration care should be taken. atol : ﬂoat The input parameters rtol and atol determine the error control performed by the solver. ‘lenrw’ the length of the double work array required. The solver will control the vector. ixpr : boolean Whether to generate extra printing at method switches. then the Jacobian is assumed to be banded. where ewt is a vector of positive error weights computed as: ewt = rtol * abs(y) + atol rtol and atol can be either vectors the same length as y or scalars. mu : integer If either of these are not-None or non-negative. according to an inequality of the form max-norm of (e / ewt) <= 1.

y. t0). method=’bdf’. Reference . with_jacobian=True) r. arg1): return [1j*arg1*y[0] + y[1].set_integrator(’zvode’.dev6665 mxhnil : integer. See Also: ode a more object-oriented integrator based on VODE quad for ﬁnding the area under a curve class scipy. mxordn : integer. See Also: odeint an integrator with a simpler interface based on lsoda from ODEPACK quad for ﬁnding the area under a curve Examples A problem to integrate and the corresponding jacobian: >>> >>> >>> >>> >>> >>> >>> >>> >>> from scipy import eye from scipy.0j. [0. mxords : integer. 1].0) t1 = 10 dt = 1 while r.0].y 230 Chapter 3.ode(f.successful() and r. r.t < t1: r. -arg1*y[1]**2] def jac(t. y. (0: solver-determined) Maximum number of messages printed. t0 = [1.set_jac_params(2.t+dt) print r. Release 0. 0 def f(t.t. 2. -arg1*2*y[1]]] The integration: >>> >>> >>> >>> >>> >>> >>> r = ode(f. arg1): return [[1j*arg1.10.integrate import ode y0.integrate. (0: solver-determined) Maximum order to be allowed for the stiff (BDF) method. jac=None) A generic interface class to numeric integrators.set_f_params(2.set_initial_value(y0.integrate(r.0).0. jac).SciPy Reference Guide. (0: solver-determined) Maximum order to be allowed for the nonstiff (Adams) method.

The default is to copy. y : array_like A N-D array of real values.interpolate) 231 ..interpolate. x) Interpolate a 1D function. Interpolation defaults to the last axis of y. optional Speciﬁes the kind of interpolation as a string (‘linear’. direction]) barycentric_interpolate(xi.interp1d(x. optional If True. Default is ‘linear’.’nearest’. orders. ﬁll_value=np. copy : bool. Parameters x : array_like A 1-D array of monotonically increasing real values. y. bounds_error : bool. y[. ‘zero’. optional 3. yi]) KroghInterpolator(xi. axis : int. the class makes internal copies of x and y. yi[. kind : str or int.dev6665 Methods integrate set_f_params set_initial_value set_integrator set_jac_params successful 3. Release 0. bounds_error=True. references to x and y are used.interpolate) 3.0.SciPy Reference Guide. Interpolation (scipy. kind=’linear’. copy.5.1 Univariate interpolation interp1d(x. kind. yi) PiecewisePolynomial(xi.]) BarycentricInterpolator(xi[. yi. If False. copy=True. yi. x and y are arrays of values used to approximate some function f: y = f(x) This class returns a function whose call method uses linear interpolation to ﬁnd the value of new points. x[. . The length of y along the interpolation axis must be equal to the length of x.5. Convenience function for piecewise polynomial interpolation class scipy. optional Speciﬁes the axis of y along which to interpolate.5 Interpolation (scipy. ‘quadratic.10. ‘slinear’. The interpolating polynomial for a set of points The interpolating polynomial for a set of points Piecewise polynomial curve speciﬁed by points and derivatives Convenience function for polynomial interpolation Convenience function for polynomial interpolation.. ‘cubic’) or as an integer specifying the order of the spline interpolator to use. axis=-1. x) krogh_interpolate(xi. der]) piecewise_polynomial_interpolate(xi.nan) Interpolate a 1D function. yi. axis.

then this value will be used to ﬁll in for requested points outside of the data range. efﬁcient changing of the y values to be interpolated. Moreover. Allows evaluation of the polynomial.KroghInterpolator(xi. splev Examples >>> import scipy.arange(0.10.Chebyshev zeros (e. an error is raised.g. Release 0. this function does not compute the coefﬁcients of the polynomial. For reasons of numerical stability. ﬁll_value : ﬂoat. 10) >>> y = np.SciPy Reference Guide.interpolate. xnew.BarycentricInterpolator(xi.interpolate.0) >>> f = sp. This algorithm is quite stable.9. This class uses a “barycentric interpolation” method that treats the problem as a special case of rational function interpolation.polynomial interpolation itself is a very ill-conditioned process due to the Runge phenomenon. this function does not compute the coefﬁcients of the polynomial. For reasons of numerical stability. y) >>> xnew = np. yi=None) The interpolating polynomial for a set of points Constructs a polynomial that passes through a given set of points.polynomial interpolation itself is a very ill-conditioned process due to the Runge phenomenon. optionally with speciﬁed derivatives at those points. If not provided.1) >>> ynew = f(xnew) >>> plt. cos(i*pi/n)) are a good choice . “Barycentric Lagrange Interpolation”. y. although they can be obtained by evaluating all the derivatives.dev6665 If True. then the default is NaN. numerically. unless the x coordinates are chosen very carefully . Allows evaluation of the polynomial and all its derivatives.interp1d(x. Methods add_xi set_yi class scipy. even in a world of exact computation. In general.arange(0. By default. ynew. See Also: UnivariateSpline A more recent wrapper of the FITPACK routines. ’-’) class scipy.exp(-x/3. splrep. Based on Berrut and Trefethen 2004.Chebyshev zeros (e. 0. yi) The interpolating polynomial for a set of points Constructs a polynomial that passes through a given set of points.g. unless the x coordinates are chosen very carefully . out of bounds values are assigned ﬁll_value. an error is thrown any time interpolation is attempted on a value outside of the range of x (where extrapolation is necessary). 232 Chapter 3. but even in a world of exact computation. ’o’. Be aware that the algorithms implemented here are not necessarily the most numerically stable known. Reference .plot(x. cos(i*pi/n)) are a good choice .0.interpolate. even with well-chosen x values. If False.interpolate >>> x = np. and updating by adding more x values. optional If provided. degrees higher than about thirty cause problems with numerical instability in this code.

yi. This function uses a “barycentric interpolation” method that treats the problem as a special case of rational function interpolation.g. this function does not compute the coefﬁcients of the polynomial. as may the number of derivatives available. Methods append derivative derivatives extend scipy. orders=None. direction=None) Piecewise polynomial curve speciﬁed by points and derivatives This class represents a curve that is a piecewise polynomial. Parameters xi : array-like.5. For reasons of numerical stability. Appending points to the end of the curve is efﬁcient. Release 0.interpolate. yi. Parameters xi : array-like of length N The x coordinates of the points the polynomial should pass through yi : array-like N by R The y coordinates of the points the polynomial should pass through. x) Convenience function for polynomial interpolation Constructs a polynomial that passes through a given set of points.barycentric_interpolate(xi.SciPy Reference Guide. x : scalar or array-like of length M 3. This algorithm is quite stable.PiecewisePolynomial(xi. Based on Berrut and Trefethen 2004. cos(i*pi/n)) are a good choice polynomial interpolation itself is a very ill-conditioned process due to the Runge phenomenon. length N Known x-coordinates yi : array-like. or scalars if R=1.interpolate) 233 . The degree of the polynomial may very from segment to segment. if R>1 the polynomial is vector-valued. It passes through a list of points and has speciﬁed derivatives at each point. unless the x coordinates are chosen very carefully . but even in a world of exact computation.0. then evaluates the polynomial. The degree should not exceed about thirty. the corresponding yi’s represent derivative values. N by R Known y-coordinates.dev6665 Based on [R4]. interpreted as vectors of length R. “Barycentric Lagrange Interpolation”.interpolate.Chebyshev zeros (e. When an xi occurs two or more times in a row. References [R4] Methods derivative derivatives class scipy.10. numerically. Interpolation (scipy.

even in a world of exact computation.10. or scalars if R=1 x : scalar or array-like of length N Point or points at which to evaluate the derivatives der : integer or list How many derivatives to extract.interpolate.g. der=0) Convenience function for polynomial interpolation. Notes Construction of the interpolation weights is a relatively slow process.yi). None for all potentially nonzero derivatives (that is a number equal to the number of points). Constructs a polynomial that passes through a given set of points. 234 Chapter 3. “Efﬁcient Algorithms for Polynomial Interpolation and Numerical Differentiation” The polynomial passes through all the pairs (xi. even with well-chosen x values. scipy.polynomial interpolation itself is a very ill-conditioned process due to the Runge phenomenon. If you want to call this many times with the same xi (but possibly varying yi or x) you should use the class BarycentricInterpolator. Notes Construction of the interpolating polynomial is a relatively expensive process. Be aware that the algorithms implemented here are not necessarily the most numerically stable known. One may additionally specify a number of derivatives at each point xi. In general. If you want to evaluate it repeatedly consider using the class KroghInterpolator (which is what this function uses). Based on Krogh 1970.dev6665 Returns y : scalar or array-like of length R or length M or M by R The shape of y depends on the shape of x and whether the interpolator is vectorvalued or scalar-valued. Evaluates the polynomial or some of its derivatives. Moreover.krogh_interpolate(xi. the middle dimension will be dropped. Returns : ——.: d : array If the interpolator’s values are R-dimensional then the returned array will be the number of derivatives by N by R. N by R known y-coordinates. interpreted as vectors of length R. unless the x coordinates are chosen very carefully . if the yi are scalars then the last dimension will be dropped. For reasons of numerical stability. cos(i*pi/n)) are a good choice . this function does not compute the coefﬁcients of the polynomial. This is what this function uses internally. degrees higher than about thirty cause problems with numerical instability in this code. Release 0.Chebyshev zeros (e. Parameters xi : array-like. length N known x-coordinates yi : array-like. x.SciPy Reference Guide.0. If x is a scalar. although they can be obtained by evaluating all the derivatives. optionally with speciﬁed derivatives at those points. or a list of derivatives to extract. yi. Reference . this is done by repeating the value xi and specifying the derivatives as successive yi values. This number includes the function value as 0th derivative.

Release 0. or integer a list of polynomial orders. . xi.. then the degree of the polynomial segment is exactly the degree required to match all i available derivatives at both endpoints. consider using the class PiecewisePolynomial (which is what this function does).10. If not enough derivatives are available.) 3. values. der=0) Convenience function for piecewise polynomial interpolation Parameters xi : array-like of length N a sorted list of x-coordinates yi : list of lists of length N yi[i] is the list of derivatives known at xi[i] x : scalar or array-like of length M orders : list of integers. the points must be sorted in ascending order.5. curvature-minimizing interpolant in values[. shape (npoints.9. shape (npoints. Piecewise linear interpolant in N dimensions. ﬁll_value=nan) Interpolate unstructured N-dimensional data. Piecewise cubic. if you repeatedly evaluate the same polynomial. x.2 Multivariate interpolation Unstructured data: griddata(points. tol]) 2D.griddata(points. then some derivatives will be ignored.0. method=’linear’.5. values) CloughTocher2DInterpolator(points. or orders[i] is None.interpolate.SciPy Reference Guide. values : ndarray of ﬂoat or complex. For interpolation of 1-D data. Can either be a ndarray of size (npoints. it will prefer the rightmost endpoint. Construction of these piecewise polynomials can be an expensive process. an exception is raised.piecewise_polynomial_interpolate(xi. Parameters points : ndarray of ﬂoats. method. Interpolate unstructured N-dimensional data. Rbf(*args) A class for radial basis function approximation/interpolation of n-dimensional scattered data. Nearest-neighbour interpolation in N dimensions.]) LinearNDInterpolator(points.. New in version 0. orders=None. values) NearestNDInterpolator(points.. ndim).interpolate) 235 . . xi[. or a single universal order der : integer which single derivative to extract Returns y : scalar or array-like of length R or length M or M by R Notes If orders is None. values.interpolate. The code will try to use an equal number of derivatives from each end.dev6665 scipy.. C1 smooth. or a tuple of ndim arrays. yi. Interpolation (scipy. If orders[i] is not None. scipy. if the total number of derivatives needed is odd. 3. ndims) Data point coordinates.

(grid_x.interpolate import griddata grid_z0 = griddata(points. extent=(0. One of • nearest: return the value at the data point closest to the point of interpolation.1). method=’cubic’) One can see that the exact result is reproduced by all of the methods to some degree.subplot(222) plt.T. and approximately curvature-minimizing polynomial surface. grid_y). ‘nearest’. y): >>> return x*(1-x)*np. (grid_x. ’k. Reference .imshow(func(grid_x. continuously differentiable (C1).0. method=’linear’) grid_z2 = griddata(points.subplot(221) plt. method : {‘linear’. grid_y)..pyplot as plt plt. See LinearNDInterpolator for more details.0. 1] >>> grid_x.1.. but for this smooth function the piecewise cubic interpolant gives the best results: >>> >>> >>> >>> >>> >>> >>> >>> >>> import matplotlib. 1]x[0. See CloughTocher2DInterpolator for more details. Release 0.0. • cubic (2-D): return the value determined from a piecewise cubic. extent=(0. ﬁll_value : ﬂoat.title(’Nearest’) plt. (grid_x.dev6665 Data values.cos(4*np. values.0]. grid_y = np. method=’nearest’) grid_z1 = griddata(points.rand(1000..mgrid[0:1:100j.0]. grid_y).plot(points[:. • linear: tesselate the input point set to n-dimensional simplices. ‘cubic’} Method of interpolation.random.1. grid_y).T.10.’. Examples Suppose we want to interpolate the 2-D function >>> def func(x.pi*y**2)**2 on a grid in [0. values. 0:1:200j] but we only know its values at 1000 data points: >>> points = np. This option has no effect for the ‘nearest’ method. ndim) Points where to interpolate data at.title(’Original’) plt.subplot(223) 236 Chapter 3. ms=1) plt.1]. points[:. and interpolate linearly on each simplex. If not provided. origin=’lower’) plt.SciPy Reference Guide. origin=’lower’) plt. xi : ndarray of ﬂoat. 2) >>> values = func(points[:. then the default is nan. shape (.sin(4*np. points[:. See NearestNDInterpolator for more details. optional Value used to ﬁll in for requested points outside of the convex hull of the input points. • cubic (1-D): return the value detemined from a cubic spline.pi*x) * np.imshow(grid_z0.1]) This can be done with griddata – below we try out all of the interpolation methods: >>> >>> >>> >>> from scipy. values.1).

1.2 Original 1.2 Nearest 0.0 0.4 0. Parameters points : ndarray of ﬂoats.2 0.interpolate.0.0 0. extent=(0. shape (npoints.2 0. Release 0.0 0.1).T.4 0.6 0.6 0.0 0. values : ndarray of ﬂoat or complex. 3.4 0.title(’Linear’) plt.6 0.8 0.0 0.title(’Cubic’) plt.8 1.8 0.interpolate) 237 .dev6665 >>> >>> >>> >>> >>> >>> >>> plt.LinearNDInterpolator(points.9.6 0.imshow(grid_z1.1.0 0.0 0.4 0.6 0. 6) plt. values) Piecewise linear interpolant in N dimensions. origin=’lower’) plt.6 0.0 0.0 0.10. shape (npoints.2 0.show() 1. origin=’lower’) plt.0..8 1.gcf().0 class scipy.8 0.4 0. Interpolation (scipy.8 1.) Data values. New in version 0..2 0.0.0 0.4 0.T.0 0.8 1.0 0.6 0.set_size_inches(6.subplot(224) plt.8 0. extent=(0.4 0.0 0.6 0. .0 Linear 1.2 0.imshow(grid_z2.4 0.2 0. ndims) Data point coordinates.1).SciPy Reference Guide.5.0 Cubic 1.

spatial. New in version 0. The gradients necessary for this are estimated using the global algorithm described in [Nielson83. then the default is nan. . If not provided. optional Value used to ﬁll in for requested points outside of the convex hull of the input points.10. ndims) Data point coordinates. shape (npoints. values) Nearest-neighbour interpolation in N dimensions. 238 Chapter 3.interpolate. and constructing a piecewise cubic interpolating Bezier polynomial on each triangle. optional Value used to ﬁll in for requested points outside of the convex hull of the input points. Notes The interpolant is constructed by triangulating the input data with Qhull [Qhull]. shape (npoints.Renka84]_.dev6665 ﬁll_value : ﬂoat. Reference . tol : ﬂoat. The gradients of the interpolant are chosen so that the curvature of the interpolating surface is approximatively minimized. using a Clough-Tocher scheme [CT]. Parameters points : ndarray of ﬂoats..9.. New in version 0. .interpolate. values. If not provided. The interpolant is guaranteed to be continuously differentiable. References [Qhull] class scipy.) Data values. values : ndarray of ﬂoat or complex. optional Absolute/relative tolerance for gradient estimation. Notes Uses scipy. and on each triangle performing linear barycentric interpolation. curvature-minimizing interpolant in 2D. Release 0. shape (npoints. optional Maximum number of iterations in gradient estimation.NearestNDInterpolator(points. Parameters points : ndarray of ﬂoats. values : ndarray of ﬂoat or complex. C1 smooth. maxiter : int. tol=1e-6) Piecewise cubic. ndims) Data point coordinates..CloughTocher2DInterpolator(points.cKDTree class scipy. then the default is nan.9. ﬁll_value : ﬂoat. shape (npoints.) Data values.0..SciPy Reference Guide. Notes The interpolant is constructed by triangulating the input data with Qhull [Qhull].

y.. smooth : ﬂoat. y.).sum(axis=0) ) which is called with x1=x1[ndims.:. yi. r). with inputs as arrays of positions (x. z.newaxis] such that the result is a matrix of the distances from each point in x1 to each point in x2.newaxis.Rbf(*args) A class for radial basis function approximation/interpolation of n-dimensional scattered data. [Nielson83]. 0 is for interpolation (default). epsilon : ﬂoat. r. z[. .5.. z. norm : callable. given by the norm (defult is Euclidean distance). . E.. y. [CT]. kind.0. the function will always go through the nodal points in this case.. where x.:] and x2=x2[ndims.. optional Values greater than zero increase the smoothness of the approximation.10. then it must take 2 arguments (self. [Renka84] class scipy. Other keyword arguments passed in will be available as well.epsilon. d. Parameters *args : arrays x. z.dev6665 References [Qhull]. the default is ‘multiquadric’: ’multiquadric’: sqrt((r/self.epsilon)**2 + 1) ’inverse’: 1. optional Adjustable constant for gaussian or multiquadrics functions .]) Interpolate over a 2D grid.interpolate.g.epsilon)**2) ’linear’: r ’cubic’: r**3 ’quintic’: r**5 ’thin_plate’: r**2 * log(r) If callable. are the coordinates of the nodes and d is the array of values at the nodes function : str or callable. copy. Release 0.interpolate) 239 . optional The radial basis function.. optional A function that returns the ‘distance’ between two points. y. The epsilon parameter will be available as self... Examples >>> rbfi = Rbf(x. zi) # radial basis function interpolator instance # interpolated values Data given on a regular grid: interp2d(x. y. z. . x2): return sqrt( ((x1 . 3. d) >>> di = rbfi(xi. based on the radius. Interpolation (scipy. the default: def euclidean_norm(x1.x2)**2).epsilon)**2 + 1) ’gaussian’: exp(-(r/self..SciPy Reference Guide. .defaults to approximate average distance between nodes (which is a good start).0/sqrt((r/self. and an output as an array of distance.

k=3. None ]. If z is a multi-dimensional array. w.10. for example: x = [0. If the points lie on a regular grid.2]. when interpolated values are requested outside of the domain of the input data. y = [0. Parameters x. ﬁll_value : number If provided. ‘cubic’. 240 Chapter 3. they are ﬂattened before use.1.0. otherwise only a reference is held. copy : bool If True. bbox.dev6665 class scipy.5. Release 0. y : 1D arrays copy=True. z.2. None. One-dimensional spline with explicit internal knots. Fits a spline y=s(x) of degree k to the provided x. y data. y = [0.interp2d(x. an error is raised.UnivariateSpline(x.7.2]. x can specify the column coordinates and y the row coordinates. y. it is ﬂattened before use.0.3.1. z : 1D array The values of the interpolated function on the grid points.3.SciPy Reference Guide. s=None) One-dimensional smoothing spline ﬁt to a given set of data points. s speciﬁes the number of knots by specifying a smoothing condition. kind : {‘linear’.3 1-D Splines UnivariateSpline(x. bbox.interpolate. bbox=[.3. w=None. y. the value to use for points outside of the interpolation domain.7] otherwise x and y must specify the full coordinates. bbox. w. then ﬁll_value is used.0. Raises ValueError when inputs are invalid. for example: x = [0. : See Also: bisplrep. kind=’linear’. w.2. bisplev BivariateSpline a more recent wrapper of the FITPACK routines 3.3. ﬁll_value=nan) Interpolate over a 2D grid.0. y[. s]) InterpolatedUnivariateSpline(x.0.7] If x and y are multi-dimensional.7. then data is copied. Defaults to NaN. y[. t[. k. bounds_error=False.interpolate. ‘quintic’} The kind of interpolation to use.1. bounds_error : bool If True. Reference . class scipy. If False. One-dimensional interpolating spline for a given set of data points.1. k]) LSQUnivariateSpline(x. Arrays deﬁning the coordinates of a 2D grid. k]) One-dimensional smoothing spline ﬁt to a given set of data points. y.

optional Weights for spline ﬁtting. spline will interpolate through all data points.interpolate) 241 . bbox : array_like. 3.10. Number of knots will be increased until the smoothing condition is satisﬁed: sum((w[i]*(y[i]-s(x[i])))**2. y.random import randn from scipy.axis=0) <= s If None (default). s : ﬂoat or None. spalde BivariateSpline A similar class for two-dimensional spline interpolation Notes The number of data points must be larger than the spline degree k. s=1) xs = linspace(-3. 3. of the same length as x. See Also: InterpolatedUnivariateSpline Subclass with smoothing forced to 0 LSQUnivariateSpline Subclass in which knots are user-selected instead of being set by smoothing condition splrep An older. splint.interpolate import UnivariateSpline x = linspace(-3. Must be positive.5.dev6665 Parameters x : array_like 1-D array of independent input data. Release 0.ys is now a smoothed. w : array_like. 100) y = exp(-x**2) + randn(100)/10 s = UnivariateSpline(x. sproot. weights are all equal. x[-1]]. k : int. Must be <= 5.y. non object-oriented wrapping of FITPACK splev.exp from numpy. s=len(w) which should be a good value if 1/w[i] is an estimate of the standard deviation of y[i]. 3. Examples >>> >>> >>> >>> >>> >>> >>> >>> from numpy import linspace. If 0. optional Degree of the smoothing spline. Must be increasing. y : array_like 1-D array of dependent input data. 1000) ys = s(xs) xs. If None (default). optional 2-sequence specifying the boundary of the approximation interval. optional Positive smoothing factor used to choose the number of knots. If None (default). super-sampled version of the noisy gaussian x.0. Interpolation (scipy. bbox=[x[0].SciPy Reference Guide.

10. non object-oriented wrapping of FITPACK splev.interpolate. w=None.x[-1]]. y data.0. None ]. Must be <= 5. optional 2-sequence specifying the boundary of the approximation interval. Reference . spalde BivariateSpline A similar class for two-dimensional spline interpolation Notes The number of data points must be larger than the spline degree k. sproot. bbox : array_like. Spline function passes through all provided points. bbox=[. k=3) One-dimensional interpolating spline for a given set of data points. optional Weights for spline ﬁtting.SciPy Reference Guide. If None (default). Release 0. splint. See Also: UnivariateSpline Superclass – allows knots to be selected by a smoothing condition LSQUnivariateSpline spline for which knots are user-selected splrep An older. weights are all equal. bbox=[x[0]. y. Must be positive. Examples 242 Chapter 3. Parameters x : array_like input dimension of data points – must be increasing y : array_like input dimension of data points w : array_like. If None (default). k : int. Equivalent to UnivariateSpline with s=0. Fits a spline y=s(x) of degree k to the provided x.InterpolatedUnivariateSpline(x.dev6665 Methods derivatives get_coeffs get_knots get_residual integral roots set_smoothing_factor class scipy. None. optional Degree of the smoothing spline.

bbox : array_like.y Methods derivatives get_coeffs get_knots get_residual integral roots set_smoothing_factor class scipy. weights are all equal. Must be <= 5.x[-1]].. y. Raises ValueError : If the interior knots do not satisfy the Schoenberg-Whitney conditions See Also: UnivariateSpline Superclass – knots are speciﬁed by setting a smoothing condition 3. optional weights for spline ﬁtting.0. Must be in ascending order and bbox[0]<t[0]<. Fits a spline y=s(x) of degree k to the provided x. 3. If None (default).10.interpolate) 243 .random import randn from scipy. Must be positive.ys is now a smoothed. 100) y = exp(-x**2) + randn(100)/10 s = UnivariateSpline(x. y. If None (default). bbox=[x[0].<t[1]<bbox[-1] w : array_like.interpolate import UnivariateSpline x = linspace(-3. super-sampled version of the noisy gaussian x. None.dev6665 >>> >>> >>> >>> >>> >>> >>> >>> from numpy import linspace.interpolate.LSQUnivariateSpline(x. None ]. bbox=[. optional Degree of the smoothing spline. s=1) xs = linspace(-3. 3.5. Release 0.exp from numpy. optional 2-sequence specifying the boundary of the approximation interval. k=3) One-dimensional spline with explicit internal knots. t speciﬁes the internal knots of the spline Parameters x : array_like input dimension of data points – must be increasing y : array_like input dimension of data points t: array_like : interior knots of the spline. y data.SciPy Reference Guide. k : int. t.. Interpolation (scipy. w=None. 1000) ys = s(xs) xs.

random import randn from scipy.y with knots [-3. Return the positions of (boundary and interior) Return weighted sum of squared residuals of the spline Continue spline computation with the given smoothing UnivariateSpline.0. 244 Chapter 3.3] Methods derivatives get_coeffs get_knots get_residual integral roots set_smoothing_factor The above univariate spline classes have the following methods: UnivariateSpline. splint.derivatives(x) Return all derivatives of the spline at the point x. spalde BivariateSpline A similar class for two-dimensional spline interpolation Notes The number of data points must be larger than the spline degree k.__call__(x[.SciPy Reference Guide.integral(a.1] s = LSQUnivariateSpline(x. Reference .y.0.get_knots() UnivariateSpline.3.-1.get_residual() UnivariateSpline. Return spline coefﬁcients. b) Return deﬁnite integral of the spline between two given points. non object-oriented wrapping of FITPACK splev. Examples >>> >>> >>> >>> >>> >>> >>> >>> >>> from numpy import linspace. super-sampled version of the noisy gaussian x. UnivariateSpline.get_coeffs() UnivariateSpline. Return deﬁnite integral of the spline between two Return the zeros of the spline. sproot. Note: x can be unordered but the evaluation is more efﬁcient if x is (partially) ordered.0.derivatives(x) UnivariateSpline.set_smoothing_factor(s) Evaluate spline (or its nu-th derivative) at positions x.interpolate import LSQUnivariateSpline x = linspace(-3.100) y = exp(-x**2) + randn(100)/10 t = [-1. Return all derivatives of the spline at the point x.__call__(x.ys is now a smoothed.3.dev6665 InterpolatedUnivariateSpline spline passing through all points splrep An older. b) UnivariateSpline. nu]) UnivariateSpline. nu=0) Evaluate spline (or its nu-th derivative) at positions x.1000) ys = s(xs) xs.t) xs = linspace(-3.roots() UnivariateSpline.integral(a. UnivariateSpline.exp from numpy.1. Release 0.10.

der. .get_residual() Return weighted sum of squared residuals of the spline approximation: sum ((w[i]*(y[i]-s(x[i])))**2.get_coeffs() Return spline coefﬁcients.5. UnivariateSpline. task=0. ub.get_knots() Return the positions of (boundary and interior) knots of the spline. Release 0. these default to x[0] and x[-1] respectively. and the knot points. w. k : int The order of the spline ﬁt. 1 <= k <= 5 task : {1. k. s. dy]) Find the B-spline representation of 1-D curve. y. kx. dx. It is recommended to use cubic splines. 0. w.]) splev(x. s. The weights are used in computing the weighted least-squares spline ﬁt.roots() Return the zeros of the spline.interpolate) 245 .interpolate. Evaluate a B-spline or its derivatives. y[. Evaluate a bivariate B-spline and its derivatives. Evaluate all derivatives of a B-spline. w. Even order splines should be avoided especially with small s values. yb.axis=0) UnivariateSpline. If the errors in the y values have standard-deviation given by the vector d. Default is ones(len(x)). s. t..0.dev6665 UnivariateSpline. Uses the FORTRAN routine curﬁt from FITPACK. xe. xe=None. w : array_like Strictly positive rank-1 array of weights the same length as x and y. xe : ﬂoat The interval to ﬁt.set_smoothing_factor(s) Continue spline computation with the given smoothing factor s and with the knots found at the last call. are returned. then w should be 1/d. tck[. tck[. full_output]) sproot(tck[. k=3. Restriction: only cubic splines are supported by ﬁtpack. y : array_like The data points deﬁning a curve y = f(x).]) bisplev(x. Given the set of data points (x[i]. . If None. y. per=0. c. xb=None. UnivariateSpline. Find a bivariate B-spline representation of a surface. Parameters x. scipy. xb. full_output=0. xe. task. w=None.SciPy Reference Guide. s=None.. ext]) splint(a. task. There must have been a previous call with task=0 or task=1 for the same set of data (t will be stored an used internally) 3. quiet=1) Find the B-spline representation of 1-D curve. tck) bisplrep(x. t=None. u. z[. Evaluate the deﬁnite integral of a B-spline. Interpolation (scipy. mest]) spalde(x. t. Find the roots of a cubic B-spline.. b. y. ue.10. ye. xb. xb.splrep(x.. t. UnivariateSpline. y[i]) determine a smooth spline approximation of degree k on the interval xb <= x <= xe. Low-level interface to FITPACK functions: splrep(x. -1} If task==0 ﬁnd t and c for a given smoothing factor. tck[.]) splprep(x[. If task==1 ﬁnd t and c for another value of the smoothing factor. s. k. . Find the B-spline representation of an N-dimensional curve... The coefﬁcients.

Otherwise an error is raised. msg : str. splprep. Release 0. then return optional outputs. These should be interior knots as knots on the ends will be added automatically.m+sqrt(2*m)) where m is the number of datapoints in x. s = 0. ier : int.y).dev6665 If task=-1 ﬁnd the weighted least square spline for a given set of knots. s : ﬂoat A smoothing condition. full_output : bool If non-zero. default : s=m-sqrt(2*m) if weights are supplied.0.c. [R23]. splev. spalde. Reference BivariateSpline. If given then task is automatically set to -1. w. The user can use s to control the tradeoff between closeness and smoothness of ﬁt. See Also: UnivariateSpline. the B-spline coefﬁcients. fp : array. If ier in [1. splint. optional The weighted sum of squared residuals of the spline approximation. bisplrep. optional An integer ﬂag about splrep success. [3]. quiet : bool Non-zero to suppress messages.0 (interpolating) if no weights are supplied.x[0] and a smooth periodic spline approximation is returned. y. The amount of smoothness is determined by satisfying the conditions: sum((w * (y . Returns tck : tuple (t. and [4]: [R22]. Larger s means more smoothing while smaller values of s indicate less smoothing. then a good s value should be found in the range (m-sqrt(2*m). per : bool If non-zero.2. Recommended values of s depend on the weights. [R24]. t : int The knots needed for task=-1.axis=0) <= s where g(x) is the smoothed interpolation of (x. [R25] 246 Chapter 3. References Based on algorithms described in [1]. sproot.g))**2. Values of y[m-1] and w[m-1] are not used. [2].3] an error occurred but was not raised.SciPy Reference Guide. bisplev Notes See splev for evaluation of the spline and its derivatives. If the weights represent the inverse of the standard-deviation of y. ier.k) a tuple containing the vector of knots. and the degree of the spline. t. Success is indicated if ier<=0.10. . data points are considered periodic with period x[m-1] . optional A message corresponding to the integer ﬂag. and w.

x. quiet=1) Find the B-spline representation of an N-dimensional curve. Uses the FORTRAN routine parcur from FITPACK. ﬁnd t and c for another value of the smoothing factor. 10) y = sin(x) tck = splrep(x.m+sqrt(2*m)). t.g))**2. k : int. Even values of k should be avoided especially with a small s-value. optional Degree of the spline. optional The end-points of the parameters interval. ’o’. y.splprep(x. ue : int. optional The knots needed for task=-1. task : int. 200) y2 = splev(x2.10. optional 3. Parameters x : array_like A list of sample vector arrays representing the curve. per=0. w. t : int. u : array_like. Interpolation (scipy. and w. nest : int. There must have been a previous call with task=0 or task=1 for the same set of data.x[i-1]) u[i] = v[i] / v[M-1] ub.0. ub=None. full_output : int. s. k=3. w=None. If task=-1 ﬁnd the weighted least square spline for a given set of knots.interpolate) 247 .SciPy Reference Guide. If not given.y).axis=0) <= s. y. full_output=0. ﬁnd a smooth approximating spline curve g(u). x2. Larger s means more smoothing while smaller values of s indicate less smoothing. optional If non-zero. ﬁnd t and c for a given smoothing factor. If the weights represent the inverse of the standard-deviation of y. The user can use s to control the trade-off between closeness and smoothness of ﬁt. then return optional outputs. then a good s value should be found in the range (m-sqrt(2*m).dev6665 Examples >>> >>> >>> >>> >>> >>> x = linspace(0. t=None. where g(x) is the smoothed interpolation of (x. If task==1. Cubic splines are recommended. task=0. Recommended values of s depend on the weights. 10. Defaults to u[0] and u[-1]. tck) plot(x. these values are calculated automatically as M = len(x[0]): v[0] = 0 v[i] = v[i-1] + distance(x[i]. where m is the number of data points in x. default is 3. The amount of smoothness is determined by satisfying the conditions: sum((w * (y . s. s : ﬂoat. y2) scipy. 10. Release 0. which represent a curve in N-dimensional space parametrized by u. nest=None. y) x2 = linspace(0. s=None. ue=None.5. optional If task==0 (default). optional An array of parameter values. 1 <= k <= 5. u=None.interpolate. Given a list of N rank-1 arrays. optional A smoothing condition.

bisplrep. optional Non-zero to suppress messages. spalde.k) containing the vector of knots. splev. ier : int An integer ﬂag about splrep success.SciPy Reference Guide. ier. BivariateSpline Notes See splev for evaluation of the spline and its derivatives. per : int. Values of y[m-1] and w[m-1] are not used.x[0] and a smooth periodic spline approximation is returned.splev(x. [R21] scipy. Returns tck : tuple A tuple (t. data points are considered periodic with period x[m-1] .10. Parameters x : array_like A 1-D array of points at which to return the value of the smoothed spline or its derivatives. Otherwise an error is raised. UnivariateSpline. Always large enough is nest=m+k+1. tck. u should be given. msg : str A message corresponding to the integer ﬂag. If ier in [1. coefﬁcients. then the parameter values. evaluate the value of the smoothing polynomial and its derivatives.2.c. der=0.interpolate. ext=0) Evaluate a B-spline or its derivatives. This is a wrapper around the FORTRAN routines splev and splder of FITPACK. tck : tuple A sequence of length 3 returned by splrep or splprep containing the knots. Reference . [R20]. Success is indicated if ier<=0. sproot. and the degree of the spline. and degree of the spline.3] an error occurred but was not raised. Given the knots and coefﬁcients of a B-spline representation.dev6665 An over-estimate of the total number of knots of the spline to help in determining the storage space. optional If non-zero. See Also: splrep. bisplev. References [R19]. Release 0. the B-spline coefﬁcients. fp : ﬂoat The weighted sum of squared residuals of the spline approximation. If tck was returned from splprep. u : array An array of the values of the parameter. quiet : int. By default nest=m/2.0. splint. 248 Chapter 3.

evaluate the deﬁnite integral of the smoothing polynomial between two given points. Returns y : ndarray or list of ndarrays An array of values representing the spline function evaluated at the points in x. Release 0. sproot. splrep. full_output=0) Evaluate the deﬁnite integral of a B-spline. the B-spline coefﬁcients. full_output : int. spalde.10. b : ﬂoat The end-points of the integration interval.5.c. Parameters a. return the extrapolated value. Interpolation (scipy.k) containing the vector of knots. and the degree of the spline (see splev).interpolate) 249 . UnivariateSpline. [R16] scipy. raise a ValueError The default value is 0. bisplrep. spalde. BivariateSpline 3. optional Non-zero to return optional output. splev. splint. tck : tuple A tuple (t. sproot. then this is a list of arrays representing the curve in N-dimensional space. ext : int Controls the value returned for elements of x not in the interval deﬁned by the knot sequence. wrk : ndarray An array containing the integrals of the normalized B-splines deﬁned on the set of knots. bisplrep. Given the knots and coefﬁcients of a B-spline.dev6665 der : int The order of derivative of the spline to compute (must be less than or equal to k). • if ext=1. bisplev References [R14]. return 0 • if ext=2. Returns integral : ﬂoat The resulting integral.splint(a. See Also: splprep.interpolate. tck. b. bisplev. See Also: splprep. [R15].0. • if ext=0. If tck was returned from splrep.SciPy Reference Guide. splrep.

Note that t(k) <= x <= t(n-k+1) must hold for each x. splint. sproot. the B-spline coefﬁcients. bisplev. Returns results : array_like An array (or a list of arrays) containing all derivatives up to order k inclusive for each point x. bisplrep. bisplrep. splev. bisplev.k) containing the vector of knots. mest : int An estimate of the number of zeros (Default is 10). See Also: splprep.10. UnivariateSpline. splrep. x : array_like A point or a set of points at which to evaluate the derivatives. BivariateSpline 250 Chapter 3. the B-spline coefﬁcients. Returns zeros : ndarray An array giving the roots of the spline. BivariateSpline References [R26]. and the degree of the spline. The knots must be a montonically increasing sequence.dev6665 References [R17]. UnivariateSpline.c. splrep. spalde.spalde(x.c.interpolate. splint.SciPy Reference Guide. [R28] scipy.sproot(tck. Reference . [R27]. mest=10) Find the roots of a cubic B-spline.k) containing the vector of knots. Parameters tck : tuple A tuple (t. Release 0. and the degree of the spline. tck) Evaluate all derivatives of a B-spline. See Also: splprep. Given the knots and coefﬁcients of a cubic B-spline compute all derivatives up to order k at a point (or set of points). Given the knots (>=8) and coefﬁcients of a cubic B-spline return the roots of the spline. Parameters tck : tuple A tuple (t.interpolate. splev. [R18] scipy.0. The number of knots must be >= 8.

nyest=None. ky : int. quiet=1) Find a bivariate B-spline representation of a surface.y). z.10.ones(len(x)). 3. z[i]) representing a surface z=f(x. tx. xe=x. By default yb=y. [R13] scipy.5.2*ky+3). If task=-1. optional End points of approximation interval in y. ty=None. Given a set of data points (x[i]. optional A threshold for determining the effective rank of an over-determined linear system of equations (0 < eps < 1). optional Non-zero to return optional outputs.9999999999999998e-17. yb. kx=3.0. optional The degrees of the spline (1 <= kx. ﬁnd knots in x and y and coefﬁcients for a given smoothing factor. s. xb=None. y[i]. xb.dev6665 References [R11]. 251 . y. eps : ﬂoat. eps is not likely to need changing. If task=1. xe : ﬂoat. then nxest = max(kx+sqrt(m/2). nxest. optional Over-estimates of the total number of knots. s.interpolate. [R12].min(). Based on the routine SURFIT from FITPACK. ye = y. bisplrep must have been previously called with task=0 or task=1. ye=None. task=0. ﬁnd coefﬁcients for a given set of knots tx. Third order (kx=ky=3) is recommended.m+sqrt(2*m)) where m=len(x). nxest=None. ky=3. yb=None. ky <= 5). full_output=0. Interpolation (scipy. then a good s-value should be found in the range (m-sqrt(2*m). eps=9. optional A non-negative smoothing factor. ty : ndarray.min(). optional Rank-1 arrays of the knots of the spline for task=-1 full_output : int. s=None.max(). tx=None. nyest : int. compute a B-spline representation of the surface. ye : ﬂoat. optional End points of approximation interval in x. y. Release 0. xe=None.max(). ty.2*kx+3). By default w=np.SciPy Reference Guide. kx. Parameters x. w : ndarray. w=None. max(ky+sqrt(m/2). optional If task=0.bisplrep(x. optional Rank-1 array of weights. ﬁnd knots and coefﬁcients for another value of the smoothing factor. z : ndarray Rank-1 arrays of data points. task : int.interpolate) If None nyest = By default xb = x. s : ﬂoat. If weights correspond to the inverse of the standard-deviation of the errors in z.

Release 0. splint. splev. c. Success is indicated if ier<=0.interpolate. sproot. dx=0. ier. the coefﬁcients.dev6665 quiet : int. optional Non-zero to suppress printing of messages. [R9]. Reference .bisplev(x. ty. splrep. splint.3] an error occurred but was not raised.2. ty) and coefﬁcients (c) of the bivariate B-spline representation of the surface along with the degree of the spline. UnivariateSpline. kx. dx. BivariateSpline 252 Chapter 3. Returns tck : array_like A list [tx. fp : ndarray The weighted sum of squared residuals of the spline approximation. If ier in [1. dy : int. Returns vals : ndarray The B-spline or its derivative evaluated over the set formed by the cross-product of x and y. BivariateSpline Notes See bisplev to evaluate the value of the B-spline given its tck representation. tck : tuple A sequence of length 5 returned by bisplrep containing the knot locations. References [R8]. ky] containing the knots (tx. dy=0) Evaluate a bivariate B-spline and its derivatives. y : ndarray Rank-1 arrays specifying the domain over which to evaluate the spline or its derivative. ky]. UnivariateSpline.10. See Also: splprep. Parameters x. ty. splrep. Based on BISPEV from FITPACK. kx.SciPy Reference Guide. return an array or just a ﬂoat if either x or y or both are ﬂoats. tck. c. [R10] scipy. Return a rank-2 array of spline function values (or spline derivative values) at points given by the cross-product of the rank-1 arrays x and y. sproot. Otherwise an error is raised.0. msg : str A message corresponding to the integer ﬂag. optional The orders of the partial derivatives in x and y respectively. splev. y. and the degree of the spline: [tx. ier : int An integer ﬂag about splrep success. See Also: splprep. In special cases.

kx=3.RectBivariateSpline(x. . Parameters x.5.tx). Can be used for both smoothing and interpolating data.4 2-D Splines See Also: scipy. optional Degrees of the bivariate spline.ty)].interpolate.y. optional Sequence of length 4 specifying the boundary of the rectangular approximation domain.y : array_like 1-D arrays of coordinates in strictly ascending order. y.dev6665 Notes See bisplrep to generate the tck representation.0.size). None.y[i])))**2.size.map_coordinates For data on a grid: RectBivariateSpline(x. Interpolation (scipy. z. class scipy. s=0) Bivariate spline approximation over a rectangular mesh. See Also: SmoothBivariateSpline a smoothing bivariate spline for scattered data bisplrep. Default is 3. None.. None[.10. bbox=[. [R7] 3. ky=3. optional Positive smoothing factor deﬁned for estimation sum((w[i]*(z[i]-s(x[i].max(x.ndimage. By default. s : ﬂoat.interpolate) 253 .tx). Release 0. min(y. None ]. ky : ints. None. References [R5].5. kx. bisplev UnivariateSpline a similar class for univariate spline interpolation condition: Default is 3. z..ty). z : array_like 2-D array of data with shape (x.axis=0) <= s s=0.max(y. which is for interpolation. y. bbox : array_like. bbox=[min(x.]) Bivariate spline approximation over a rectangular mesh. None.SciPy Reference Guide. [R6].

None. tx. None) Bivariate spline s(x.max(y. bisplev UnivariateSpline a similar class for univariate spline interpolation SmoothUnivariateSpline to create a BivariateSpline through the given points LSQUnivariateSpline to create a BivariateSpline using weighted least-squares ﬁtting Methods ev get_coeffs get_knots get_residual integral class scipy.10. kx. None.tx). z. eps=None) Smooth bivariate spline approximation. class scipy. w=None.ty)]. min(y.dev6665 Methods ev get_coeffs get_knots get_residual integral For unstructured data: BivariateSpline SmoothBivariateSpline(x. None. bbox=[min(x. s=None. None. Smooth bivariate spline approximation.0. See Also: bisplrep.SmoothBivariateSpline(x. ye] calculated from a given set of data points (x. w : array_lie.z). None[. z. Release 0.ty). z : array_like 1-D sequences of data points (order is not important). Weighted least-squares bivariate spline approximation.y. ty. y. y.]) LSQBivariateSpline(x. .interpolate.tx). ky=3. kx=3. Parameters x.interpolate.xe] x [yb.. bbox=[. None. optional 254 Chapter 3. Reference . y. optional Sequence of length 4 specifying the boundary of the rectangular approximation domain. ky : ints.SciPy Reference Guide. optional Positive 1-D sequence of weights.y) of degrees kx and ky on the rectangle [xb. y. By default.max(x.y. None ].BivariateSpline Bivariate spline s(x.xe] x [yb.z).. ye] calculated from a given set of data points (x.y) of degrees kx and ky on the rectangle [xb. bbox : array_like. z.

optional Sequence of length 4 specifying the boundary of the rectangular approximation domain. bisplev UnivariateSpline a similar class for univariate spline interpolation LSQUnivariateSpline to create a BivariateSpline using weighted Notes The length of x. None. eps : ﬂoat. optional Positive 1-D sequence of weights.axis=0) <= s Default s=len(w) which should be a good value if 1/w[i] is an estimate of the standard deviation of z[i]. z : array_like 1-D sequences of data points (order is not important).ty)]. tx.interpolate) 255 . s : ﬂoat. ty. By default.tx). min(y.5. Interpolation (scipy. y. optional A threshold for determining the effective rank of an over-determined linear system of equations. bbox : array_like. the default is 1e-16. tx.max(x.0. Default is 3. optional Positive smoothing factor deﬁned for estimation condition: sum((w[i]*(z[i]-s(x[i].y[i])))**2. Methods ev get_coeffs get_knots get_residual integral class scipy. optional Degrees of the bivariate spline. y.interpolate. y and z should be at least (kx+1) * (ky+1). z. See Also: bisplrep.10.max(y. bbox=[. s : ﬂoat. Default is 3.dev6665 Degrees of the bivariate spline. eps should have a value between 0 and 1. None. w=None. bbox=[min(x. w : array_lie. Release 0. eps=None) Weighted least-squares bivariate spline approximation. ky=3. Parameters x.tx). ty : array_like Strictly ordered 1-D sequences of knots coordinates. None ]. kx. optional 3.LSQBivariateSpline(x.SciPy Reference Guide.ty). None. kx=3. ky : ints.

min(). y. Based on the routine SURFIT from FITPACK. compute a B-spline representation of the surface.SciPy Reference Guide. nxest=None. s=None.interpolate. y. xe.. By default w=np. tck[. yb=None. eps : ﬂoat. w. z : ndarray Rank-1 arrays of data points. ye = y. xe=x. task=0. optional A threshold for determining the effective rank of an over-determined linear system of equations. xb=None. . Parameters x.max(). full_output=0.y[i])))**2. xe : ﬂoat. See Also: bisplrep.9999999999999998e-17. nyest=None. y. bisplev UnivariateSpline a similar class for univariate spline interpolation SmoothUnivariateSpline To create a BivariateSpline through the given points Notes The length of x. Release 0. ye=None.dev6665 Positive smoothing factor deﬁned for estimation condition: sum((w[i]*(z[i]-s(x[i]. y and z should be at least (kx+1) * (ky+1). ye. By default yb=y. yb.10. dy]) Find a bivariate B-spline representation of a surface.. z[. Reference . 256 Chapter 3.y). z. quiet=1) Find a bivariate B-spline representation of a surface. kx=3. w=None. eps=9.max().]) bisplev(x. Methods ev get_coeffs get_knots get_residual integral Low-level interface to FITPACK functions: bisplrep(x. optional End points of approximation interval in x.axis=0) <= s Default s=len(w) which should be a good value if 1/w[i] is an estimate of the standard deviation of z[i]. kx. y. z[i]) representing a surface z=f(x. kx. Given a set of data points (x[i]. xb. optional Rank-1 array of weights. ye : ﬂoat. yb. w : ndarray. the default is 1e-16. xb. ky=3.min().bisplrep(x.0. scipy. Evaluate a bivariate B-spline and its derivatives.ones(len(x)). y[i]. optional By default xb = x. ty=None. dx. eps should have a value between 0 and 1. ky : int. xe=None. optional End points of approximation interval in y. tx=None.

5.interpolate) 257 .2*kx+3). BivariateSpline Notes See bisplev to evaluate the value of the B-spline given its tck representation. optional A threshold for determining the effective rank of an over-determined linear system of equations (0 < eps < 1). s. splint.3] an error occurred but was not raised. max(ky+sqrt(m/2).SciPy Reference Guide.10. Release 0. If task=-1. optional Non-zero to suppress printing of messages. then nxest = max(kx+sqrt(m/2). sproot. Interpolation (scipy. s : ﬂoat. splrep. eps is not likely to need changing. eps : ﬂoat. fp : ndarray The weighted sum of squared residuals of the spline approximation. ty : ndarray. If task=1. s. Success is indicated if ier<=0. c. If weights correspond to the inverse of the standard-deviation of the errors in z. UnivariateSpline.2. optional A non-negative smoothing factor. optional Rank-1 arrays of the knots of the spline for task=-1 full_output : int. ky] containing the knots (tx. ty. nyest : int. bisplrep must have been previously called with task=0 or task=1. optional If task=0.0. ﬁnd coefﬁcients for a given set of knots tx. then a good s-value should be found in the range (m-sqrt(2*m). ky <= 5). splev.dev6665 The degrees of the spline (1 <= kx. nxest. ﬁnd knots and coefﬁcients for another value of the smoothing factor.2*ky+3). Third order (kx=ky=3) is recommended. quiet : int. ier.m+sqrt(2*m)) where m=len(x). optional Non-zero to return optional outputs. ier : int An integer ﬂag about splrep success. msg : str A message corresponding to the integer ﬂag. Returns tck : array_like A list [tx. optional Over-estimates of the total number of knots. See Also: splprep. ty) and coefﬁcients (c) of the bivariate B-spline representation of the surface along with the degree of the spline. ty. Otherwise an error is raised. If ier in [1. kx. If None nyest = 3. tx. ﬁnd knots in x and y and coefﬁcients for a given smoothing factor. task : int.

ky]. ty.dev6665 References [R8].SciPy Reference Guide. Based on BISPEV from FITPACK. Returns vals : ndarray The B-spline or its derivative evaluated over the set formed by the cross-product of x and y. splev. y. dy=0) Evaluate a bivariate B-spline and its derivatives. [R7] 3. c. . Return a rank-2 array of spline function values (or spline derivative values) at points given by the cross-product of the rank-1 arrays x and y. . Given two 1-D arrays x and w. Estimate the Taylor polynomial of f at x by polynomial ﬁtting.) scipy. UnivariateSpline. return an array or just a ﬂoat if either x or y or both are ﬂoats. tck : tuple A sequence of length 5 returned by bisplrep containing the knot locations.interpolate. Do not expect to be able to use more than about 20 points even if they are chosen optimally.10. BivariateSpline Notes See bisplrep to generate the tck representation. See Also: splprep. Warning: This implementation is numerically unstable. degree... [R10] scipy. w) approximate_taylor_polynomial(f. Reference Return a Lagrange interpolating polynomial.5. and the degree of the spline: [tx.0.interpolate. optional The orders of the partial derivatives in x and y respectively. w).5 Additional tools lagrange(x. tck. References [R5]. kx. dx. x. w : array_like 258 Chapter 3. splrep. Parameters x : array_like x represents the x-coordinates of a set of datapoints.lagrange(x. [R9]. Parameters x.bisplev(x. w) Return a Lagrange interpolating polynomial. Release 0. dy : int. dx=0. returns the Lagrange interpolating polynomial through the points (x. the coefﬁcients. y : ndarray Rank-1 arrays specifying the domain over which to evaluate the spline or its derivative. [R6]. In special cases. sproot. splint.

use degree. x : scalar The point at which the polynomial is to be evaluated. Must be chosen carefully. **kwargs[.6. mdict[. Notes The appropriate choice of “scale” is a trade-off. Parameters f : callable The function whose Taylor polynomial is sought.routines.io) 259 . i. The algorithm used becomes numerically unstable around order 30 even under ideal circumstances. scale. scipy. appendmat]) savemat(ﬁle_name. Input and output (scipy.10.io.6.io) See Also: numpy-reference. f will be evaluated order+1 times. mdict. too large and the function differs from its Taylor polynomial too much to get a good answer.6 Input and output (scipy. Returns p : poly1d instance The Taylor polynomial (translated to the origin. . order : int or None The order of the polynomial to be used in the ﬁtting. scipy. appendmat. so that for example p(0)=f(x)). Function values spread over a range this wide are used to ﬁt the polynomial.interpolate. **kwargs) Load MATLAB ﬁle Parameters ﬁle_name : str 3. too small and round-off errors overwhelm the higher-order terms. degree. x. 3.]) Load MATLAB ﬁle Save a dictionary of names and arrays into a MATLAB-style .dev6665 w represents the y-coordinates of a set of datapoints.SciPy Reference Guide.0.io (in Numpy) 3.approximate_taylor_polynomial(f. mdict=None.loadmat(ﬁle_name. f(x).1 MATLAB® ﬁles loadmat(ﬁle_name..mat ﬁle.. Release 0. If None. appendmat=True. order=None) Estimate the Taylor polynomial of f at x by polynomial ﬁtting.e. Should accept a vector of x values. Choosing order somewhat larger than degree may improve the higher-order terms. degree : int The degree of the Taylor polynomial scale : scalar The width of the interval to use to evaluate the Taylor polynomial.

optional Returns matrices as would be loaded by MATLAB (implies squeeze_me=False. matlab_compatible : bool. You will need an HDF5 python library to read matlab 7. Because scipy does not supply one.7.3 format mat ﬁles.10.SciPy Reference Guide. ‘little’. optional Whether to squeeze unit matrix dimensions or not.read all variables in ﬁle. The default setting is True.dev6665 Name of the mat ﬁle (do not need .io. optional None by default. mdict. Reference . struct_as_record=True). byte_order : str or None. return arrays in same dtype as would be loaded into MATLAB (instead of the dtype with which they are saved). implying byte order guessed from mat ﬁle. do_compression=False. or as old-style numpy arrays with dtype=object. mat_dtype : bool. appendmat=True. ‘<’. we do not implement the HDF5 / 7. appendmat : bool. ‘>’). format=‘5’. Release 0. giving names of the matlab variables to read from the ﬁle. struct_as_record : bool. because it allows easier round-trip load and save of MATLAB ﬁles. long_ﬁeld_names=False.style . m_dict : dict. possibly saving some read processing.mat ﬁle. scipy. The reader will skip any variable with a name not in this sequence.x (returning numpy object arrays). Otherwise can be one of (‘native’. optional Dictionary in which to insert matﬁle variables. optional True to append the . v6 and v7 to 7. chars_as_strings : bool.2 matﬁles are supported.mat ﬁle. 260 Chapter 3.0. optional Whether to convert char arrays to string arrays. This saves the array objects in the given dictionary to a MATLAB. Setting this ﬂag to False replicates the behaviour of scipy version 0.mat extension to the end of the given ﬁlename. ‘=’. optional Whether to load MATLAB structs as numpy record arrays. variable_names : None or sequence If None (the default) .0). Otherwise variable_names should be a sequence of strings. mat_dtype=True.savemat(ﬁle_name. and loaded matrices as values Notes v4 (Level 1. squeeze_me : bool. ‘BIG’.mat extension if appendmat==True) Can also pass open ﬁle-like object. if not already present.3 interface here. optional If True. oned_as=None) Save a dictionary of names and arrays into a MATLAB-style . chars_as_strings=False. Returns mat_dict : dict dictionary with variable names as keys.

optional True to append the . string. a[. if not already present.MatFile4Writer is called.10. mio5. 3. Default is False. optional If ‘column’. Writes the sparse or dense matrix A to a Matrix Market formatted ﬁle.maximum ﬁeld name length in a structure is 31 characters which is the documented maximum length. ‘4’ for MATLAB 4 . scipy. appendmat : bool. If ‘row’. write 1-D numpy arrays as column vectors. m_dict : dict Dictionary from which to save matﬁle variables. • True . comment.maximum ﬁeld name length in a structure is 63 characters which works for Matlab 7. ‘4’}. Input and output (scipy. oned_as : {‘column’.MatFile5Writer is called.6.dev6665 Parameters ﬁle_name : str or ﬁle-like object Name of the . optional ‘5’ (the default) for MATLAB 5 and up (to 7. Release 0.6.mat extension to the end of the given ﬁlename. which sets oned_as to ‘column’ if it had been None. ‘row’}.mminfo(source) Queries the contents of the Matrix Market ﬁle ‘ﬁlename’ to extract size and storage information. stacklevel=2) without being more speciﬁc as to precisely when the change will take place. write 1D numpy arrays as row vectors.MatFile4Writer.warn("Using oned_as default value (’column’)" + " This will change to ’row’ in future versions". optional • False .MatFile5Writer Notes If format == ’4’. but ﬁrst it executes: warnings.0. precision]) Queries the contents of the Matrix Market ﬁle ‘ﬁlename’ to Reads the contents of a Matrix Market ﬁle ‘ﬁlename’ into a matrix.io. optional Whether to compress matrices on write.2 Matrix Market ﬁles mminfo(source) mmread(source) mmwrite(target.mat ﬁle (. This is the default.mat extension not needed if appendmat == True). ﬁeld. If format == ’5’.2). 3.6 do_compression : bool. FutureWarning.io) 261 .SciPy Reference Guide. mio5. which sets oned_as to ‘row’ if it had been None. format : {‘5’. See Also: mio4. mio4.mat ﬁles long_ﬁeld_names : bool. Can also pass open ﬁle_like object.

io. 3. ‘integer’} symm : {‘general’.cols : int Number of matrix rows and columns entries : int Number of non-zero entries of a sparse matrix or rows*cols for a dense matrix format : {‘coordinate’.io. ‘complex’. scipy. ‘skew-symmetric’.3 Other save_as_module([ﬁle_name. optional precision : : Number of digits to display for real or complex values.save_as_module(ﬁle_name=None.6. ‘pattern’.0. optional File name of the module to save.mtz.SciPy Reference Guide. Returns a: : Sparse or full matrix scipy. ﬁeld=None. precision=None) Writes the sparse or dense matrix A to a Matrix Market formatted ﬁle.mmread(source) Reads the contents of a Matrix Market ﬁle ‘ﬁlename’ into a matrix.dev6665 Parameters source : ﬁle Matrix Market ﬁlename (extension . comment=’‘. Parameters target : ﬁle Matrix Market ﬁlename (extension . a. ‘complex’.mtx) or open ﬁle object Returns rows. Parameters source : ﬁle Matrix Market ﬁlename (extensions . 262 Chapter 3.mmwrite(target. Parameters ﬁle_name : str. Reference . ‘array’} ﬁeld : {‘real’.10.mtx. ‘symmetric’. .gz) or open ﬁle object.mtx) or open ﬁle object a : array like Sparse or full matrix comment : str comments to be prepended to the Matrix Market ﬁle ﬁeld : {‘real’. ‘hermitian’} scipy. data]) Save the dictionary “data” into a module and shelf named save. ‘integer’}. Release 0. data=None) Save the dictionary “data” into a module and shelf named save. ‘pattern’.io.

Input and output (scipy.io.wavfile. Returns rate : int Sample rate of wav ﬁle data : numpy array Data read from wav ﬁle Notes •The ﬁle can be an open ﬁle or a ﬁlename. •The returned sample rate is a Python integer •The data is returned as a numpy array with a data-type determined from the ﬁle. optional The dictionary to store in the module. data : ndarray A 1-D or 2-D numpy array of integer data-type. Nchannels).0. rate : int The sample rate (in samples/sec). use a 2-D array of shape (Nsamples.4 Wav sound ﬁles (scipy.wavfile. data) Write a numpy array as a WAV ﬁle Parameters ﬁlename : ﬁle The name of the ﬁle to write (will be over-written). •The bits-per-sample will be determined by the data-type.write(ﬁlename.wavfile) read(ﬁle) write(ﬁlename.io.6.io. •To write multiple-channels. 3.10. 3. data) Return the sample rate (in samples/sec) and data from a WAV ﬁle Write a numpy array as a WAV ﬁle scipy.io) 263 .read(ﬁle) Return the sample rate (in samples/sec) and data from a WAV ﬁle Parameters ﬁle : ﬁle Input wav ﬁle. scipy. rate.SciPy Reference Guide.dev6665 data : dict. Notes •Writes a simple uncompressed WAV ﬁle. rate. Release 0.6.

. """ >>> f = open(’testdata..0. Examples >>> from scipy.write(content) >>> f. ARFF is a text ﬁle format which support numerical. See the WEKA website for more details about arff format and available datasets. (4..blue.red .. For example. if one of the attributes is called ‘pressure’. 3. dtype=[(’width’.. ’black’) loadarff(ﬁlename) Read an arff ﬁle..0. ’blue’). etc.25.75.0.green.io.5 Arff ﬁles (scipy. meta = arff.io... (3. ’green’. which can be accessed much like a dictionary of numpy arrays.. @attribute height numeric .loadarff(ﬁlename) Read an arff ﬁle.25....0.5. ’red’)].dev6665 3. accessible by attribute names.arff’.io import arff >>> content = """ . ’w’) >>> f. ’|S6’)]) >>> meta Dataset: foo width’s type is numeric height’s type is numeric color’s type is nominal.loadarff(’testdata.00.blue .. (’height’.75. The data is returned as a record array.black} .. range is (’red’.3. ’yellow’. 3. 5. @relation foo . 264 Chapter 3.4. then its ﬁrst 10 data points can be accessed from the data record array like so: data[’pressure’][0:10] Parameters ﬁlename : str the name of the ﬁle Returns data : record array The data of the arff ﬁle.0.green .6.SciPy Reference Guide.arff’) >>> data array([(5.yellow. ’<f8’). 3. Reference . @attribute color {red. @attribute width numeric .arff) Module to read ARFF ﬁles.5. the relation (name of the dataset).. string and data values. meta : MetaData Contains information about the arff ﬁle such as name and type of attributes. ’green’)..10.0.. @data .... The format can also represent missing data and sparse data.3. 4. (’color’. Release 0. ’blue’.arff.close() >>> data. ’<f8’). 4. which are the standard data format for WEKA. scipy.

mmap. See here for more info. ‘w’}.6.SciPy Reference Guide. It cannot read ﬁles with sparse data ({} in the ﬁle). version=1) A ﬁle object for NetCDF data. version]) netcdf_variable(data. default is ‘r’ mmap : None or bool. Notes This function should be able to read most arff ﬁles. Default is True when ﬁlename is a ﬁle name. NotImplementedError : The ARFF ﬁle has an attribute which is not supported yet. False when ﬁlename is a ﬁle-like object version : {1. mapping dimension names to their associated lengths and variable names to variables. shape. 2}.netcdf) netcdf_file(ﬁlename[.0. this function can read ﬁles with missing data (? in the ﬁle). mode=’r’. 3. .) A ﬁle object for NetCDF data. optional read-write mode. typecode. optional version of netcdf to read / write.netcdf_file(ﬁlename.io) 265 . Parameters ﬁlename : string or ﬁle-like string -> ﬁlename mode : {‘r’. However. respectively.6 Netcdf (scipy. Global ﬁle attributes are created by assigning to an attribute of the netcdf_ﬁle object. representing the data points as NaNs.. Input and output (scipy. mode.dev6665 Raises ‘ParseArffError‘ : This is raised if the given ﬁle is not ARFF-formatted. A netcdf_ﬁle object has two standard attributes: dimensions and variables.6. Release 0.io.. class scipy. The values of both are dictionaries.io. All other attributes correspond to global attributes deﬁned in the NetCDF ﬁle. Application programs should never modify these dictionaries. Methods close createDimension createVariable flush sync 3. Not implemented functionality include: •date type attributes •string type attributes It can read ﬁles with numeric and nominal attributes.netcdf. A data object for the netcdf module. Default is 1. where 1 means Classic format and 2 means 64-bit offset format. mmap=None.10. optional Whether to mmap ﬁlename when reading.

Data is read by indexing and written by assigning to an indexed subset. netcdf_variable objects are constructed by calling the method netcdf_ﬁle. the entire array can be accessed by the index [:] or (for scalars) by using the methods getValue and assignValue. Typically. but the shape cannot be modiﬁed.SciPy Reference Guide. See Also: isrec. this is initialized as empty. This should match the lengths of the variable’s dimensions. attributes=None) A data object for the netcdf module. attributes : dict. Reference .netcdf. whose value is the tuple of dimension names.netcdf_variable(data. All other attributes correspond to variable attributes deﬁned in the NetCDF ﬁle. shape Methods assignValue getValue typecode list of str List of names of dimensions used by the variable object.createVariable on the netcdf_ﬁle object. shape : sequence of ints The shape of the array. typecode : dtype character code Desired data-type for the data array. There is another read-only attribute dimensions. Must be in the same order of the dimension lengths given by shape. except that their data resides in a ﬁle. optional Attribute values (any type) keyed by string names. but with the proper shape. Properties 266 Chapter 3. shape Attributes dimensions isrec.10.dev6665 class scipy. netcdf_variable objects also have attribute shape with the same meaning as for arrays.io. Parameters data : array_like The data array that holds the values for the variable. dimensions : sequence of strings The names of the dimensions used by the variable. These attributes become attributes for the netcdf_variable object. Variable attributes are created by assigning to an attribute of the netcdf_variable object.0. Release 0. shape. dimensions. typecode. netcdf_variable objects behave much like array objects deﬁned in numpy.

trans. or not 2-dimensional.. Returns ainv : ndarray Inverse of the matrix a. -0. [ 1.. . Linear algebra (scipy.linalg. 1. shape (M.. assuming a is banded matrix.linalg.]) solve_triangular(a. overwrite_a]) norm(a[.]]) Compute the inverse of a matrix.]]) >>> sp. [ 0.5]]) >>> np. overwrite_a]) solve(a.10.linalg.inv(a)) array([[ 1. 2. sym_pos. sp.linalg. b[.]) det(a[.array([[1. .7. Compute the determinant of a matrix Matrix or vector norm. cond..) or (M. b[. Solve the equation a x = b for x Solve the equation a x = b for x. M) b : array. debug=False) Solve the equation a x = b for x Parameters a : array.]) solve_banded(l.0. Solve equation a x = b. overwrite_ab. ValueError : : If a is not square. overwrite_ab. Default is False. scipy.solve(a. cond.. assuming a is a triangular matrix.inv(a) array([[-2. overwrite_a=False) Compute the inverse of a matrix. lower=False.. ord]) lstsq(a. Raises LinAlgError : : If a is singular. 1. b[. overwrite_b]) pinv(a[.5.1 Basics inv(a[.. Solve the equation a x = b for x.. Compute least-squares solution to equation Ax = b. cond.. [3. . ].SciPy Reference Guide. Compute the (Moore-Penrose) pseudo-inverse of a matrix. rcond]) pinv2(a[. b.7.. overwrite_b=False. 4. Release 0.].]) solveh_banded(ab. 0. b[. lower. sym_pos=False. overwrite_a.dev6665 3. . ab..linalg) 267 . b[. Examples >>> a = np.7 Linear algebra (scipy. Parameters a : array_like Square matrix to be inverted. overwrite_a.. shape (M. .linalg) 3.dot(a.]. overwrite_a=False. overwrite_a : bool. optional Discard data in a (may improve performance). N) sym_pos : boolean 3. Compute the (Moore-Penrose) pseudo-inverse of a matrix. rcond]) scipy. lower.inv(a.

assuming a is banded matrix.solveh_banded(ab.10. j] == a[i. shape (M. Reference . integer) Number of non-zero lower and upper diagonals ab : array.) or (M.linalg.SciPy Reference Guide.6).dev6665 Assume a is symmetric and positive deﬁnite lower : boolean Use only data contained in the lower triangle of a. a is Hermitian positive-deﬁnite banded matrix. l=2): * a00 a10 a20 a01 a11 a21 a31 a12 a22 a32 a42 a23 a33 a43 a53 a34 a44 a54 * a45 a55 * * Parameters (l. shape (M.j. shape (M. overwrite_b=False. overwrite_a : boolean Allow overwriting data in a (may enhance performance) overwrite_b : boolean Allow overwriting data in b (may enhance performance) Returns x : array.) or (M. b.j] Example of ab (shape of a is (6. overwrite_ab=False. u) : (integer.solve_banded((l.0. The matrix a is stored in ab using the matrix diagonal orded form: ab[u + i . overwrite_b=False. debug=False) Solve the equation a x = b for x. lower=False) Solve equation a x = b. u=1. Release 0. K) Right-hand side overwrite_ab : boolean Discard data in ab (may enhance performance) overwrite_b : boolean Discard data in b (may enhance performance) Returns x : array. ab. N) depending on b Solution to the system a x = b Raises LinAlgError if a is singular : scipy.linalg. overwrite_ab=False. b. u). The matrix a is stored in ab either in lower diagonal or upper diagonal ordered form: 268 Chapter 3. M) Banded matrix b : array. if sym_pos is true.) or (M. shape (l+u+1. K) The solution to the system a x = b scipy. Default is to use upper triangle.

shape (M. shape (u + 1. M) b : array. K) Right-hand side overwrite_ab : boolean Discard data in ab (may enhance performance) overwrite_b : boolean Discard data in b (may enhance performance) lower : boolean Is the matrix in the lower form. trans : {0.linalg) 269 . Linear algebra (scipy. M) Banded matrix b : array. j] == a[i. ‘C’} Type of system to solve: trans 0 or ‘N’ 1 or ‘T’ 2 or ‘C’ system ax=b a^T x = b a^H x = b unit_diagonal=False.solve_triangular(a. shape (M. Parameters a : array. debug=False) Solve the equation a x = b for x. i >= j) Example of ab (shape of a is (6. shape (M.linalg.j. 2. ‘N’. b. over- unit_diagonal : boolean If True. Default is to use upper triangle.j. Release 0. 3. diagonal elements of A are assumed to be 1 and will not be referenced. trans=0.dev6665 ab[u + i .0.7. shape (M. u=2): upper form: a02 a13 a24 a35 * * a01 a12 a23 a34 a45 * a00 a11 a22 a33 a44 a55 lower form: a00 a11 a22 a33 a44 a55 a10 a21 a32 a43 a54 * a20 a31 a42 a53 * * Cells marked with * are not used.) or (M. ‘T’.j] (if upper form. Parameters ab : array. lower=False. assuming a is a triangular matrix. write_b=False.) or (M. N) lower : boolean Use only data contained in the lower triangle of a. i <= j) ab[ i .10.6). j] == a[i.j] (if lower form. (Default is upper form) Returns x : array. 1. K) The solution to the system a x = b scipy.SciPy Reference Guide.) or (M.

shape (M. depending on the value of the ord parameter. inf.dev6665 overwrite_b : boolean Allow overwriting data in b (may enhance performance) Returns x : array. ord=None) Matrix or vector norm. shape (M.0. The following norms can be calculated: 270 Chapter 3. optional Order of the norm (see table under Notes). N) Input array. not a mathematical ‘norm’. the result is.) or (M.linalg.norm(a. M) Returns det : ﬂoat or complex Determinant of a Notes The determinant is computed via LU factorization. inf means numpy’s inf object. -inf.) or (M.linalg. Reference . Release 0. but it may still be useful for various numerical purposes.SciPy Reference Guide. This function is able to return one of seven different matrix norms. Parameters x : array_like. overwrite_a=False) Compute the determinant of a matrix Parameters a : array. shape (M. strictly speaking. Notes For values of ord <= 0. ord : {non-zero int. Returns n : ﬂoat Norm of the matrix or vector. LAPACK routine z/dgetrf. or one of an inﬁnite number of vector norms (described below). ‘fro’}.det(a. scipy.10. N) depending on b Solution to the system a x = b Raises LinAlgError : If a is singular scipy.

SciPy Reference Guide.norm(b. axis=1)) – max(sum(abs(x). 2) 7.norm(a. -3.norm(b. ’fro’) 7.inf) 0 >>> LA.3484692283495345 i. -1.dev6665 ord None ‘fro’ inf -inf 0 1 -1 2 -2 other norm for matrices Frobenius norm Frobenius norm max(sum(abs(x).norm(b) 7.j )2 ]1/2 3.linalg) 271 .norm(a.inf) 4 >>> LA. -np. value) smallest singular value – norm for vectors 2-norm – max(abs(x)) min(abs(x)) sum(x != 0) as below as below as below as below sum(abs(x)**ord)**(1. axis=0)) min(sum(abs(x).norm(a. Linear algebra (scipy. [-1.6566128774142013e-010 >>> LA. 1) 7 >>> LA. np.norm(a) 7.inf) 2 >>> LA. axis=0)) 2-norm (largest sing.745966692414834 >>> LA.arange(9) . 3. 1.norm(b. 3)) >>> b array([[-4.norm(a. axis=1)) min(sum(abs(x). 2.0.j abs(ai. [ 2.norm(a./ord) The Frobenius norm is given by [R32]: ||A||F = [ References [R32] Examples >>> from numpy import linalg as LA >>> a = np. -3.norm(b. 1]. 1) 20 >>> LA.745966692414834 >>> LA. -1) 6 >>> LA. 4]]) >>> LA. 4]) 3.reshape((3. Release 0.745966692414834 >>> LA. -np. -2]. >>> b = a. 0. 0. -2.4 >>> a array([-4.745966692414834 >>> LA. np.norm(b.10.7.inf) 9 >>> LA. 2) 7.norm(b. -1) -4.

Returns x : array. shape (M.A x| is minimized.dev6665 >>> LA. shape (M. shape (min(M.SciPy Reference Guide. Singular values smaller than rcond * largest_singular_value are considered zero. overwrite_a=False.) or (M. optional Discard data in a (may enhance performance). overwrite_a : bool. used to determine effective rank of a. K) depending on shape of b Least-squares solution.N).norm(a.) or (K. Default is False.) shape array. residues : ndarray. 3) 5.). -2) 1. this is an (1. See Also: optimize. If b was 1-D. optional Discard data in b (may enhance performance). shape () or (1. Default is False. overwrite_b=False) Compute least-squares solution to equation Ax = b. Compute a vector x such that the 2-norm |b .nnls linear least squares with non-negativity constraint 272 Chapter 3. Reference . b. -2) nan >>> LA. s : array.norm(b. Parameters a : array. K) Right hand side matrix or vector (1-D or 2-D array). shape (N. otherwise the shape is (K. cond=None. rank : int Effective rank of matrix a. overwrite_b : bool.linalg.lstsq(a.) Singular values of a. Release 0.) or (N. The condition number of a is abs(s[0]/s[-1]).norm(a. optional Cutoff for ‘small’ singular values. If rank of matrix a is < N or > M this is an empty array.10.0. Raises LinAlgError : : If computation does not converge. squared 2-norm for each column in b . -3) nan scipy. N) Left hand side matrix (2-D array).8570331885190563e-016 >>> LA. cond : ﬂoat.norm(a.8480354764257312 >>> LA. b : array.) Sums of residues.a x.

suitable machine precision is used. a))) True >>> allclose(B. a))) True >>> allclose(B.pinv2(a) >>> allclose(a. Parameters a : array. cond=None. 6) >>> B = linalg. shape (M. Linear algebra (scipy. Calculate a generalized inverse of a matrix using its singular-value decomposition and including all ‘large’ singular values. Parameters a : array. M) Raises LinAlgError if computation does not converge : Examples >>> from numpy import * >>> a = random. M) Raises LinAlgError if SVD computation does not converge : Examples >>> from numpy import * >>> a = random. B))) True values smaller than 3. rcond=None) Compute the (Moore-Penrose) pseudo-inverse of a matrix.pinv(a) >>> allclose(a.dev6665 scipy. Singular values smaller than rcond*largest_singular_value are considered zero.linalg. cond=None.pinv2(a. Release 0. Returns B : array. dot(B.randn(9. dot(B.linalg) 273 .7.linalg. N) Matrix to be pseudo-inverted cond.SciPy Reference Guide. dot(B. If None or -1. shape (N.randn(9. Singular rcond*largest_singular_value are considered zero. dot(a. shape (M. shape (N. rcond : ﬂoat Cutoff for ‘small’ singular values in the least-squares solver. rcond=None) Compute the (Moore-Penrose) pseudo-inverse of a matrix. 6) >>> B = linalg.10. dot(B. Returns B : array.0. B))) True scipy. dot(a. dot(a. dot(a.pinv(a. rcond : ﬂoat or None Cutoff for ‘small’ singular values. Calculate a generalized inverse of a matrix using a least-squares solver. N) Matrix to be pseudo-inverted cond.

scipy.i] where .H vl[:.. (if right == True) : vr : double or complex array. shape (M. left=False. If omitted..H vl[:.linalg..]) eigvals_banded(a_band[.. overwrite_b=False) Solve an ordinary or generalized eigenvalue problem of a square matrix.]) eigvalsh(a[. . M) Right-hand side matrix in a generalized eigenvalue problem.SciPy Reference Guide. right=True. overwrite_a=False.0. Release 0. shape (M. eigvals_only. b. left : boolean Whether to calculate and return left eigenvectors right : boolean Whether to calculate and return right eigenvectors overwrite_a : boolean Whether to overwrite data in a (may improve performance) overwrite_b : boolean Whether to overwrite data in b (may improve performance) Returns w : double or complex array. overwrite_a.i] = w[i]. Compute eigenvalues from an ordinary or generalized eigenvalue problem. shape (M. eigvals_only. (if left == True) : vl : double or complex array. M) 274 Chapter 3.eig(a.conj() b.]) Solve an ordinary or generalized eigenvalue problem of a square matrix. lower. shape (M. right..i]. lower. identity matrix is assumed.. lower. Parameters a : array. b=None. b. .]) eig_banded(a_band[. .10.i] = w[i] b vr[:. b.]) eigvals(a[.. Find eigenvalues w and right or left eigenvectors of a general matrix: a vr[:..i] a. lower.2 Eigenvalue Problem eig(a[.) The eigenvalues.. b. b : array. overwrite_a]) eigh(a[. shape (M. . M) The normalized left eigenvector corresponding to the eigenvalue w[i] is the column v[:.dev6665 3. Reference . Solve real symmetric or complex hermitian band matrix eigenvalue problem. .7. each repeated according to its multiplicity. left. M) A complex or real matrix whose eigenvalues and eigenvectors will be computed. Solve an ordinary or generalized eigenvalue problem for a complex Solve an ordinary or generalized eigenvalue problem for a complex Solve real symmetric or complex hermitian band matrix eigenvalue problem.. overwrite_a.H is the Hermitean conjugation.

linalg) 275 . shape (M. where b is positive deﬁnite: a v[:. Release 0.eigh(a. M) Right-hand side matrix in a generalized eigenvalue problem. Raises LinAlgError if eigenvalue computation does not converge : See Also: eigvalsh eigenvalues of symmetric or Hemitiean arrays eig eigenvalues and right eigenvectors of general arrays eigh eigenvalues and eigenvectors of symmetric/Hermitean arrays. overwrite_a=False) Compute eigenvalues from an ordinary or generalized eigenvalue problem.i].conj() a v[:.conj() b v[:.7.i] = w[i] b v[:. overwrite_a : boolean Whether to overwrite data in a (may improve performance) Returns w : double or complex array. overwrite_a=False. If omitted. eigvals=None. b=None. but not in any speciﬁc order.i] Parameters a : array.10. Find eigenvalues w and optionally eigenvectors v of matrix a.0.) The eigenvalues.i] v[i.i] = w[i] b vr[:. each repeated according to its multiplicity.:]. M) 3. shape (M.i] = 1 Parameters a : array. b : array. Linear algebra (scipy. type=1) Solve an ordinary or generalized eigenvalue problem for a complex Hermitian or real symmetric matrix.linalg. shape (M. identity matrix is assumed. overwrite_b=False.eigvals(a. scipy.i] = w[i] v[i. turbo=True. b=None.dev6665 The normalized right eigenvector corresponding to the eigenvalue w[i] is the column vr[:.:]. M) A complex or real matrix whose eigenvalues and eigenvectors will be computed. Find eigenvalues of a general matrix: a vr[:.SciPy Reference Guide. shape (M. eigvals_only=False. Raises LinAlgError if eigenvalue computation does not converge : See Also: eigh eigenvalues and right eigenvectors for symmetric/Hermitian arrays scipy.linalg. lower=True.

i] = w[i] b v[:. in ascending order. identity matrix is assumed.conj() b v = I type = 3 : v.i] = w[i] v[:.i] overwrite_a : boolean Whether to overwrite data in a (may improve performance) overwrite_b : boolean Whether to overwrite data in b (may improve performance) Returns w : real array. If omitted. or b matrix is not deﬁnite positive. type: integer : Speciﬁes the problem type to be solved: type = 1: a v[:. N) The normalized selected eigenvector corresponding to the eigenvalue w[i] is the column v[:.10. Normalization: type 1 and 3: v. : See Also: 276 Chapter 3.) The N (1<=N<=M) selected eigenvalues. b : array. only for generalized eigenvalue problem and if eigvals=None) eigvals : tuple (lo.i] = w[i] v[:. shape (M. lower : boolean Whether the pertinent array data is taken from the lower or upper triangle of a.0.conj() inv(b) v = I Raises LinAlgError if eigenvalue computation does not converge.i] type = 2: a b v[:. no error is reported : but results will be wrong. Reference . all eigenvalues and eigenvectors are returned. each repeated according to its multiplicity. (Default: lower) eigvals_only : boolean Whether to calculate only eigenvalues and no eigenvectors. If omitted. shape (M. M) A complex Hermitian or real symmetric deﬁnite positive matrix in.SciPy Reference Guide.conj() a inv(v) = w type = 1 or 2: v.dev6665 A complex Hermitian or real symmetric matrix whose eigenvalues and eigenvectors will be computed. (if eigvals_only == False) : v : complex array. shape (N. : an error occurred. (Default: both are calculated) turbo : boolean Use divide and conquer algorithm (faster but expensive in memory. hi) Indexes of the smallest and largest (in ascending order) eigenvalues and corresponding eigenvectors to be returned: 0 <= lo < hi <= M-1. Release 0. Note that : if input matrices are not symmetric or hermitian.i] type = 3: b a v[:.conj() a v = w type 2: inv(v).i].

SciPy Reference Guide, Release 0.10.0.dev6665

eig eigenvalues and right eigenvectors for non-symmetric arrays scipy.linalg.eigvalsh(a, b=None, lower=True, overwrite_a=False, overwrite_b=False, turbo=True, eigvals=None, type=1) Solve an ordinary or generalized eigenvalue problem for a complex Hermitian or real symmetric matrix. Find eigenvalues w of matrix a, where b is positive deﬁnite:

a v[:,i] = w[i] b v[:,i] v[i,:].conj() a v[:,i] = w[i] v[i,:].conj() b v[:,i] = 1

Parameters a : array, shape (M, M) A complex Hermitian or real symmetric matrix whose eigenvalues and eigenvectors will be computed. b : array, shape (M, M) A complex Hermitian or real symmetric deﬁnite positive matrix in. If omitted, identity matrix is assumed. lower : boolean Whether the pertinent array data is taken from the lower or upper triangle of a. (Default: lower) turbo : boolean Use divide and conquer algorithm (faster but expensive in memory, only for generalized eigenvalue problem and if eigvals=None) eigvals : tuple (lo, hi) Indexes of the smallest and largest (in ascending order) eigenvalues and corresponding eigenvectors to be returned: 0 <= lo < hi <= M-1. If omitted, all eigenvalues and eigenvectors are returned. type: integer : Speciﬁes the problem type to be solved: type = 1: a v[:,i] = w[i] b v[:,i] type = 2: a b v[:,i] = w[i] v[:,i] type = 3: b a v[:,i] = w[i] v[:,i] overwrite_a : boolean Whether to overwrite data in a (may improve performance) overwrite_b : boolean Whether to overwrite data in b (may improve performance) Returns w : real array, shape (N,) The N (1<=N<=M) selected eigenvalues, in ascending order, each repeated according to its multiplicity. Raises LinAlgError if eigenvalue computation does not converge, : an error occurred, or b matrix is not deﬁnite positive. Note that : if input matrices are not symmetric or hermitian, no error is reported : 3.7. Linear algebra (scipy.linalg) 277

SciPy Reference Guide, Release 0.10.0.dev6665

but results will be wrong. : See Also: eigvals eigenvalues of general arrays eigh eigenvalues and right eigenvectors for symmetric/Hermitian arrays eig eigenvalues and right eigenvectors for non-symmetric arrays scipy.linalg.eig_banded(a_band, lower=False, eigvals_only=False, overwrite_a_band=False, select=’a’, select_range=None, max_ev=0) Solve real symmetric or complex hermitian band matrix eigenvalue problem. Find eigenvalues w and optionally right eigenvectors v of a:

a v[:,i] = w[i] v[:,i] v.H v = identity

The matrix a is stored in ab either in lower diagonal or upper diagonal ordered form: ab[u + i - j, j] == a[i,j] (if upper form; i <= j) ab[ i - j, j] == a[i,j] (if lower form; i >= j) Example of ab (shape of a is (6,6), u=2):

upper form: a02 a13 a24 a35 * * a01 a12 a23 a34 a45 * a00 a11 a22 a33 a44 a55 lower form: a00 a11 a22 a33 a44 a55 a10 a21 a32 a43 a54 * a20 a31 a42 a53 * *

Cells marked with * are not used. Parameters a_band : array, shape (M, u+1) Banded matrix whose eigenvalues to calculate lower : boolean Is the matrix in the lower form. (Default is upper form) eigvals_only : boolean Compute only the eigenvalues and no eigenvectors. (Default: calculate also eigenvectors) overwrite_a_band: : Discard data in a_band (may enhance performance) select: {‘a’, ‘v’, ‘i’} : Which eigenvalues to calculate

278

Chapter 3. Reference

SciPy Reference Guide, Release 0.10.0.dev6665

select ‘a’ ‘v’ ‘i’

calculated All eigenvalues Eigenvalues in the interval (min, max] Eigenvalues with indices min <= i <= max

select_range : (min, max) Range of selected eigenvalues max_ev : integer For select==’v’, maximum number of eigenvalues expected. For other values of select, has no meaning. In doubt, leave this parameter untouched. Returns w : array, shape (M,) The eigenvalues, in ascending order, each repeated according to its multiplicity. v : double or complex double array, shape (M, M) The normalized eigenvector corresponding to the eigenvalue w[i] is the column v[:,i]. Raises LinAlgError if eigenvalue computation does not converge : scipy.linalg.eigvals_banded(a_band, lower=False, overwrite_a_band=False, select=’a’, select_range=None) Solve real symmetric or complex hermitian band matrix eigenvalue problem. Find eigenvalues w of a:

a v[:,i] = w[i] v[:,i] v.H v = identity

The matrix a is stored in ab either in lower diagonal or upper diagonal ordered form: ab[u + i - j, j] == a[i,j] (if upper form; i <= j) ab[ i - j, j] == a[i,j] (if lower form; i >= j) Example of ab (shape of a is (6,6), u=2):

upper form: a02 a13 a24 a35 * * a01 a12 a23 a34 a45 * a00 a11 a22 a33 a44 a55 lower form: a00 a11 a22 a33 a44 a55 a10 a21 a32 a43 a54 * a20 a31 a42 a53 * *

Cells marked with * are not used. Parameters a_band : array, shape (M, u+1) Banded matrix whose eigenvalues to calculate lower : boolean Is the matrix in the lower form. (Default is upper form) overwrite_a_band: : Discard data in a_band (may enhance performance)

3.7. Linear algebra (scipy.linalg)

279

SciPy Reference Guide, Release 0.10.0.dev6665

select: {‘a’, ‘v’, ‘i’} : Which eigenvalues to calculate select ‘a’ ‘v’ ‘i’ calculated All eigenvalues Eigenvalues in the interval (min, max] Eigenvalues with indices min <= i <= max

select_range : (min, max) Range of selected eigenvalues Returns w : array, shape (M,) The eigenvalues, in ascending order, each repeated according to its multiplicity. Raises LinAlgError if eigenvalue computation does not converge : See Also: eig_banded eigenvalues and right eigenvectors for symmetric/Hermitian band matrices eigvals eigenvalues of general arrays eigh eigenvalues and right eigenvectors for symmetric/Hermitian arrays eig eigenvalues and right eigenvectors for non-symmetric arrays

3.7.3 Decompositions

lu(a[, permute_l, overwrite_a]) lu_factor(a[, overwrite_a]) lu_solve(lu, b[, trans, overwrite_b]) svd(a[, full_matrices, compute_uv, overwrite_a]) svdvals(a[, overwrite_a]) diagsvd(s, M, N) orth(A) cholesky(a[, lower, overwrite_a]) cholesky_banded(ab[, overwrite_ab, lower]) cho_factor(a[, lower, overwrite_a]) cho_solve(c, b[, overwrite_b]) cho_solve_banded(cb, b[, overwrite_b]) qr(a[, overwrite_a, lwork, mode]) schur(a[, output, lwork, overwrite_a]) rsf2csf(T, Z) hessenberg(a[, calc_q, overwrite_a]) Compute pivoted LU decompostion of a matrix. Compute pivoted LU decomposition of a matrix. Solve an equation system, a x = b, given the LU factorization of a Singular Value Decomposition. Compute singular values of a matrix. Construct the sigma matrix in SVD from singular values and size M,N. Construct an orthonormal basis for the range of A using SVD Compute the Cholesky decomposition of a matrix. Cholesky decompose a banded Hermitian positive-deﬁnite matrix Compute the Cholesky decomposition of a matrix, to use in cho_solve Solve the linear equations A x = b, given the Cholesky factorization of A. Solve the linear equations A x = b, given the Cholesky factorization of A. Compute QR decomposition of a matrix. Compute Schur decomposition of a matrix. Convert real Schur form to complex Schur form. Compute Hessenberg form of a matrix.

280

Chapter 3. Reference

SciPy Reference Guide, Release 0.10.0.dev6665

**scipy.linalg.lu(a, permute_l=False, overwrite_a=False) Compute pivoted LU decompostion of a matrix. The decomposition is:
**

A = P L U

where P is a permutation matrix, L lower triangular with unit diagonal elements, and U upper triangular. Parameters a : array, shape (M, N) Array to decompose permute_l : boolean Perform the multiplication P*L (Default: do not permute) overwrite_a : boolean Whether to overwrite data in a (may improve performance) Returns (If permute_l == False) : p : array, shape (M, M) Permutation matrix l : array, shape (M, K) Lower triangular or trapezoidal matrix with unit diagonal. K = min(M, N) u : array, shape (K, N) Upper triangular or trapezoidal matrix (If permute_l == True) : pl : array, shape (M, K) Permuted L matrix. K = min(M, N) u : array, shape (K, N) Upper triangular or trapezoidal matrix Notes This is a LU factorization routine written for Scipy. scipy.linalg.lu_factor(a, overwrite_a=False) Compute pivoted LU decomposition of a matrix. The decomposition is:

A = P L U

where P is a permutation matrix, L lower triangular with unit diagonal elements, and U upper triangular. Parameters a : array, shape (M, M) Matrix to decompose overwrite_a : boolean Whether to overwrite data in A (may increase performance)

3.7. Linear algebra (scipy.linalg)

281

SciPy Reference Guide, Release 0.10.0.dev6665

Returns lu : array, shape (N, N) Matrix containing U in its upper triangle, and L in its lower triangle. The unit diagonal elements of L are not stored. piv : array, shape (N,) Pivot indices representing the permutation matrix P: row i of matrix was interchanged with row piv[i]. See Also: lu_solve solve an equation system using the LU factorization of a matrix Notes This is a wrapper to the *GETRF routines from LAPACK. scipy.linalg.lu_solve((lu, piv), b, trans=0, overwrite_b=False) Solve an equation system, a x = b, given the LU factorization of a Parameters (lu, piv) : Factorization of the coefﬁcient matrix a, as given by lu_factor b : array Right-hand side trans : {0, 1, 2} Type of system to solve: trans 0 1 2 Returns x : array Solution to the system See Also: lu_factor LU factorize a matrix scipy.linalg.svd(a, full_matrices=True, compute_uv=True, overwrite_a=False) Singular Value Decomposition. Factorizes the matrix a into two unitary matrices U and Vh and an 1d-array s of singular values (real, nonnegative) such that a == U S Vh if S is an suitably shaped matrix of zeros whose main diagonal is s. Parameters a : array, shape (M, N) Matrix to decompose full_matrices : boolean system ax=b a^T x = b a^H x = b

282

Chapter 3. Reference

SciPy Reference Guide, Release 0.10.0.dev6665

If true, U, Vh are shaped (M,M), (N,N) If false, the shapes are (M,K), (K,N) where K = min(M,N) compute_uv : boolean Whether to compute also U, Vh in addition to s (Default: true) overwrite_a : boolean Whether data in a is overwritten (may improve performance) Returns U: array, shape (M,M) or (M,K) depending on full_matrices : s: array, shape (K,) : The singular values, sorted so that s[i] >= s[i+1]. K = min(M, N) Vh: array, shape (N,N) or (K,N) depending on full_matrices : For compute_uv = False, only s is returned. : Raises LinAlgError if SVD computation does not converge : See Also: svdvals return singular values of a matrix diagsvd return the Sigma matrix, given the vector s Examples

>>> from scipy import random, linalg, allclose, dot >>> a = random.randn(9, 6) + 1j*random.randn(9, 6) >>> U, s, Vh = linalg.svd(a) >>> U.shape, Vh.shape, s.shape ((9, 9), (6, 6), (6,)) >>> U, s, Vh = linalg.svd(a, full_matrices=False) >>> U.shape, Vh.shape, s.shape ((9, 6), (6, 6), (6,)) >>> S = linalg.diagsvd(s, 6, 6) >>> allclose(a, dot(U, dot(S, Vh))) True >>> s2 = linalg.svd(a, compute_uv=False) >>> allclose(s, s2) True

scipy.linalg.svdvals(a, overwrite_a=False) Compute singular values of a matrix. Parameters a : array, shape (M, N) Matrix to decompose overwrite_a : boolean Whether data in a is overwritten (may improve performance)

3.7. Linear algebra (scipy.linalg)

283

SciPy Reference Guide, Release 0.10.0.dev6665

Returns s: array, shape (K,) : The singular values, sorted so that s[i] >= s[i+1]. K = min(M, N) Raises LinAlgError if SVD computation does not converge : See Also: svd return the full singular value decomposition of a matrix diagsvd return the Sigma matrix, given the vector s scipy.linalg.diagsvd(s, M, N) Construct the sigma matrix in SVD from singular values and size M,N. Parameters s : array, shape (M,) or (N,) Singular values M : integer N : integer Size of the matrix whose singular values are s Returns S : array, shape (M, N) The S-matrix in the singular value decomposition scipy.linalg.orth(A) Construct an orthonormal basis for the range of A using SVD Parameters A : array, shape (M, N) Returns Q : array, shape (M, K) Orthonormal basis for the range of A. K = effective rank of A, as determined by automatic cutoff See Also: svd Singular value decomposition of a matrix scipy.linalg.cholesky(a, lower=False, overwrite_a=False) Compute the Cholesky decomposition of a matrix. Returns the Cholesky decomposition, :lm:‘A = L L^*‘ or :lm:‘A = U^* U‘ of a Hermitian positive-deﬁnite matrix :lm:‘A‘. Parameters a : array, shape (M, M) Matrix to be decomposed lower : boolean

284

Chapter 3. Reference

SciPy Reference Guide, Release 0.10.0.dev6665

Whether to compute the upper or lower triangular Cholesky factorization (Default: upper-triangular) overwrite_a : boolean Whether to overwrite data in a (may improve performance) Returns c : array, shape (M, M) Upper- or lower-triangular Cholesky factor of A Raises LinAlgError if decomposition fails : Examples

>>> from scipy import array, linalg, dot >>> a = array([[1,-2j],[2j,5]]) >>> L = linalg.cholesky(a, lower=True) >>> L array([[ 1.+0.j, 0.+0.j], [ 0.+2.j, 1.+0.j]]) >>> dot(L, L.T.conj()) array([[ 1.+0.j, 0.-2.j], [ 0.+2.j, 5.+0.j]])

scipy.linalg.cholesky_banded(ab, overwrite_ab=False, lower=False) Cholesky decompose a banded Hermitian positive-deﬁnite matrix The matrix a is stored in ab either in lower diagonal or upper diagonal ordered form: ab[u + i - j, j] == a[i,j] (if upper form; i <= j) ab[ i - j, j] == a[i,j] (if lower form; i >= j) Example of ab (shape of a is (6,6), u=2):

upper form: a02 a13 a24 a35 * * a01 a12 a23 a34 a45 * a00 a11 a22 a33 a44 a55 lower form: a00 a11 a22 a33 a44 a55 a10 a21 a32 a43 a54 * a20 a31 a42 a53 * *

Parameters ab : array, shape (u + 1, M) Banded matrix overwrite_ab : boolean Discard data in ab (may enhance performance) lower : boolean Is the matrix in the lower form. (Default is upper form) Returns c : array, shape (u+1, M) Cholesky factorization of a, in the same banded format as ab

3.7. Linear algebra (scipy.linalg)

285

SciPy Reference Guide, Release 0.10.0.dev6665

scipy.linalg.cho_factor(a, lower=False, overwrite_a=False) Compute the Cholesky decomposition of a matrix, to use in cho_solve Returns a matrix containing the Cholesky decomposition, A = L L* or A = U* U of a Hermitian positivedeﬁnite matrix a. The return value can be directly used as the ﬁrst parameter to cho_solve. Warning: The returned matrix also contains random data in the entries not used by the Cholesky decomposition. If you need to zero these entries, use the function cholesky instead. Parameters a : array, shape (M, M) Matrix to be decomposed lower : boolean Whether to compute the upper or lower triangular Cholesky factorization (Default: upper-triangular) overwrite_a : boolean Whether to overwrite data in a (may improve performance) Returns c : array, shape (M, M) Matrix whose upper or lower triangle contains the Cholesky factor of a. Other parts of the matrix contain random data. lower : boolean Flag indicating whether the factor is in the lower or upper triangle Raises LinAlgError : Raised if decomposition fails. See Also: cho_solve Solve a linear set equations using the Cholesky factorization of a matrix. scipy.linalg.cho_solve((c, lower), b, overwrite_b=False) Solve the linear equations A x = b, given the Cholesky factorization of A. Parameters (c, lower) : tuple, (array, bool) Cholesky factorization of a, as given by cho_factor b : array Right-hand side Returns x : array The solution to the system A x = b See Also: cho_factor Cholesky factorization of a matrix 286 Chapter 3. Reference

SciPy Reference Guide, Release 0.10.0.dev6665

scipy.linalg.cho_solve_banded((cb, lower), b, overwrite_b=False) Solve the linear equations A x = b, given the Cholesky factorization of A. Parameters (cb, lower) : tuple, (array, bool) cb is the Cholesky factorization of A, as given by cholesky_banded. lower must be the same value that was given to cholesky_banded. b : array Right-hand side overwrite_b : bool If True, the function will overwrite the values in b. Returns x : array The solution to the system A x = b See Also: cholesky_banded Cholesky factorization of a banded matrix Notes New in version 0.8.0. scipy.linalg.qr(a, overwrite_a=False, lwork=None, mode=’full’) Compute QR decomposition of a matrix. Calculate the decomposition :lm:‘A = Q R‘ where Q is unitary/orthogonal and R upper triangular. Parameters a : array, shape (M, N) Matrix to be decomposed overwrite_a : bool, optional Whether data in a is overwritten (may improve performance) lwork : int, optional Work array size, lwork >= a.shape[1]. If None or -1, an optimal size is computed. mode : {‘full’, ‘r’, ‘economic’} Determines what information is to be returned: either both Q and R (‘full’, default), only R (‘r’) or both Q and R but computed in economy-size (‘economic’, see Notes). Returns Q : double or complex ndarray Of shape (M, M), or (M, K) for mode=’economic’. Not returned if mode=’r’. R : double or complex ndarray Of shape (M, N), or (K, N) for mode=’economic’. K = min(M, N). Raises LinAlgError if decomposition fails :

3.7. Linear algebra (scipy.linalg)

287

SciPy Reference Guide, Release 0.10.0.dev6665

Notes This is an interface to the LAPACK routines dgeqrf, zgeqrf, dorgqr, and zungqr. If mode=economic, the shapes of Q and R are (M, K) and (K, N) instead of (M,M) and (M,N), with K=min(M,N). Examples

>>> from scipy import random, linalg, dot, allclose >>> a = random.randn(9, 6) >>> q, r = linalg.qr(a) >>> allclose(a, dot(q, r)) True >>> q.shape, r.shape ((9, 9), (9, 6)) >>> r2 = linalg.qr(a, mode=’r’) >>> allclose(r, r2) True >>> q3, r3 = linalg.qr(a, mode=’economic’) >>> q3.shape, r3.shape ((9, 6), (6, 6))

scipy.linalg.schur(a, output=’real’, lwork=None, overwrite_a=False) Compute Schur decomposition of a matrix. The Schur decomposition is A = Z T Z^H where Z is unitary and T is either upper-triangular, or for real Schur decomposition (output=’real’), quasi-upper triangular. In the quasi-triangular form, 2x2 blocks describing complex-valued eigenvalue pairs may extrude from the diagonal. Parameters a : array, shape (M, M) Matrix to decompose output : {‘real’, ‘complex’} Construct the real or complex Schur decomposition (for real matrices). lwork : integer Work array size. If None or -1, it is automatically computed. overwrite_a : boolean Whether to overwrite data in a (may improve performance) Returns T : array, shape (M, M) Schur form of A. It is real-valued for the real Schur decomposition. Z : array, shape (M, M) An unitary Schur transformation matrix for A. It is real-valued for the real Schur decomposition. See Also: rsf2csf Convert real Schur form to complex Schur form 288 Chapter 3. Reference

SciPy Reference Guide, Release 0.10.0.dev6665

scipy.linalg.rsf2csf(T, Z) Convert real Schur form to complex Schur form. Convert a quasi-diagonal real-valued Schur form to the upper triangular complex-valued Schur form. Parameters T : array, shape (M, M) Real Schur form of the original matrix Z : array, shape (M, M) Schur transformation matrix Returns T : array, shape (M, M) Complex Schur form of the original matrix Z : array, shape (M, M) Schur transformation matrix corresponding to the complex form See Also: schur Schur decompose a matrix scipy.linalg.hessenberg(a, calc_q=False, overwrite_a=False) Compute Hessenberg form of a matrix. The Hessenberg decomposition is A = Q H Q^H where Q is unitary/orthogonal and H has only zero elements below the ﬁrst subdiagonal. Parameters a : array, shape (M,M) Matrix to bring into Hessenberg form calc_q : boolean Whether to compute the transformation matrix overwrite_a : boolean Whether to ovewrite data in a (may improve performance) Returns H : array, shape (M,M) Hessenberg form of A (If calc_q == True) : Q : array, shape (M,M) Unitary/orthogonal similarity transformation matrix s.t. A = Q H Q^H

3.7. Linear algebra (scipy.linalg)

289

SciPy Reference Guide, Release 0.10.0.dev6665

3.7.4 Matrix Functions

expm(A[, q]) expm2(A) expm3(A[, q]) logm(A[, disp]) cosm(A) sinm(A) tanm(A) coshm(A) sinhm(A) tanhm(A) signm(a[, disp]) sqrtm(A[, disp]) funm(A, func[, disp]) Compute the matrix exponential using Pade approximation. Compute the matrix exponential using eigenvalue decomposition. Compute the matrix exponential using Taylor series. Compute matrix logarithm. Compute the matrix cosine. Compute the matrix sine. Compute the matrix tangent. Compute the hyperbolic matrix cosine. Compute the hyperbolic matrix sine. Compute the hyperbolic matrix tangent. Matrix sign function. Matrix square root. Evaluate a matrix function speciﬁed by a callable.

scipy.linalg.expm(A, q=7) Compute the matrix exponential using Pade approximation. Parameters A : array, shape(M,M) Matrix to be exponentiated q : integer Order of the Pade approximation Returns expA : array, shape(M,M) Matrix exponential of A scipy.linalg.expm2(A) Compute the matrix exponential using eigenvalue decomposition. Parameters A : array, shape(M,M) Matrix to be exponentiated Returns expA : array, shape(M,M) Matrix exponential of A scipy.linalg.expm3(A, q=20) Compute the matrix exponential using Taylor series. Parameters A : array, shape(M,M) Matrix to be exponentiated q : integer Order of the Taylor series Returns expA : array, shape(M,M) Matrix exponential of A

290

Chapter 3. Reference

SciPy Reference Guide, Release 0.10.0.dev6665

scipy.linalg.logm(A, disp=True) Compute matrix logarithm. The matrix logarithm is the inverse of expm: expm(logm(A)) == A Parameters A : array, shape(M,M) Matrix whose logarithm to evaluate disp : boolean Print warning if error in the result is estimated large instead of returning estimated error. (Default: True) Returns logA : array, shape(M,M) Matrix logarithm of A (if disp == False) : errest : ﬂoat 1-norm of the estimated error, ||err||_1 / ||A||_1 scipy.linalg.cosm(A) Compute the matrix cosine. This routine uses expm to compute the matrix exponentials. Parameters A : array, shape(M,M) Returns cosA : array, shape(M,M) Matrix cosine of A scipy.linalg.sinm(A) Compute the matrix sine. This routine uses expm to compute the matrix exponentials. Parameters A : array, shape(M,M) Returns sinA : array, shape(M,M) Matrix cosine of A scipy.linalg.tanm(A) Compute the matrix tangent. This routine uses expm to compute the matrix exponentials. Parameters A : array, shape(M,M) Returns tanA : array, shape(M,M) Matrix tangent of A

3.7. Linear algebra (scipy.linalg)

291

SciPy Reference Guide, Release 0.10.0.dev6665

scipy.linalg.coshm(A) Compute the hyperbolic matrix cosine. This routine uses expm to compute the matrix exponentials. Parameters A : array, shape(M,M) Returns coshA : array, shape(M,M) Hyperbolic matrix cosine of A scipy.linalg.sinhm(A) Compute the hyperbolic matrix sine. This routine uses expm to compute the matrix exponentials. Parameters A : array, shape(M,M) Returns sinhA : array, shape(M,M) Hyperbolic matrix sine of A scipy.linalg.tanhm(A) Compute the hyperbolic matrix tangent. This routine uses expm to compute the matrix exponentials. Parameters A : array, shape(M,M) Returns tanhA : array, shape(M,M) Hyperbolic matrix tangent of A scipy.linalg.signm(a, disp=True) Matrix sign function. Extension of the scalar sign(x) to matrices. Parameters A : array, shape(M,M) Matrix at which to evaluate the sign function disp : boolean Print warning if error in the result is estimated large instead of returning estimated error. (Default: True) Returns sgnA : array, shape(M,M) Value of the sign function at A (if disp == False) : errest : ﬂoat 1-norm of the estimated error, ||err||_1 / ||A||_1

292

Chapter 3. Reference

SciPy Reference Guide, Release 0.10.0.dev6665

Examples

>>> from scipy.linalg import signm, eigvals >>> a = [[1,2,3], [1,2,1], [1,1,1]] >>> eigvals(a) array([ 4.12488542+0.j, -0.76155718+0.j, 0.63667176+0.j]) >>> eigvals(signm(a)) array([-1.+0.j, 1.+0.j, 1.+0.j])

scipy.linalg.sqrtm(A, disp=True) Matrix square root. Parameters A : array, shape(M,M) Matrix whose square root to evaluate disp : boolean Print warning if error in the result is estimated large instead of returning estimated error. (Default: True) Returns sgnA : array, shape(M,M) Value of the sign function at A (if disp == False) : errest : ﬂoat Frobenius norm of the estimated error, ||err||_F / ||A||_F Notes Uses algorithm by Nicholas J. Higham scipy.linalg.funm(A, func, disp=True) Evaluate a matrix function speciﬁed by a callable. Returns the value of matrix-valued function f at A. The function f is an extension of the scalar-valued function func to matrices. Parameters A : array, shape(M,M) Matrix at which to evaluate the function func : callable Callable object that evaluates a scalar function f. Must be vectorized (eg. using vectorize). disp : boolean Print warning if error in the result is estimated large instead of returning estimated error. (Default: True) Returns fA : array, shape(M,M) Value of the matrix function speciﬁed by func evaluated at A (if disp == False) : errest : ﬂoat

3.7. Linear algebra (scipy.linalg)

293

SciPy Reference Guide, Release 0.10.0.dev6665

1-norm of the estimated error, ||err||_1 / ||A||_1

3.7.5 Special Matrices

block_diag(*arrs) circulant(c) companion(a) hadamard(n[, dtype]) hankel(c[, r]) kron(a, b) leslie(f, s) toeplitz(c[, r]) tri(N[, M, k, dtype]) tril(m[, k]) triu(m[, k]) Create a block diagonal matrix from provided arrays. Construct a circulant matrix. Create a companion matrix. Construct a Hadamard matrix. Construct a Hankel matrix. Kronecker product of a and b. Create a Leslie matrix. Construct a Toeplitz matrix. Construct (N, M) matrix ﬁlled with ones at and below the k-th diagonal. Construct a copy of a matrix with elements above the k-th diagonal zeroed. Construct a copy of a matrix with elements below the k-th diagonal zeroed.

scipy.linalg.block_diag(*arrs) Create a block diagonal matrix from provided arrays. Given the inputs A, B and C, the output will have these arrays arranged on the diagonal:

[[A, 0, 0], [0, B, 0], [0, 0, C]]

Parameters A, B, C, ... : array_like, up to 2-D Input arrays. A 1-D array or array_like sequence of length n‘is treated as a 2-D array with shape ‘‘(1,n)‘. Returns D : ndarray Array with A, B, C, ... on the diagonal. D has the same dtype as A. Notes If all the input arrays are square, the output is known as a block diagonal matrix. Examples

>>> A = [[1, 0], ... [0, 1]] >>> B = [[3, 4, 5], ... [6, 7, 8]] >>> C = [[7]] >>> block_diag(A, B, C) [[1 0 0 0 0 0] [0 1 0 0 0 0] [0 0 3 4 5 0] [0 0 6 7 8 0] [0 0 0 0 0 7]] >>> block_diag(1.0, [2, array([[ 1., 0., 0., [ 0., 2., 3., [ 0., 0., 0., [ 0., 0., 0.,

3], [[4, 5], [6, 7]]) 0., 0.], 0., 0.], 4., 5.], 6., 7.]])

294

Chapter 3. Reference

and a[0] must not be zero. n-1). [2. Create the companion matrix [R29] associated with the polynomial whose coefﬁcients are given in a. Linear algebra (scipy.0*a[0]. len(c)) A circulant matrix whose ﬁrst column is c. Returns A : array.0. b) a. See Also: toeplitz Toeplitz matrix hankel Hankel matrix Notes New in version 0. 3].0.companion(a) Create a companion matrix. Notes New in version 0. Raises ValueError : If any of the following are true: a) a. 2].circulant(c) Construct a circulant matrix.dev6665 scipy.8. 2. where n is the length of a.linalg) 295 . shape (len(c).0. c) a[0] == 0.7. 3. 1]]) scipy. Parameters a : array_like 1-D array of polynomial coefﬁcients. The ﬁrst row of c is -a[1:]/a[0]. Parameters c : array_like 1-D array. Examples >>> from scipy. 3]) array([[1. and the ﬁrst sub-diagonal is all ones. 1. 3. [3.linalg.SciPy Reference Guide. Release 0. The data-type of the array is the same as the data-type of 1.10.size < 2.linalg.8. The length of a must be at least two.linalg import circulant >>> circulant([1. the ﬁrst column of the matrix.ndim != 1. 2. Returns c : ndarray A square array of shape (n-1.

-1. 1. Reference . 296 Chapter 3. Notes New in version 0. Parameters n : int The order of the matrix.hadamard(n... using Sylvester’s construction.linalg. Returns H : ndarray with shape (n. Whatever the actual shape of c. Parameters c : array_like First column of the matrix. 30. r[0] is ignored. r[1:]].0.+0. -1. -1.. -1]. n must be a power of 2.. 1.+0.hankel(c. -1.]. -1. r = zeros_like(c) is assumed. -31. [ 0.j. [ 1. -10. Release 0.0. 1]]) scipy. [ 1. n must be a power of 2.j. dtype=complex) array([[ 1. 1. r=None) Construct a Hankel matrix.8. 1. [ 1. 0.dev6665 References [R29] Examples >>> from scipy.SciPy Reference Guide. The Hankel matrix has constant anti-diagonals. [ 1. If r is not given. 1. with c as its ﬁrst column and r as its last row. [ 1. then r = zeros_like(c) is assumed. -30]) array([[ 10. dtype : numpy dtype The data type of the array to be constructed. 1. it will be converted to a 1-D array.j]]) >>> hadamard(4) array([[ 1. n) The Hadamard matrix. it will be converted to a 1-D array. r : array_like.linalg import companion >>> companion([1. Whatever the actual shape of r. 31.]. 0.linalg. 1D Last row of the matrix.-0.. dtype=<type ‘int’>) Construct a Hadamard matrix.10. the last row of the returned matrix is [c[-1]..+0.j]. hadamard(n) constructs an n-by-n Hadamard matrix. 1]. 0. -1].]]) scipy. If None. Examples >>> hadamard(2.

0]. [4. N) b : array. 7. a[-1.kron(a.dev6665 Returns A : array. [4.1]])) array([[1. 99]) array([[ 1. Q) Returns A : array. 4]]) scipy. len(r)) The Hankel matrix. N*Q) Kronecker product of a and b Examples >>> from scipy import kron.3. Given the length n array of fecundity coefﬁcients f and the length n-1 array of survival coefﬁcents s. Dtype is the same as (c[0] + r[0]). 2. 3.4]. 4. 7.0]*b a[1.0]*b .. 2. shape (P.. 1.. 0]]) >>> hankel([1. 17.dtype.SciPy Reference Guide. a[1. 7].linalg import hankel >>> hankel([1. array([[1. b) Kronecker product of a and b. 7]. a[0. 9]]) scipy. Linear algebra (scipy. 4. The result is the block matrix: a[0.0. [3. 3. 4.4]]).9]) array([[1..1]*b .7. 99]. 2. 2]. 7..linalg) 297 .0]*b a[0.leslie(f..linalg.1.-1]*b . 8.2.8. 4.[3. return the associated Leslie matrix. [99. [2. a[-1.7.2].10. 7. shape (M*P. shape (len(c).-1]*b Parameters a : array.1]*b .. See Also: toeplitz Toeplitz matrix circulant circulant matrix Examples >>> from scipy. 99. Parameters f : array_like 3.. [3. shape (M. 8].-1]*b a[-1. array >>> kron(array([[1. [17. 7.linalg. s) Create a Leslie matrix. 3. 1. 4.1]*b a[1. 17. Release 0.7. 0. 3.

The length of s must be one less than the length of f. Dtype is the same as (c[0] + r[0]). and the ﬁrst sub-diagonal. 0. and the n . 0. Whatever the actual shape of r. 1. r[0] is ignored. 1. Whatever the actual shape of c. 0. 0.10.2. if c[0] is real. with c as its ﬁrst column and r as its ﬁrst row. ]. [ 0.dev6665 The “fecundity” coefﬁcients. 0.linalg. r == conjugate(c) is assumed.1]. which give the per-capita survival rate of each age class. .0. Parameters c : array_like First column of the matrix.7. Returns A : array. See Also: circulant circulant matrix 298 Chapter 3. r : array_like First row of the matrix. the ﬁrst row of the returned matrix is [c[0]. .1. where n is the length of f. The Toeplitz matrix has constant diagonals. ]. 0. 0. age-structured population growth [R30] [R31].1 “survival coefﬁcients”. [ 0. len(r)) The Toeplitz matrix.7]) 0.0. two sets of parameters deﬁne a Leslie matrix: the n “fecundity coefﬁcients”. r = conjugate(c) is assumed. shape (len(c).8. 2.1]. array([[ 0. .1. [ 0. 0. it will be converted to a 1-D array.toeplitz(c. in this case.SciPy Reference Guide. s : array_like The “survival” coefﬁcients. References [R30].8. 0. . n). .8. In a population with n age classes. 0. If None. and it must be at least 1. [R31] Examples >>> leslie([0. which is s. the result is a Hermitian matrix. which is f. Reference . ]]) scipy. 2.0. If r is not given. The array is zero except for the ﬁrst row. . r[1:]]. has to be 1-D. Returns L : ndarray Returns a 2-D ndarray of shape (n.dtype. 0. 0. The Leslie matrix is used to model discrete-time.2. [0.0. it will be converted to a 1-D array. The data-type of the array will be the data-type of f[0]+s[0]. r=None) Construct a Toeplitz matrix. has to be 1-D. Release 0. Notes New in version 0. . which give the number of offspring per-capita produced by each age class. .

1. 6].tri(N. [1. [ 2.+1.0. k = 0 is the main diagonal. 1. M=None. 4. 5. k < 0 subdiagonal and k > 0 superdiagonal. If M is None.linalg. 4.0.dev6665 hankel Hankel matrix Notes The behavior when c or r is a scalar. 4]]) >>> toeplitz([1.4.tril(m.j.6]) array([[1. 4. 0.-3. The behavior in previous versions was undocumented and is no longer supported. 0]. M) matrix ﬁlled with ones at and below the k-th diagonal. Linear algebra (scipy. 1. 1. or when c is complex and r is None. 0.j. 1.+3.j.linalg. 0.+0.j. k=0) Construct a copy of a matrix with elements above the k-th diagonal zeroed. 2+3j. M) Examples >>> from scipy. 0. Returns A : array. dtype : dtype Data type of the matrix. M = N is assumed. 2. 5. k : integer Number of subdiagonal below which matrix is ﬁlled with ones. 1.8.0.+0. 4-1j]) array([[ 1.SciPy Reference Guide. The matrix has A[i. dtype=None) Construct (N. k=0. 2. Release 0.5.j. 0.linalg) 299 . 1.j]. [1. 5. 0].j] == 1 for i <= j + k Parameters N : integer The size of the ﬁrst dimension of the matrix.linalg import tri >>> tri(3. -1.-1. 0]. [3.10.7. 0. [1. [ 4. 1.+3. 2.2. 0. 0]]) scipy. 1]]) >>> tri(3. dtype=int) array([[1.linalg import toeplitz >>> toeplitz([1. 5].3].j]]) scipy. 1.j]. [1. was changed in version 0. 1.-3.j. dtype=int) array([[0. 2. 1. shape (N. 2. 0. 1. Parameters m : array 3.+0. M : integer or None The size of the second dimension of the matrix. 0. [1. 1. Examples >>> from scipy. 0]. [2.

triu(m.0. 5.dtype Examples >>> from scipy.11.dev6665 Matrix whose elements to return k : integer Diagonal above which to zero elements. Reference . 12]]) scipy. “model”.12]]. -1) array([[ 0. k < 0 subdiagonal and k > 0 superdiagonal.3]. 0].8. dtype m. 0.linalg import tril >>> triu([[1. using explicit summation.8. 0. conditional Monte Carlo methods. [ 0.shape.8 Maximum entropy models (scipy. 6]. The other. and uses importance sampling.2.3]. dtype m. shape m.[4.2. [ 0. k == 0 is the main diagonal. Returns A : array. 300 Chapter 3. [ 4. is for sample spaces that are either continuous (and perhaps high-dimensional) or discrete but too large to sum over.maxentropy) 3.6]. [ 4. 2.SciPy Reference Guide.[4. 12]]) 3.dtype Examples >>> from scipy. [10. Release 0.[10.shape. 0. Returns A : array. k=0) Construct a copy of a matrix with elements below the k-th diagonal zeroed.8.[10.11.10. Parameters m : array Matrix whose elements to return k : integer Diagonal below which to zero elements.linalg.6]. “bigmodel”. shape m. 9]. [ 7.1 Routines for ﬁtting maximum entropy models Contains two classes for ﬁtting maximum entropy models (also known as “exponential family” models) subject to linear constraints on the expectations of arbitrary feature statistics. One class.[7. -1) array([[ 1. k == 0 is the main diagonal.9]. 0].9]. is for small discrete sample spaces. 8.5. 3].linalg import tril >>> tril([[1. 0].12]].5. k < 0 subdiagonal and k > 0 superdiagonal. 11. 8.[7.

SciPy Reference Guide. order]) columnmeans(A) This is a wrapper for general dense or sparse dot products.8. Cover and Thomas (1991). Copyright: Ed Schoﬁeld.e^{a_n}) norm(a[.. dtype. asarray(a[.py for a walk-through of how to use these routines when the sample space is small enough to be enumerated. Perhaps the logsumexp() function belongs under the utils/ branch where other modules can access it more easily. Returns an (m x n) sparse matrix of non-zero evaluations of the scalar or vector sample[. and PySparse matrices a common interface. columnvariances(A) This is a wrapper for general dense or sparse dot products.. samplespace]) A base class providing generic functionality for both small and large maximum entropy models.. Maximum entropy models (scipy. A maximum-entropy (exponential-form) model on a large sample space. Copyright: Ed Schoﬁeld.10. Most of them are either Python replacements for the corresponding Fortran routines or wrappers around matrices to allow the maxent module to manipulate ndarrays. format]) functions f_1. See bergerexamplesimulated.. sparsefeaturematrix(f. counts.x_n in the sequence ‘sample’. is a wrapper around general dense or sparse dot products. innerprodtranspose(A. 2003-2006 License: BSD-style (see LICENSE. Release 0. ord]) Matrix or vector norm. for example. 2003-2006 License: BSD-style (see LICENSE. see.maxentropy) 301 .. A maximum-entropy (exponential-form) model on a discrete sample space. numcontexts) model([f.txt in main source directory) Modules maxentropy maxentutils Functions arrayexp(x) Returns the elementwise antilog of the real array x.. v) This is a wrapper around general dense or sparse dot products. Utility routines for the maximum entropy module. This v) logsumexp(a) Compute the log of the sum of exponentials log(e^{a_1}+. scipy sparse matrices.dev6665 The maximum entropy model has exponential form p (x) = exp θT f (x) Z (θ) with a real parameter vector theta of the same length as the feature statistic f(x).f_m in the list f at the points x_1.py for a a similar walk-through using simulation. Elements of Information Theory. For more background. See the ﬁle bergerexample. flatten(a) Flattens the sparse matrix or dense array/matrix ‘a’ into a innerprod(A.txt in main source directory) 3. Convert the input to an array.. A conditional maximum-entropy (exponential-form) model p(x|w) on a discrete sample space.0.. Utility routines for the maximum entropy module. Exceptions DivergenceError(message) Exception raised if the entropy dual has no ﬁnite minimum.. Classes basemodel() bigmodel() conditionalmodel(F..

A base class providing generic functionality for both small and large maximum entropy models.dev6665 Functions arrayexp(x) Returns the elementwise antilog of the real array x. This v) logsumexp(a) Compute the log of the sum of exponentials log(e^{a_1}+. exception scipy. densefeaturematrix(f.. For robustlog(x) Returns log(x) if x > 0.log(x) if x < 0.f_m in the list f at the points x_1.SciPy Reference Guide.0. Reference . v) This is a wrapper around general dense or sparse dot products. sample_wr(population. format]) Classes ndarray Exceptions DivergenceError(message) Classes DivergenceError(message) basemodel() bigmodel() conditionalmodel(F. numcontexts) model([f. rowmeans(A) This is a wrapper for general dense or sparse dot products. counts. Returns an (m x n) sparse matrix of non-zero evaluations of the scalar or vector sample[.maxentropy. dtype. is a wrapper around general dense or sparse dot products. empty(shape[.. innerprodtranspose(A. x) Returns a dense array of non-zero evaluations of the functions ﬁ dotprod(u.. order]) flatten(a) Flattens the sparse matrix or dense array/matrix ‘a’ into a innerprod(A. A maximum-entropy (exponential-form) model on a large sample space. order]) columnmeans(A) This is a wrapper for general dense or sparse dot products..basemodel A base class providing generic functionality for both small and large maximum entropy models. An array object represents a multidimensional. Exception raised if the entropy dual has no ﬁnite minimum. Convert the input to an array.10. k) sparsefeaturematrix(f. Returns an Mx1 sparse matrix of non-zero evaluations of the x[. Chooses k random elements (with replacement) from a population. homogeneous array of ﬁxed-size items.. columnvariances(A) This is a wrapper for general dense or sparse dot products. A conditional maximum-entropy (exponential-form) model p(x|w) on a discrete sample space.Returns an (m x n) dense array of non-zero evaluations of the sample) densefeatures(f. without initializing entries.maxentropy... samplespace]) Exception raised if the entropy dual has no ﬁnite minimum.. the complex log cmath. sparsefeatures(f. v) This is a wrapper around general dense or sparse dot products. asarray(a[.. dtype.DivergenceError(message) Exception raised if the entropy dual has no ﬁnite minimum.e^{a_n}) logsumexp_naive(values) testing logsumexp(). Release 0.x_n in the sequence ‘sample’. format]) functions f_1.. Return a new array of given shape and type. Cannot be instantiated. arrayexpcomplex(x) Returns the elementwise antilog of the vector x. A maximum-entropy (exponential-form) model on a discrete sample space. 302 Chapter 3. class scipy.

10. The model expectations are not computed exactly (by summing or integrating over a sample space) but approximately (by Monte Carlo estimation). Approximating the expectations by sampling requires an instrumental distribution that should be close to the model for fast convergence.SciPy Reference Guide.dev6665 Methods beginlogging clearcache crossentropy dual endlogging entropydual fit grad log logparams normconst reset setcallback setparams setsmooth class scipy. Maximum entropy models (scipy.8. The tails should be fatter than the model.0.maxentropy. like a continuous sample space in more than about 4 dimensions or a large discrete space like all possible sentences in a natural language.maxentropy) 303 . Release 0.bigmodel A maximum-entropy (exponential-form) model on a large sample space. Approximation is necessary when the sample space is too large to sum or integrate over in practice. 3.

what is the probability of each class x? The form of such a model is: p(x | w) = exp(theta .dev6665 Methods beginlogging clearcache crossentropy dual endlogging entropydual estimate expectations fit grad log lognormconst logparams logpdf normconst pdf pdf_function resample reset setcallback setparams setsampleFgen setsmooth settestsamples stochapprox test([label.conditionalmodel(F.0. f(w. verbose. . The sum is over all classes x in the set Y. which must be supplied to the constructor as the parameter ‘samplespace’. x)). theta) is a normalization term equal to: Z(w.10. class scipy.. This method minimizes the Lagrangian dual L of the entropy. This is useful for classiﬁcation problems: given the context w. counts. x)) / Z(w. f(w. extra_argv. numcontexts) A conditional maximum-entropy (exponential-form) model p(x|w) on a discrete sample space. Release 0. X) where the expectation is with respect to the distribution: q(w) p(x | w) where q(w) is the empirical probability mass function derived from observations of the context w in a training set. Reference . theta) where Z(w. Such a model form arises from maximizing the entropy of a conditional model p(x | w) subject to the constraints: K_i = E f_i(W. theta) = sum_x exp(theta . Normally the vector K = {K_i} of expectations is set equal to the expectation of f_i(w.]) Run tests for module using nose. which is deﬁned for conditional models as: 304 Chapter 3. doctests. x) with respect to the empirical distribution.SciPy Reference Guide.maxentropy..

Y) where the expectation is as deﬁned above.x)] Note that both sums are only over the training set {w.x not in the training set. The partial derivatives of L are: dL / dtheta_i = K_i .E f_i(X.dev6665 L(theta) = sum_w q(w) log Z(w. not the entire sample space.10. since q(w.8.0. Methods beginlogging clearcache crossentropy dual endlogging entropydual expectations fit grad log lognormconst logparams logpmf normconst pmf pmf_function probdist reset setcallback setfeaturesandsamplespace setparams setsmooth class scipy.x} q(w.model(f=None. theta) . samplespace=None) A maximum-entropy (exponential-form) model on a discrete sample space. 3.x) = 0 for all w.x) [theta . Release 0.sum_{w. f(w.maxentropy. Maximum entropy models (scipy.maxentropy) 305 .x}.SciPy Reference Guide.

... innerprodtranspose(A.exp() and. v) This is a wrapper around general dense or sparse dot products.x_n in the sequence ‘sample’. exp(-800).. We try to exponentiate with numpy..exp() is about 10 times faster but throws an OverﬂowError exception for numerical underﬂow (e.g. Release 0.0.SciPy Reference Guide. whereas python’s math.exp(). format]) functions f_1. columnvariances(A) This is a wrapper for general dense or sparse dot products. densefeaturematrix densefeatures dotprod flatten(a) Flattens the sparse matrix or dense array/matrix ‘a’ into a innerprod(A. with python’s math. sparsefeatures scipy..arrayexp(x) Returns the elementwise antilog of the real array x..maxentropy.. 306 Chapter 3. arrayexpcomplex columnmeans(A) This is a wrapper for general dense or sparse dot products. is a wrapper around general dense or sparse dot products..dev6665 Methods beginlogging clearcache crossentropy dual endlogging entropydual expectations fit grad log lognormconst logparams logpmf normconst pmf pmf_function probdist reset setcallback setfeaturesandsamplespace setparams setsmooth Functions arrayexp(x) Returns the elementwise antilog of the real array x. This v) logsumexp(a) Compute the log of the sum of exponentials log(e^{a_1}+. numpy.10.f_m in the list f at the points x_1.e^{a_n}) logsumexp_naive robustlog rowmeans sample_wr sparsefeaturematrix(f. if that fails..exp() just returns zero. Reference . which is much more helpful. Returns an (m x n) sparse matrix of non-zero evaluations of the scalar or vector sample[.

.1). scipy spmatrix.array([[1. Returns a dense (1 x n) vector with the column averages of A.maxentropy. This is a wrapper for A.maxentropy.flatten(a) Flattens the sparse matrix or dense array/matrix ‘a’ into a 1-dimensional array scipy.4]]. This is a wrapper for u.dot(v) for dense arrays and spmatrix objects.maxentropy. which can be an (m x n) sparse or dense matrix..]) scipy. A trimmed-down version. [3.]) scipy. It is not necessary except as a common interface for supporting ndarray. avoiding numerical overﬂow.) >>> a = numpy.array([[1.logsumexp(a) Compute the log of the sum of exponentials log(e^{a_1}+.sparsefeaturematrix(f. result) for pysparse matrices.maxentropy. It is not necessary except as a common interface for supporting ndarray.. This function is efﬁcient for large matrices A. If A is sparse. sample. scipy spmatrix. 3. Maximum entropy models (scipy.x_n in the sequence ‘sample’. (The normalization is by (m . not a matrix. If format=’ll_mat’.. Computes A^T V.maxentropy. Returns the inner product of the (m x n) dense or sparse matrix A with the n-element dense array v. v) This is a wrapper around general dense or sparse dot products..[3.innerprod(A.dot(v) for dense arrays and spmatrix objects.. result) for PySparse matrices.2].f_m in the list f at the points x_1. patched for NumPy compatibility. >>> a = numpy. Objects division scipy.maxentropy. scipy.maxentropy) 307 .columnmeans(A) This is a wrapper for general dense or sparse dot products.maxentropy. and PySparse arrays. v) This is a wrapper around general dense or sparse dot products.. It is only necessary as a common interface for supporting ndarray.e^{a_n}) of the components of the array a..SciPy Reference Guide.dev6665 scipy. scipy spmatrix. Returns a dense (1 x n) vector with unbiased estimators for the column variances for each column of the (m x n) sparse or dense matrix A. is available in the SciPy sandbox/pysparse directory. and for u.division 3.’d’) >>> columnmeans(a) array([ 2.0. format=’csc_matrix’) Returns an (m x n) sparse matrix of non-zero evaluations of the scalar or vector functions f_1. the PySparse module (or a symlink to it) must be available in the Python site-packages/ directory.. scipy.8. 2.. V must be a rank-1 array. ’d’) >>> columnvariances(a) array([ 2. and PySparse arrays. Release 0.matvec(v. and for A.innerprodtranspose(A.. scipy. It is not necessary except as a common interface for supporting ndarray.10.2].T.matvec_transp(v. and PySparse arrays.columnvariances(A) This is a wrapper for general dense or sparse dot products.4]]. scipy spmatrix. and PySparse arrays.maxentropy. where A is a dense or sparse matrix and V is a numpy array..

replacing the existing parameters. basemodel.freq. basemodel. basemodel. logging params for each fn evaluation to ﬁles named Enable freq]) ‘ﬁlename. for the current model.0.grad([params. . basemodel.params to zero.endlogging() Stop logging param values whenever setparams() is called.clearcache() Clears the interim results of computations depending on the basemodel.pickle’. Fit the maxent model p whose feature expectations are given algorithm]) basemodel.pickle’.log(params) This method is called every iteration during the optimization process.. p) of the empirical log_prior_x.endlogging() Stop logging param values whenever setparams() is called.freq.2 Models class scipy. Returns the cross entropy H(q.dev6665 3.fit(K[..beginlogging(ﬁlename. Release 0. .pickle’. each ‘freq’ iterations.setcallback([callback.]) evaluation. ‘ﬁlename. basemodel.clearcache() 308 Chapter 3.basemodel A base class providing generic functionality for both small and large maximum entropy models.]) basemodel.logparams() Saves the model parameters if logging has been basemodel.dual([params.setparams(params)Set the parameter vector to params. basemodel. Computes or estimates the gradient of the entropy dual. basemodel..crossentropy(fx[.maxentropy.beginlogging(ﬁlename[.10. or every gradient evaluation.normconst() Returns the normalization constant. Methods beginlogging clearcache crossentropy dual endlogging entropydual fit grad log logparams normconst reset setcallback setparams setsmooth basemodel.8. clearing the cache variables dependent on them. Reference .(2*freq). Computes the Lagrangian dual L(theta) of the entropy of the ignorepenalty..reset([numfeatures]) Resets the parameters self.(2*freq). . basemodel. base]) basemodel. freq=10) Enable logging params for each fn evaluation to ﬁles named ‘ﬁlename. or partition function.pickle’. basemodel. ignorepenalty]) basemodel.. Cannot be instantiated.. every function Sets . callback functions to be called every iteration. basemodel..SciPy Reference Guide. ‘ﬁlename.setsmooth(sigma) Speciﬁes that the entropy dual and gradient should be computed with a quadratic penalty term on magnitude of the parameters..

‘LBFGSB’. the dual estimate is deterministic for any given sample. use the ‘bigmodel’ class instead. expectations are computed exactly. ignoretest=False) Computes the Lagrangian dual L(theta) of the entropy of the model. For ‘bigmodel’ instances. j=1.K for the expectations of the feature statistic. ‘Powell’. This is important if the sample space is continuous or innumerable in practice.. The tails should be fatter than the model.maxentropy) 309 . Maximum entropy models (scipy. the model expectations are not computed exactly (by summing or integrating over a sample space) but approximately (by Monte Carlo simulation). The ‘base’ argument speciﬁes the base of the logarithm. Simulation is necessary when the sample space is too large to sum or integrate over in practice. ‘BFGS’. Approximating the expectations by sampling requires an instrumental distribution that should be close to the model for fast convergence. which defaults to e. depending on the ‘func’ and ‘grad’ parameters passed to this function.0. and K_i = the empirical expectation E_p_tilde f_i (X) = sum_x {p(x) f_i(x)}. Minimizing this function (without constraints) should ﬁt the maximum entropy model subject to the given constraints.10. base=2. for the given vector theta=params.crossentropy(fx. Release 0. This estimator is deterministic for any given sample. Note that. ignorepenalty=False.. justifying the use of this estimator in conjunction with grad() in optimization methods that use both the function and gradient.SciPy Reference Guide. It is given as: L_est = log Z_est . We approximate the norm constant Z using importance sampling as in [Rosenfeld01whole]. p) of the empirical distribution q of the data (with the given feature matrix fx) with respect to the model p.n. This function is computed as: L(theta) = log(Z) . that convergence guarantees break down for most optimization algorithms in the presence of stochastic error. log_prior_x=None.sum_i{theta_i K_i} where Z_est = 1/m sum_{x in sample S_0} p_dot(x) / aux_dist(x). The algorithm can be ‘CG’. or ‘Nelder-Mead’. For ‘model’ instances.n^{-1} sum_{j=1}^n log p(x_j) where x_j are the data elements assumed drawn from q whose features are given by the matrix fx = {f(x_j)}. For discrete distributions this is deﬁned as: H(q. it estimates the entropy dual without actually computing p_theta. by summing over the given sample space. Note that the gradient of this estimator is equal to the importance sampling ratio estimator of the gradient of the entropy dual [see my thesis]. p) = . For continuous distributions this makes no sense! basemodel. This instrumental distribution is speciﬁed by calling setsampleFgen() with a user-supplied generator function that yields a matrix of features of a random sample and its log pdf values.7182818284590451) Returns the cross entropy H(q. basemodel. Note. however. and m = # observations in sample S_0. for ‘bigmodel’ objects. algorithm=’CG’) Fit the maxent model p whose feature expectations are given by the vector K.fit(K. 3. basemodel. Model expectations are computed either exactly or using Monte Carlo simulation. If the sample space is continuous or too large to iterate over. K For ‘bigmodel’ objects..dual(params=None.8.. like a continuous sample space in more than about 4 dimensions or a large discrete space like all possible sentences in a natural language.dev6665 Clears the interim results of computations depending on the parameters and the sample.theta^T . These constraints are speciﬁed as the desired (target) values self.

Also resets the number of function and gradient evaluations to zero.maxentropy. ‘A Gaussian prior for smoothing maximum entropy models’ (1999). for the current model. For ‘bigmodel’ instances. Release 0. 310 Chapter 3.setcallback(callback=None. like Newton-based methods). clearing the cache variables dependent on them. estimates the normalization term as Z = E_aux_dist [{exp (params. some of which we expect to be poor.f(X))} / aux_dist(X)] using a sample from aux_dist. basemodel.sigma2. for bigmodel instances. This ‘smooths’ the model to account for noise in the target expectation values or to improve robustness when using simulation to ﬁt models and when the sampling distribution has high variance. logs the evolution of the entropy dual and gradient norm. For small models it is slow but robust. All callback functions are passed one argument.log(params) This method is called every iteration during the optimization process. basemodel. callback_dual=None. basemodel. The Powell algorithm doesn’t require gradients.0. The smoothing mechanism is described in Chen and Rosenfeld. params must be a list or numpy array of the same length as the model’s feature vector f.dev6665 The CG (conjugate gradients) method is the default. the current model object.paramslogfreq. Warning – this may be too large to represent. every function evaluation. It is perhaps faster than the CG method but requires O(N^2) instead of O(N) memory. basemodel. Note that line search algorithms in e. basemodel. The BFGS (Broyden-Fletcher-Goldfarb-Shanno) algorithm is a variable metric Newton method. basemodel. which would indicate inconsistent constraints (or. In this case use lognormconst() instead.grad(params=None.reset(numfeatures=None) Resets the parameters self.setparams(params) Set the parameter vector to params.params to zero.setsmooth(sigma) Speciﬁes that the entropy dual and gradient should be computed with a quadratic penalty term on magnitude of the parameters. Reference . It calls the user-supplied callback function (if any). replacing the existing parameters.SciPy Reference Guide.10. or every gradient evaluation. ignorepenalty=False) Computes or estimates the gradient of the entropy dual. basemodel. callback_grad=None) Sets callback functions to be called every iteration. CG make potentially several function and gradient evaluations per iteration. this may be less robust than the gradient-based algorithms.g. samplespace=None) A maximum-entropy (exponential-form) model on a discrete sample space.logparams() Saves the model parameters if logging has been enabled and the # of iterations since the last save has reached self. and checks whether the process appears to be diverging. basemodel.model(f=None. or partition function. it is quite fast and requires only linear space in the number of parameters. The parameter ‘sigma’ will be squared and stored as self. too large a variance in the estimates). if so. this will result in numerical overﬂow. class scipy. For big models (where func and grad are simulated) with large variance in the function estimates. (not quadratic. so it is infeasible for more than about 10^3 parameters.normconst() Returns the normalization constant.

Release 0. The feature statistic f should be a list of functions [f1().f’.maxentropy) 311 .logpmf() Returns an array indexed by integers representing the logarithms of the probability mass function (pmf) at each point in the sample space under the current model (with the current parameter vector self. f(x))..F of features f of all points in the samplespace) model. model. Creates a new matrix self.10.logpmf() Returns an array indexed by integers representing the model.log Z) where theta is the current parameter vector self.8.pmf_function(f=None) Returns the pmf p_theta(x) as a function taking values on the model’s sample space.samplespace as a list or array.0.SciPy Reference Guide.expectations() The vector E_p[f(X)] under the model p_params of the vector of feature functions f_i over the sample space.params.samplespace] == pmf()).lognormconst() Compute the log of the normalization constant (partition model. 3. and stored as self.params). The returned pmf is deﬁned as: p_theta(x) = exp(theta..dev6665 Methods beginlogging clearcache crossentropy dual endlogging entropydual expectations fit grad log lognormconst logparams logpmf normconst pmf pmf_function probdist reset setcallback setfeaturesandsamplespace setparams setsmooth The vector E_p[f(X)] under the model p_params of the vector of model. model. The returned function p_theta also satisﬁes all([p(x) for x in self. Requires that the sample space be discrete and ﬁnite.. The sample space must be discrete and ﬁnite. model.lognormconst() Compute the log of the normalization constant (partition function) Z=sum_{x in samplespace} p_0(x) exp(params ..expectations() model.fn(x)]. This must be passed unless the model already contains an equivalent attribute ‘model.pmf_function([f]) Returns the pmf p_theta(x) as a function taking values on the model’s sample space. Maximum entropy models (scipy.setfeaturesandsamplespace(f.f(x) . model.

bigmodel A maximum-entropy (exponential-form) model on a large sample space. f is a list of feature functions f_i mapping the sample space to real values. doctests. extra_argv.. Reference .F. Methods beginlogging clearcache crossentropy dual endlogging entropydual estimate expectations fit grad log lognormconst logparams logpdf normconst pdf pdf_function resample reset setcallback setparams setsampleFgen setsmooth settestsamples stochapprox test([label. Release 0. samplespace) Creates a new matrix self. The model expectations are not computed exactly (by summing or integrating over a sample space) but approximately (by Monte Carlo estimation). Approximation is necessary when the sample space is too large to sum or integrate over in practice. This uses lots of memory but is much faster. . verbose. This is only appropriate when the sample space is ﬁnite. 312 Chapter 3. class scipy.params is initialized to zero.10.setfeaturesandsamplespace(f.maxentropy. like a continuous sample space in more than about 4 dimensions or a large discrete space like all possible sentences in a natural language.SciPy Reference Guide..dev6665 model.]) Run tests for module using nose. The tails should be fatter than the model. We also compute f(x) for each x in the sample space and store them as self. The parameter vector self.0. Approximating the expectations by sampling requires an instrumental distribution that should be close to the model for fast convergence.F of features f of all points in the sample space.

10. It doesn’t return anything.8.f(s_j) . In the matrix case.resample() (Re)samples the matrix F of sample features. Initializes the Monte Carlo sampler to use the supplied staticsample]) bigmodel. It uses these either in a matrix (with multiple runs) or with a sequential procedure.stochapprox(K) Tries to ﬁt the model to the feature expectations K using bigmodel.estimate() This function approximates both the feature expectation vector E_p f(X) and the log of the normalization term Z with importance sampling. Release 0. (This is done because some optimization algorithms retrieve the dual fn and gradient fn in separate function calls. bigmodel. .. the features F={f_i(s_j)} and vector [log_aux_dist(s_j)] of log probabilities are generated by calling resample().estimate() bigmodel. bigmodel.maxentropy) 313 .log aux_dist(s_j) • log f_i(s_j))) and denom = [n * Zapprox] 3. keeping track of the parameters that yield the minimum such dual.. Returns the estimated density p_theta(x) at the point x with feature statistic fx = f(x). but stores the member variables logZapprox. It also computes the sample variance of the component estimates of the feature expectations as: varE = var(E_1. We use [Rosenfeld01Wholesentence]’s estimate of E_p[f_i] as: {sum_j p(s_j)/aux_dist(s_j) f_i(s_j) } / {sum_j p(s_j) / aux_dist(s_j)}. mu and varE. bigmodel.SciPy Reference Guide.. E_T) where T is self.settestsamples(F_list.pdf_function() Returns the estimated density p_theta(x) as a function p(f) taking a vector f = f(x) of feature statistics at any point x. where num_i = exp(logsumexp(theta. Note that this is consistent but biased.pdf(fx) This function approximates both the feature expectation vector Returns the log of the estimated density p(x) = p_theta(x) at the point x.logpdf(fx[. This equals: {sum_j p_dot(s_j)/aux_dist(s_j) f_i(s_j) } / {sum_j p_dot(s_j) / aux_dist(s_j)} Compute the estimator E_p f_i(X) in log space as: num_i / denom.) It uses a supplied generator sampleFgen whose . with more updating overhead but potentially stopping earlier (needing fewer samples). but we can compute them more efﬁciently together.next() method returns features of random observations s_j generated according to an auxiliary distribution aux_dist. Requests that the model be tested every ‘testevery’ iterations logprob_list) bigmodel. bigmodel.matrixtrials and E_t is the estimate of E_p f(X) approximated using the ‘t’th auxiliary feature matrix. Maximum entropy models (scipy.test() Estimate the dual and gradient on the external samples. log_prior_x]) bigmodel.setsampleFgen(sampler[.dev6665 bigmodel.0.

314 Chapter 3.. The log pdf of the model is then deﬁned as log p(x) = log p0(x) + theta. This is useful for inspecting the output and understanding the model characteristics.log aux_dist(s_j))) = exp(logsumexp(theta.setsampleFgen(sampler.resample() (Re)samples the matrix F of sample features. staticsample=True) Initializes the Monte Carlo sampler to use the supplied generator of samples’ features and log probabilities..0..log Z where f(x) is given by the (m x 1) array fx.log aux_dist(s_j))) bigmodel.pdf_function() Returns the estimated density p_theta(x) as a function p(f) taking a vector f = f(x) of feature statistics at any point x. Reference . fx is a 2-d (m x n) array. where Z is the estimated value self... (which is useful for estimating variance between the different feature estimates).. Calling sampler.next() can optionally be a 3-tuple (F.next() return the entire sample feature matrix to be used each iteration to avoid overhead in extra function calls and memory copying (and extra code)... If matrixtrials > 1 and staticsample = True. where F is an (m x n) matrix of features of the n sample points x_1. instead. this is deﬁned as: log p(x) = theta. bigmodel. This is deﬁned as p_theta(x) = exp(theta.normconst() of the partition function. If log_prior_x is None. and lp is an array of length n containing the (natural) log probability density (pdf or pmf) of each point under the auxiliary sampling distribution.matrixtrials) for each iteration.x_n. log Z is estimated using the sample provided with setsampleFgen().SciPy Reference Guide. and returns an array containing the log pdf value of each point x_j under the current model. lp. log_prior_x=None) Returns the log of the estimated density p(x) = p_theta(x) at the point x.f(x)) / Z bigmodel.sample. each of which stays constant over all iterations.n-1 as a feature vector f(x_j). this function interprets each of its rows j=0..lognormconst()). sample) instead of a 2-tuple (F. lp). This is an alternative to deﬁning a sampler in terms of a (ﬁxed size) feature matrix sampleF and accompanying vector samplelogprobs of log probabilities. Release 0. This allows using a set of feature matrices. We can compute the denominator n*Zapprox directly as: exp(logsumexp(log p_dot(s_j) . The output of sampler.log Z and p then represents the model of minimum KL divergence D(p||p0) instead of maximum entropy. lp)..next() will be called once for each trial (0.f(x)) / Z(theta). In this case the value ‘sample’ is then stored as a class variable self.pdf(fx) Returns the estimated density p_theta(x) at the point x with feature statistic fx = f(x)..logpdf(fx. We now insist that sampleFgen. bigmodel. If.10.f(s_j) . bigmodel.next() should generate tuples (F. The optional argument log_prior_x is the log of the prior density p_0 at the point x (or at each point x_j if fx is 2-dimensional).. sampler. This is deﬁned as: p_theta(x) = exp(theta.f(x) .f(x) .dev6665 where Zapprox = exp(self.

numcontexts) A conditional maximum-entropy (exponential-form) model p(x|w) on a discrete sample space.. The vector of desired (target) feature expectations is stored as self.SciPy Reference Guide.. while True: . x)). it should be a list of arrays of log(p0(x_j)) values.test() Estimate the dual and gradient on the external samples.i] for i in range(3)] [1. . .K) evaluated at the point theta_k. which must be supplied to the constructor as the parameter ‘samplespace’.a_k e_k where g_k is the gradient vector (= feature expectations E . 1. bigmodel. >>> model.. If priorlogprob_list is not None. each representing a sample {x_j} from an auxiliary distribution q. n += 1 . n .. theta) is a normalization term equal to: Z(w.. class scipy. theta) where Z(w. specifying the prior distribution p0 for the sample points x_j for each of the test samples. x)) / Z(w. rather than passing it as an argument to this function.maxentropy) 315 ..0..) bigmodel. But this code was unmaintained.testevery > 1.setsampleFgen(sampler()) >>> type(model.. f(w.a_0 in the model.maxentropy. only perform the test every self. sampler1. f[0.1. j = 0. The sum is over all classes x in the set Y. If self.0 .. counts.. f[0.2] = n+1 . Example use: >>> import spmatrix >>> model = bigmodel() >>> def sampler(): . a_k is the sequence a_k = a_0 / k.testevery calls. together with the corresponding log probabiltiy mass or density values log {q(x_j)} in logprob_list.sampleF[0. keeping track of the parameters that yield the minimum such dual..K. f[0.. which could otherwise reﬂect the vagaries of the single sample being used for optimization. rather than the population as a whole.. where it can be written over (perhaps with the default function argument by accident) when we re-call this func (e.3) . priorlogprob_list=None) Requests that the model be tested every ‘testevery’ iterations during ﬁtting using the provided list F_list of feature matrices.. yield f. Maximum entropy models (scipy.. f = spmatrix.. Release 0. bigmodel. f(w. one for each feature and one for estimating the normalization constant Z.. sampler=[sampler0.0] We now set matrixtrials as a class property instead. n = 0 .10.0. where a_0 is some step size parameter deﬁned as self.0. X) where the expectation is with respect to the distribution: q(w) p(x | w) 3.8.. Such a model form arises from maximizing the entropy of a conditional model p(x | w) subject to the constraints: K_i = E f_i(W. logprob_list.. samplerZ].0] = n+1. We assume e_k has nice enough properties for the algorithm to converge. 1. to change the matrix size.stochapprox(K) Tries to ﬁt the model to the feature expectations K using stochastic approximation. This is useful for classiﬁcation problems: given the context w. This is useful as an external check on the ﬁtting process with sample path optimization.dev6665 An alternative was to supply a list of samplers..ll_mat(1..g.conditionalmodel(F. theta) = sum_x exp(theta . 1. and has now been removed (but it’s in Ed’s CVS repository :). what is the probability of each class x? The form of such a model is: p(x | w) = exp(theta . testevery=1.sampleFgen) <type ‘generator’> >>> [model.1] = n+1. sampler_{m-1}. with the Robbins-Monro stochastic approximation algorithm: theta_{k+1} = theta_k + a_k g_k .settestsamples(F_list. and e_k is an unknown error term representing the uncertainty of the estimate of g_k.

10. dual function is deﬁned for conditional models as The entropy ignorepenalty]) conditionalmodel. theta) .x}. where c are contexts and x are points in the sample space.dual([params. conditionalmodel. Reference . not the entire sample space.x)] Note that both sums are only over the training set {w.x) = 0 for all w. This method minimizes the Lagrangian dual L of the entropy. which is deﬁned for conditional models as: L(theta) = sum_w q(w) log Z(w.x) [theta . ignorepenalty=False) The entropy dual function is deﬁned for conditional models as L(theta) = sum_w q(w) log Z(w. x).fit([algorithm]) Fits the conditional maximum entropy model subject to the conditionalmodel. Methods beginlogging clearcache crossentropy dual endlogging entropydual expectations fit grad log lognormconst logparams logpmf normconst pmf pmf_function probdist reset setcallback setfeaturesandsamplespace setparams setsmooth conditionalmodel. Release 0.dev6665 where q(w) is the empirical probability mass function derived from observations of the context w in a training set.logpmf() a (sparse) row vector of logarithms of the conditional probability mass Returns function (pmf) values p(x | c) for all pairs (c.expectations()expectations of the features with respect to the The vector of conditionalmodel. x) with respect to the empirical distribution.SciPy Reference Guide. Y) where the expectation is as deﬁned above.E f_i(X.sum_{w. theta) • sum_{w.x)] 316 Chapter 3.x not in the training set. f(w.lognormconst() Compute the elementwise log of the normalization constant conditionalmodel.dual(params=None. Normally the vector K = {K_i} of expectations is set equal to the expectation of f_i(w.0.x} q(w.x} q(w. since q(w.x) [theta . The partial derivatives of L are: dL / dtheta_i = K_i . f(w.

10.. x} p_tilde(w) p(x | w) f_i(w. x} q(w. Maximum entropy models (scipy. The order of these is log p(x | c) = logpmf()[c * numsamplepoints + x].logpmf() Returns a (sparse) row vector of logarithms of the conditional probability mass function (pmf) values p(x | c) for all pairs (c.expectations() The vector of expectations of the features with respect to the distribution p_tilde(w) p(x | w). conditionalmodel.SciPy Reference Guide.0. Copyright: Ed Schoﬁeld. 3. where p_tilde(w) is the empirical probability mass function value stored as self. x) will be 1. x). 2003-2006 License: BSD-style (see LICENSE. y)). and where q(w) is the empirical probability mass function derived from observations of the context w in a training set. scipy sparse matrices. Normally q(w. since q(w. and PySparse matrices a common interface.lognormconst() Compute the elementwise log of the normalization constant (partition function) Z(w)=sum_{y in Y(w)} exp(theta . f(w.txt in main source directory) 3. The entropy dual function is proportional to the negative log likelihood.x not in the training set.m. conditionalmodel. Most of them are either Python replacements for the corresponding Fortran routines or wrappers around matrices to allow the maxent module to manipulate ndarrays.. theta) . Compare to the entropy dual of an unconditional model: L(theta) = log(Z) .(theta .8. x). x} p_tilde(w. where c are contexts and x are points in the sample space.theta^T .. where k_i is the empirical expectation k_i = sum_{w. x). x) f_i(w.maxentropy) 317 . x) = k_i for i=1. k) where K_i = sum_{w. Release 0. Note that both sums are only over the training set {w.8.fit(algorithm=’CG’) Fits the conditional maximum entropy model subject to the constraints sum_{w. This is a vector with one element for each context w.p_tilde_context[w]..x}.x) = 0 for all w. conditionalmodel. The sample space must be discrete and ﬁnite. not the entire sample space. x) f_i(w. Perhaps the logsumexp() function belongs under the utils/ branch where other modules can access it more easily. K conditionalmodel. unless the same class label is assigned to the same context more than once.3 Utilities Utility routines for the maximum entropy module.dev6665 or equivalently as L(theta) = sum_w q(w) log Z(w.

the complex log cmath.maxentropy. and PySparse arrays.2].maxentutils. sparsefeatures(f. which is much more helpful.exp() and.. and PySparse arrays. (The normalization is by (m . x) Returns a dense array of non-zero evaluations of the functions ﬁ dotprod(u. rowmeans(A) This is a wrapper for general dense or sparse dot products.[3. with python’s math.0. innerprodtranspose(A.e^{a_n}) logsumexp_naive(values) testing logsumexp(). This v) logsumexp(a) Compute the log of the sum of exponentials log(e^{a_1}+.4]].SciPy Reference Guide...f_m in the list f at the points x_1. Returns a dense (1 x n) vector with unbiased estimators for the column variances for each column of the (m x n) sparse or dense matrix A. if that fails. flatten(a) Flattens the sparse matrix or dense array/matrix ‘a’ into a innerprod(A.’d’) >>> columnmeans(a) array([ 2. [3. whereas python’s math.maxentutils. numpy.Returns an (m x n) dense array of non-zero evaluations of the sample) densefeatures(f.4]]. arrayexpcomplex(x) Returns the elementwise antilog of the vector x. Reference . 2. 3. numpy..maxentutils. k) sparsefeaturematrix(f..columnvariances(A) This is a wrapper for general dense or sparse dot products.exp().exp() is about 10 times faster but throws an OverﬂowError exception for numerical underﬂow (e. Returns a dense (1 x n) vector with the column averages of A. columnmeans(A) This is a wrapper for general dense or sparse dot products. format]) functions f_1. with python’s math. exp(-800)..exp() just returns zero.x_n in the sequence ‘sample’.maxentropy. scipy spmatrix.2].array([[1. ’d’) >>> columnvariances(a) array([ 2.. which is much more helpful...array([[1. >>> a = numpy.]) 318 Chapter 3.g.. scipy.exp() is about 10 times faster but throws an OverﬂowError exception for numerical underﬂow (e. format]) scipy. if that fails.columnmeans(A) This is a wrapper for general dense or sparse dot products.1). v) This is a wrapper around general dense or sparse dot products. whereas python’s math.exp(). It is not necessary except as a common interface for supporting ndarray. We try to exponentiate with numpy.maxentropy.g.. exp(-800). Returns an Mx1 sparse matrix of non-zero evaluations of the x[.exp() and. is a wrapper around general dense or sparse dot products.10.dev6665 arrayexp(x) Returns the elementwise antilog of the real array x.) >>> a = numpy. Returns an (m x n) sparse matrix of non-zero evaluations of the scalar or vector sample[. We try to exponentiate with numpy. which can be an (m x n) sparse or dense matrix.log(x) if x < 0. v) This is a wrapper around general dense or sparse dot products.arrayexp(x) Returns the elementwise antilog of the real array x.arrayexpcomplex(x) Returns the elementwise antilog of the vector x.maxentropy. densefeaturematrix(f.maxentutils. It is only necessary as a common interface for supporting ndarray. Chooses k random elements (with replacement) from a population. Release 0. columnvariances(A) This is a wrapper for general dense or sparse dot products.]) scipy. scipy.exp() just returns zero.. scipy spmatrix. For robustlog(x) Returns log(x) if x > 0. sample_wr(population.

maxentutils.5.5]) scipy.T. scipy. and PySparse arrays. scipy. scipy spmatrix..maxentutils.4]].matvec(v.8. k) Chooses k random elements (with replacement) from a population. and PySparse arrays.robustlog(x) Returns log(x) if x > 0.maxentropy. This function is efﬁcient for large matrices A.maxentutils.sample_wr(population. scipy. Maximum entropy models (scipy..maxentropy.dot(v) for dense arrays and spmatrix objects.. V must be a rank-1 array. This is a wrapper for u.dev6665 scipy. (From the Python Cookbook).matvec_transp(v.dot(v) for dense arrays and spmatrix objects.maxentropy. 3. This is a wrapper for A.maxentutils.[3. 720).flatten(a) Flattens the sparse matrix or dense array/matrix ‘a’ into a 1-dimensional array scipy..densefeatures(f.innerprod(A. or ﬂoat(‘-inf’) if x == 0. >>> a = numpy.. the complex log cmath.maxentropy) 319 . which be an (m x n) sparse or dense matrix. It is not necessary except as a common interface for supporting ndarray. and for A. and for u.maxentropy. If A is sparse. and PySparse arrays.. Computes A^T V.log(x) if x < 0. not a matrix. scipy. It is not necessary except as a common interface for supporting ndarray. scipy.maxentropy..10.innerprodtranspose(A.dotprod(u. x) Returns a dense array of non-zero evaluations of the functions ﬁ in the list f at the point x. Returns a dense (m x 1) vector representing the mean of the rows of A.maxentropy.maxentutils. Returns the inner product of the (m x n) dense or sparse matrix A with the n-element dense array v. scipy.maxentropy.x_n in the list sample.. scipy.x_n in the sequence ‘sample’. Subject to numerical overﬂow for large values (e. Release 0.densefeaturematrix(f.maxentutils. It is not necessary except as a common interface for supporting ndarray.0.. scipy. format=’csc_matrix’) Returns an (m x n) sparse matrix of non-zero evaluations of the scalar or vector functions f_1.maxentropy. It is only necessary as a common interface for supporting ndarray..e^{a_n}) of the components of the array a. scipy spmatrix.SciPy Reference Guide.maxentutils. Returns the dot product of the (1 x m) sparse array u with the (m x 1) (dense) numpy array v. v) This is a wrapper around general dense or sparse dot products. v) This is a wrapper around general dense or sparse dot products.. and PySparse arrays.array([[1.f_m in the list f at the points x_1.maxentropy.g.. result) for pysparse matrices. avoiding numerical overﬂow. result) for PySparse matrices..maxentropy.. 3.logsumexp(a) Compute the log of the sum of exponentials log(e^{a_1}+.maxentutils. where A is a dense or sparse matrix and V is a numpy array.sparsefeaturematrix(f. v) This is a wrapper around general dense or sparse dot products. scipy spmatrix.maxentutils.logsumexp_naive(values) For testing logsumexp().rowmeans(A) This is a wrapper for general dense or sparse dot products. scipy spmatrix. sample.maxentropy. sample) Returns an (m x n) dense array of non-zero evaluations of the scalar functions ﬁ in the list f at the points x_1.maxentropy. scipy.maxentutils.maxentutils.maxentutils. float) >>> rowmeans(a) array([ 1.2].

scipy.f_m in the list f at the point x. Various utilities that don’t have another home.. A trimmed-down version.SciPy Reference Guide. patched for NumPy compatibility.sparsefeatures(f.9 Miscellaneous routines (scipy.misc) Warning: This documentation is work-in-progress and unorganized.0.10. x. patched for NumPy compatibility. format=’csc_matrix’) Returns an Mx1 sparse matrix of non-zero evaluations of the scalar functions f_1.maxentropy. A trimmed-down version...dev6665 If format=’ll_mat’. is available in the SciPy sandbox/pysparse directory..maxentutils. 3. linalg) 320 Chapter 3.1 Modules common doccer pilutil setup setupscons Functions which are common and require SciPy Base and Level 1 SciPy Utilities to allow inserting docstring fragments for common A collection of image utilities using the Python Imaging Library (PIL). the PySparse module (or a symlink to it) must be available in the Python site-packages/ directory.9. Functions which are common and require SciPy Base and Level 1 SciPy (special. 3. the PySparse module (or a symlink to it) must be available in the Python site-packages/ directory. If format=’ll_mat’. Release 0. is available in the SciPy sandbox/pysparse directory. Reference . Note that the Python Imaging Library (PIL) is not a dependency of SciPy and therefore the pilutil module is not available on systems that don’t have PIL installed.

misc) 321 . Dot product of two arrays. Find the n-th derivative of a function at point x0. Return the product of array elements over a given axis. Get classic image processing example image. either from x or y. n. dtype.dev6665 Functions arange([dtype]) array(object[. r. The factorial function. m) place(arr. mask. Return elements. depending on condition. ﬁlled with zeros.10. dx. order]) central_diff_weights(Np[. Return a 2-D array with ones on the diagonal and zeros elsewhere. Utilities to allow inserting docstring fragments for common parameters into function and method docstrings Functions docformat(docstring[. k[. order]) dot(a.9. Note that PIL is not a dependency of SciPy and this module is not available on systems that don’t have PIL installed. x0[. Release 0. dtype.gamma(n+1). ndmin]) asarray(a[. including ﬁrst A collection of image utilities using the Python Imaging Library (PIL). Create an array. k[.. copy. arr) eye(N[. exact]) factorialk(n. n(!!. order. 3. Lena. variable]) A one-dimensional polynomial class. exact]) factorial2(n[. return a Pade approximation to Change elements of an array based on conditional and input values. Return weights for an Np-point central derivative of order ndiv The number of combinations of N things taken k at a time. dtype. subok. Convert the input to an array. exact]) hstack(tup) lena() pade(an. at 8-bit grayscale Given Taylor series coefﬁcients in an. unindent_params]) indentcount_lines(lines) unindent_dict(docdict) unindent_string(docstring) Fill a function docstring from variables in dictionary Return docstring decorator using docdict variable dictionary Minumum indent for all lines in line list Unindent all strings in a docdict Set docstring to minimum indent for all lines. Double factorial. Miscellaneous routines (scipy. dtype]) factorial(n[. vals) product(a[. M. Return a new array of given shape and type. n! = special. docdict]) filldoc(docdict[. exact]) derivative(func. k.!) = multifactorial of order k Stack arrays in sequence horizontally (column wise). out]) extract(condition.SciPy Reference Guide.0. b[. x) zeros(shape[. out]) where(condition. dtype. order]) Classes poly1d(c_or_r[.. args. Return the elements of an array that satisfy some condition. axis. Return evenly spaced values within a given interval. ndiv]) comb(N.

cmax. Reference . out]) amin(a[.. dtype. dtype. dtype. axis. top_path]) Return the maximum of an array or maximum along an axis. Returns True if ﬁrst argument is a typecode lower/equal in type hierarchy. high. Byte scales an array (image). Return evenly spaced values within a given interval. order]) sum(a[. arg2) ones(shape[. ﬂatten]) imresize(arr. order]) bytescale(data[. theta]) ravel(a[. Rotate an image counter-clockwise by angle degrees. Sum of array elements over a given axis. top_path]) Functions configuration([parent_package. interp. ﬁlled with zeros. dtype. Simple ﬁltering of an image. interp]) imsave(name. Resize an image. Return True if x is a complex type or an array of complex numbers. Simple showing of an image through an external viewer. Return a new array of given shape and type. axis. 322 Chapter 3. . out]) arange([dtype]) array(object[. cmax. Save an array to an image ﬁle. axis.dev6665 Functions amax(a[. order. Create an array. Return a ﬂattened array. ﬁlled with ones. cmin. Return a new array of given shape and type. Read an image ﬁle from a ﬁlename. out]) toimage(arr[. ﬂatten]) imfilter(arr.]) transpose(a[. angle[. mode]) imrotate(arr. low]) fromimage(im[. Release 0. subok. dtype. order]) radon(arr[. ndmin]) asarray(a[. cmin. copy. Return the minimum of an array or minimum along an axis. The mode of the Permute the dimensions of an array. Takes a numpy array and returns a PIL image. pal. Convert the input to an array. ftype) imread(name[. order]) Classes uint8 Functions configuration([parent_package. Return a copy of a PIL image as a numpy array. arr) imshow(arr) iscomplexobj(x) issubdtype(arg1. low. size[.0. high.SciPy Reference Guide.. axes]) zeros(shape[.10.

Examples >>> img = array([[ 91. cmin. Returns img_array : ndarray Bytescaled array.. Get classic image processing example image. cmax. 0.. interp.gamma(n+1).10. 4]. toplevel]) lena() pade(an. cmax=None. 90. [140. .4221549 ]. Default is data.39058326. 80. k[.dev6665 3. The mode of the scipy. high : scalar Scale max value to high.06794177. cmin. Rotate an image counter-clockwise by angle degrees. Default is data. mode]) imrotate(arr. Save an array to an image ﬁle. interp]) imsave(name. Miscellaneous routines (scipy. args. n(!!. >>> bytescale(img) array([[255. m) radon(arr[.9. 4. Double factorial. Find the n-th derivative of a function at point x0.bytescale(data..]) Byte scales an array (image). [205. high.. Read an image ﬁle from a ﬁlename. n. low : scalar Scale min value to low. angle[.45808177.misc. high. cmax : scalar Bias scaling of large values.misc) 323 .min(). k[. low]) central_diff_weights(Np[. pal. cmin : Scalar Bias scaling of small values. ndiv]) comb(N. arr) imshow(arr) info([object.9. exact]) fromimage(im[. [ 73. high=255. Lena. theta]) toimage(arr[. class. 70]].2 Functions bytescale(data[. low=100) 84. exact]) factorialk(n. dtype=uint8) >>> bytescale(img. maxwidth. output. Resize an image. 3. high=200. 27. 34. n! = special. return a Pade approximation to Takes a numpy array and returns a PIL image.SciPy Reference Guide. 225. ﬂatten]) imfilter(arr. low. Simple ﬁltering of an image. Simple showing of an image through an external viewer. 236]. size[.max().88878881]. Release 0.0. Return weights for an Np-point central derivative of order ndiv The number of combinations of N things taken k at a time. dx. ftype) imread(name[. cmax. [ 51. ﬂatten]) imresize(arr.5873488 ]]) 3.88003259. x0[. at 8-bit grayscale Given Taylor series coefﬁcients in an. low=0) Byte scales an array (image). exact]) factorial2(n[. cmin=None.!) = multifactorial of order k Return a copy of a PIL image as a numpy array.91433048. or module. Parameters data : ndarray PIL image data array. order]) factorial(n[. exact]) derivative(func.53875334. The factorial function. Get help information for a function.

5].misc. 34. exact=0) The number of combinations of N things taken k at a time. Parameters func : function Input function.misc. Release 0. k : int. •If k > N. Notes •Array arguments accepted only for exact=0 case. Returns val : int. optional If exact is 0. Examples >>> k = np. array Number of elements taken. exact=True) 120L scipy. x0. then a 0 is returned. 192].0.]) >>> sc. 84]. dtype=uint8) >>> bytescale(img. use a central difference formula with spacing dx to compute the n-th derivative at x0. array Number of things. 3. array The total number of combinations.comb(N.comb(n.10. 210. Given a function. [52. 102].derivative(func. then ﬂoating point precision is used.SciPy Reference Guide.misc. 188. then derivative is w[0] * f(x-ho*dx) + .. 81. [180. otherwise exact long integer is computed. dtype=uint8) scipy. [155. 4]) >>> n = np. n=1. 100. This is often expressed as “N choose k”. args=(). k. [74.0.dev6665 array([[200.central_diff_weights(Np. 28]]. 135.array([3. 128]]. N < 0. scipy. exact : int. cmin=0.. + w[-1] * f(x+h0*dx) Notes Can be inaccurate for large number of points. Reference .array([10. exact=False) array([ 120. 324 Chapter 3. cmax=255) array([[91. 3.comb(10. or k < 0. order=3) Find the n-th derivative of a function at point x0. ndiv=1) Return weights for an Np-point central derivative of order ndiv assuming equally-spaced function points. If weights are in the vector w. dx=1. 10]) >>> sc. Parameters N : int.. k.

. then ﬂoating point precision is used.0. >>> derivative(x2. Default is False..4. must be odd.. the return value is 0.. If exact is set to True. optional Spacing. optional Arguments order : int. Default is 1. 120.5]) >>> sc. If n < 0.10. Release 0.]) >>> sc. dx : int.SciPy Reference Guide. Miscellaneous routines (scipy. Returns nf : ﬂoat or int Factorial of n.misc) 325 . Examples >>> def x2(x): . exact=False) array([ 6..gamma(n+1). n : int. Parameters n : int or array_like of ints Calculate n!. Notes Decreasing the step size too small can result in round-off error. as an integer or a ﬂoat depending on exact. •If n<0. calculate the answer exactly using integer arithmetic. exact=True) 120L 3. optional Order of the derivative.factorial(arr. •Array argument accepted only for exact=0 case. optional Number of points to use. n! = special.array([3. 2) 4.misc.9. Examples >>> arr = np. optional The result can be approximated rapidly using the gamma-formula above. otherwise exact long integer is computed. exact : bool.factorial(5. the return value is 0. args : tuple. 24. If exact is 0.0 scipy.factorial(n. exact=0) The factorial function. return x*x .. Arrays are only supported with exact set to False.dev6665 x0 : ﬂoat The point at which nth derivative is found.

exact=True) 10L 326 Chapter 3.factorialk(5.gamma(n/2+1)*2**((m+1)/2)/sqrt(pi) = 2**(n/2) * (n/2)! Parameters n : int or array_like Calculate n!!.factorialk(n. Arrays are only supported with exact set to False. Returns val : int Multi factorial of n.0.10..dev6665 scipy. calculate the answer exactly using integer arithmetic. 1. exact=True) 105L scipy. 7!! numerically as: = 7 * 5 * 3 * 1.SciPy Reference Guide. k. Raises NotImplementedError : Raises when exact is False Examples >>> sc. i. Reference . Release 0. Arrays are only supported with exact set to False. exact : bool..misc. calculate the answer exactly using integer arithmetic. optional If exact is set to True. This is the factorial with every second value skipped. exact=True) 120L >>> sc.factorial2(n. 3.. exact : bool. It can be approximated n odd n even n!! = special. the return value is 0. exact=False) array(105. If exact is set to True. as an int or a ﬂoat depending on exact.factorialk(5. the return value is 0. optional The result can be approximated rapidly using the gamma-formula above (default).00000000000001) >>> factorial2(7.!) = multifactorial of order k k times Parameters n : int. array_like Calculate multifactorial.misc. Examples >>> factorial2(7. If n < 0. exact=False) Double factorial.e. If n < 0. Returns nff : ﬂoat or int Double factorial of n. exact=1) n(!!.

Legal values are: ‘blur’. Parameters name : str The ﬁle name to be read. Miscellaneous routines (scipy. Notes The image is ﬂattened by calling convert(‘F’) on the resulting image object.dev6665 scipy. Returns img_array : ndarray The different colour bands/channels are stored in the third dimension.imfilter(arr. Returns res : nd_array The array with ﬁlter applied. size. If the ﬁlter you are trying to apply is unsupported.imread(name. ﬂatten : bool. ﬂatten=0) Return a copy of a PIL image as a numpy array. an RGB-image MxNx3 and an RGBA-image MxNx4. scipy. convert the output to grey-scale. such that a grey-image is MxN. Returns : nd_array : The array obtained by reading image. ‘contour’. mode=None) Resize an image. Raises ValueError : Unknown ﬁlter type. interp=’bilinear’.SciPy Reference Guide. Parameters im : PIL image Input image. ‘edge_enhance_more’. .0. ‘smooth’.misc.misc. ‘emboss’. ‘sharpen’. scipy. Parameters arr : ndarray The array of Image in which the ﬁlter is to be applied. Release 0. ‘detail’.imresize(arr. 3.10.misc.9. ﬂatten : bool If true.misc. ﬂatten=0) Read an image ﬁle from a ﬁlename.misc) 327 . ‘ﬁnd_edges’. ﬂattens the color layers into a single gray-scale layer. ftype : str The ﬁlter that has to be applied. ftype) Simple ﬁltering of an image. optional If True.fromimage(im. ‘smooth_more’. scipy. ‘edge_enhance’.

misc. interp : string interpolation to use for re-sizing (‘nearest’. angle : ﬂoat The angle of rotation. angle. arr) Save an array to an image ﬁle.10.misc.dev6665 Parameters arr : nd_array The array of image to be resized. optional Interpolation Returns : nd_array : The rotated array of image. size : int. etc.0.Fraction of current size. ‘bilinear’.imrotate(arr.) Returns : nd_array : The resized array of image. Parameters arr : nd_array Input array of image to be rotated.Size of the output image. convert the output to grey-scale. scipy. ﬂatten : bool If true. ‘bicubic’ or ‘cubic’) mode : : mode is the PIL image mode (‘P’. Release 0. Notes Interpolation methods can be: * ‘nearest’ : for nearest neighbor * ‘bilinear’ : for bilinear * ‘cubic’ : cubic * ‘bicubic’ : for bicubic scipy.imsave(name. ﬂoat or tuple • int . interp : str.Percentage of current size. Returns img_array : ndarray 328 Chapter 3. ‘L’. interp=’bilinear’) Rotate an image counter-clockwise by angle degrees. • tuple . • ﬂoat . Parameters im : PIL image Input image. Reference .SciPy Reference Guide.

When using a string for object it is possible to get multiple results. its docstring is given.misc) 329 .dev6665 The different colour bands/channels are stored in the third dimension. output : ﬁle like object.SciPy Reference Guide. If None.pilutil.info(np.tile(np. Returns None : Examples >>> a = np. toplevel : str. np. such that a grey-image is MxN. 0x7f28120b5198>. If it is a string.9.info(object=None. See Also: source.0.polyval) polyval(p. output=<open ﬁle ‘<stdout>’. lookfor Notes When used interactively with an object.arange(255). If object is a numpy object. maxwidth : int.1)) >>> from scipy import misc >>> misc.10. (255.misc. Examples >>> np. scipy. or module. maxwidth=76. x) Evaluate the polynomial p at x.imshow(arr) Simple showing of an image through an external viewer. optional mode ‘w’ at Input object or name to get information about. . Uses the image viewer speciﬁed by the environment variable SCIPY_PIL_IMAGE_VIEWER. default is stdout.. or if that is not deﬁned then see. Parameters object : object or str. The object has to be opened in ‘w’ or ‘a’ mode.. Miscellaneous routines (scipy.misc. class. toplevel=’scipy’) Get help information for a function. optional Start search at this level. information about info itself is returned. 3. an RGB-image MxNx3 and an RGBA-image MxNx4. to view a temporary ﬁle generated from array data. Parameters arr : ndarray Array of image data to show.imshow(a) scipy. optional Printing width. Release 0. optional File like object that the output is written to. available modules are searched for matching objects.info(obj) is equivalent to help(obj) on the Python prompt or obj? on the IPython prompt.

n=None. Release 0. axis=-1) . *** Found in numpy.SciPy Reference Guide.misc.pyplot as plt plt.dtype dtype(’int32’) >>> >>> >>> >>> import matplotlib.imshow(lena) plt.show() 0 100 200 300 400 500 0 100 200 300 400 500 scipy...shape (512. *** scipy.pade(an. at 8-bit grayscale bit-depth..fft *** fft(a..dev6665 >>> np. return a Pade approximation to the function as the ratio of two polynomials 330 Chapter 3.max() 245 >>> lena. Reference .lena() >>> lena. m) Given Taylor series coefﬁcients in an.10.fft.lena() Get classic image processing example image. 512) >>> lena.gray() plt. 512 x 512 size.misc. *** Repeat reference found in numpy.0.info(’fft’) *** Found in numpy *** Core FFT routines .misc >>> lena = scipy.misc. Parameters None : Returns lena : ndarray Lena image Examples >>> import scipy.fftpack *** *** Total of 3 references found. Lena.

misc. channel_axis=None) Takes a numpy array and returns a PIL image. optional A dictionary possibly containing ndarrays. ’idx’:5} >>> np. For 3-D arrays if one of the dimensions is 3.misc.0). Release 0.. shape.dev6665 p / q where the order of q is m.. scipy. If there is no dictionary passed in or vardict is None then returns Numpy arrays in the globals() dictionary (all Numpy arrays in the namespace). cmin=None. . the channel_axis argument tells which dimension of the array holds the channel data.9.radon(arr.who() Name Shape Bytes Type =========================================================== a 10 40 int32 b 20 160 float64 Upper bound on total bytes = 200 >>> d = {’x’: np. scipy. bytes and type of all of the ndarrays present in vardict. unless mode is given as ‘F’ or ‘I’ in which case a ﬂoat and/or integer array is made For 3-D arrays.10.ones(20) >>> np. low=0.arange(10) >>> b = np.arange(3. For 2-D arrays.misc. pal=None.0. Notes Prints out the name. ’txt’: ’Some str’. Default is globals(). mode=None. Parameters vardict : dict. cmax=None. high=255. if the The numpy array must be either 2 dimensional or 3 dimensional. the pal keyword.toimage(arr.SciPy Reference Guide. Examples >>> a = np.0). otherwise mode=’L’. and the mode keyword. the mode is ‘RGB’ by default or ‘YCbCr’ if selected.3) byte-array giving the RGB values (from 0 to 255) then mode=’P’. Miscellaneous routines (scipy.arange(2. The mode of the PIL image depends on the array shape.who(vardict=None) Print the Numpy arrays in the given dictionary. if pal is a valid (N. ’y’: np.misc) 331 . theta=None) scipy. Returns out : None Returns ‘None’.who(d) Name Shape Bytes Type =========================================================== y 3 24 float64 x 2 16 float64 Upper bound on total bytes = 40 3.

maxwidth=76. If it is a string. optional If output not supplied then source code is printed to screen (sys..misc.source(object. right) The source code is only returned for objects written in Python.source(np. output : ﬁle like object. If None.interp) In file: /usr/lib/python2. >>> np. output=<open ﬁle ‘<stdout>’.. Parameters object : numpy object Input object. toplevel=’scipy’) Get help information for a function.10. info Examples >>> np. If object is a numpy object. right=None): """.source(np. xp.. This can be any object (function. mode ‘w’ at 0x7f28120b5198>) Print or write to a ﬁle the source code for a Numpy object. xp. (full docstring printed)""" if isinstance(x.info(object=None. See Also: lookfor. File object must be created with either write ‘w’ or append ‘a’ modes.SciPy Reference Guide. its docstring is given. available modules are searched for matching objects. left. fp.0. number)): return compiled_interp([x]. class.. (float. fp. output=<open ﬁle ‘<stdout>’.6/dist-packages/numpy/lib/function_base. optional Printing width. xp. . lookfor 332 Chapter 3. The object has to be opened in ‘w’ or ‘a’ mode. default is stdout. information about info itself is returned. maxwidth : int.py def interp(x. right). 0x7f28120b5198>.. class. fp. left=None. See Also: source. Parameters object : object or str.misc.item() else: return compiled_interp(x. optional Start search at this level.dev6665 scipy. Many functions and classes are deﬁned in C and will therefore not return useful information. optional mode ‘w’ at Input object or name to get information about.). int.stdout). optional File like object that the output is written to. or module. Release 0. toplevel : str. output : ﬁle object.array) Not available for this object. scipy. left. Reference . module. The source code is only returned for objects written in Python.

The mode of the PIL image depends on the array shape. an RGB-image MxNx3 and an RGBA-image MxNx4.9. ﬂatten : bool If true. When using a string for object it is possible to get multiple results.misc. np. For 3-D arrays if one of the dimensions is 3..fftpack *** *** Total of 3 references found. the channel_axis argument tells which dimension of the array holds the channel data.. the pal keyword. low=0. *** Repeat reference found in numpy. n=None.fft. such that a grey-image is MxN. if the The numpy array must be either 2 dimensional or 3 dimensional.info(np. arr) Save an array to an image ﬁle.info(’fft’) *** Found in numpy *** Core FFT routines .10. convert the output to grey-scale. scipy. . Miscellaneous routines (scipy.polyval) polyval(p.imsave(name. Release 0. >>> np. channel_axis=None) Takes a numpy array and returns a PIL image. *** scipy..fft *** fft(a. pal=None. 3. axis=-1) . ﬂatten=0) Return a copy of a PIL image as a numpy array.toimage(arr. the mode is ‘RGB’ by default or ‘YCbCr’ if selected. For 2-D arrays. otherwise mode=’L’. *** Found in numpy...fromimage(im. high=255. x) Evaluate the polynomial p at x.0. if pal is a valid (N. scipy.3) byte-array giving the RGB values (from 0 to 255) then mode=’P’. cmax=None. and the mode keyword. Examples >>> np.misc.SciPy Reference Guide. Parameters im : PIL image Input image.misc) 333 .dev6665 Notes When used interactively with an object. Returns img_array : ndarray The different colour bands/channels are stored in the third dimension. unless mode is given as ‘F’ or ‘I’ in which case a ﬂoat and/or integer array is made For 3-D arrays.info(obj) is equivalent to help(obj) on the Python prompt or obj? on the IPython prompt. cmin=None..misc. mode=None.

scipy. Parameters data : ndarray PIL image data array. low : scalar Scale min value to low. scipy. Parameters name : str The ﬁle name to be read. such that a grey-image is MxN. Default is data. ﬂattens the color layers into a single gray-scale layer. Notes The image is ﬂattened by calling convert(‘F’) on the resulting image object. 334 Chapter 3. convert the output to grey-scale. Returns img_array : ndarray The different colour bands/channels are stored in the third dimension. an RGB-image MxNx3 and an RGBA-image MxNx4. Returns img_array : ndarray Bytescaled array. optional If True. ﬂatten=0) Read an image ﬁle from a ﬁlename. Reference .imread(name. Release 0.bytescale(data. cmin=None. Default is data. cmax=None.misc.SciPy Reference Guide.max().10.misc. high : scalar Scale max value to high.0.min(). Returns : nd_array : The array obtained by reading image. cmin : Scalar Bias scaling of small values. ﬂatten : bool If true. cmax : scalar Bias scaling of large values. ﬂatten : bool. low=0) Byte scales an array (image).dev6665 Parameters im : PIL image Input image. high=255.

3.imrotate(arr. dtype=uint8) 84. 4.91433048. Miscellaneous routines (scipy. 3.5873488 ]]) scipy. [140. interp : str. 70]].SciPy Reference Guide. 188. [180. Parameters arr : nd_array Input array of image to be rotated. size.88878881].4221549 ]. 81.Percentage of current size. [155. ‘bilinear’. 100. low=100) array([[200. interp=’bilinear’) Rotate an image counter-clockwise by angle degrees. 4]. 135. 192]. interp=’bilinear’.misc) 335 .88003259. >>> bytescale(img) array([[255. • ﬂoat . Parameters arr : nd_array The array of image to be resized. [ 51. ‘bicubic’ or ‘cubic’) mode : : 3. size : int.53875334. 28]]. 236]. 80. mode=None) Resize an image.06794177. 27. interp : string interpolation to use for re-sizing (‘nearest’. dtype=uint8) >>> bytescale(img. Notes Interpolation methods can be: * ‘nearest’ : for nearest neighbor * ‘bilinear’ : for bilinear * ‘cubic’ : cubic * ‘bicubic’ : for bicubic scipy. [52. • tuple . high=200.Fraction of current size.dev6665 Examples >>> img = array([[ 91. [205. 128]]. 34. [ 73. 34. angle : ﬂoat The angle of rotation. 102]. 5]. dtype=uint8) >>> bytescale(img. 84]. cmax=255) array([[91.misc. [74. cmin=0.0. 225.misc.10. 0. Release 0. optional Interpolation Returns : nd_array : The rotated array of image.39058326.45808177.imresize(arr.9. angle.Size of the output image. 90. ﬂoat or tuple • int .

Parameters arr : ndarray Array of image data to show. Raises ValueError : Unknown ﬁlter type. Legal values are: ‘blur’. ‘edge_enhance’. ‘contour’. otherwise exact long integer is computed.pilutil. If the ﬁlter you are trying to apply is unsupported. or if that is not deﬁned then see. scipy. ftype : str The ﬁlter that has to be applied.misc.10. ‘detail’.dev6665 mode is the PIL image mode (‘P’. to view a temporary ﬁle generated from array data. the return value is 0.tile(np.imshow(arr) Simple showing of an image through an external viewer.factorial(n. Arrays are only supported with exact set to False. •Array argument accepted only for exact=0 case. then ﬂoating point precision is used.) Returns : nd_array : The resized array of image. the return value is 0. If exact is 0. n! = special. ‘sharpen’. ‘smooth’.misc. Returns None : Examples >>> a = np. 336 Chapter 3. ‘emboss’. Uses the image viewer speciﬁed by the environment variable SCIPY_PIL_IMAGE_VIEWER.gamma(n+1).misc.arange(255). ‘L’. Parameters arr : ndarray The array of Image in which the ﬁlter is to be applied. . Parameters n : int or array_like of ints Calculate n!. Reference .SciPy Reference Guide. ‘smooth_more’. ftype) Simple ﬁltering of an image. etc. scipy. ‘ﬁnd_edges’. (255. exact=0) The factorial function.0. Returns res : nd_array The array with ﬁlter applied. If n < 0.imshow(a) scipy. •If n<0.1)) >>> from scipy import misc >>> misc. ‘edge_enhance_more’.imfilter(arr. Release 0.

7!! numerically as: = 7 * 5 * 3 * 1. exact=1) n(!!.array([3. array_like Calculate multifactorial. calculate the answer exactly using integer arithmetic.misc. Miscellaneous routines (scipy.4. exact=True) 105L scipy.. exact : bool.factorial2(n. exact=True) 120L scipy.misc) 337 . as an integer or a ﬂoat depending on exact. exact=False) array([ 6.!) = multifactorial of order k k times Parameters n : int. the return value is 0. as an int or a ﬂoat depending on exact.factorial(5.0.00000000000001) >>> factorial2(7.. This is the factorial with every second value skipped. Release 0. Returns nf : ﬂoat or int Factorial of n. If n < 0.SciPy Reference Guide. exact : bool. optional The result can be approximated rapidly using the gamma-formula above (default). 3.9.e.gamma(n/2+1)*2**((m+1)/2)/sqrt(pi) = 2**(n/2) * (n/2)! Parameters n : int or array_like Calculate n!!. optional If exact is set to True. If exact is set to True.10. Default is False. 24.. Arrays are only supported with exact set to False.misc. exact=False) Double factorial. If n < 0.dev6665 exact : bool. Arrays are only supported with exact set to False. calculate the answer exactly using integer arithmetic.factorialk(n. optional The result can be approximated rapidly using the gamma-formula above. k. It can be approximated n odd n even n!! = special. Examples >>> arr = np.]) >>> sc.factorial(arr. If exact is set to True. calculate the answer exactly using integer arithmetic.. the return value is 0. Examples >>> factorial2(7.5]) >>> sc. Returns nff : ﬂoat or int Double factorial of n. i. exact=False) array(105. 120..

.misc.array([10. 210.factorialk(5. 4]) >>> n = np. Release 0. Notes •Array arguments accepted only for exact=0 case. N < 0.]) >>> sc.factorialk(5. exact=0) The number of combinations of N things taken k at a time. k. •If k > N.dev6665 Returns val : int Multi factorial of n. Returns val : int..comb(n. 338 Chapter 3. exact=False) array([ 120..comb(N. Raises NotImplementedError : Raises when exact is False Examples >>> sc. exact=True) 120L scipy. array The total number of combinations. Examples >>> k = np. then ﬂoating point precision is used. exact=True) 120L >>> sc. Reference . array Number of elements taken. then derivative is w[0] * f(x-ho*dx) + .comb(10.array([3. If weights are in the vector w.misc. array Number of things. + w[-1] * f(x+h0*dx) Notes Can be inaccurate for large number of points. k : int. or k < 0. exact=True) 10L scipy. 3. 10]) >>> sc.0. This is often expressed as “N choose k”. exact : int.10. then a 0 is returned. Parameters N : int. k. optional If exact is 0. 1. ndiv=1) Return weights for an Np-point central derivative of order ndiv assuming equally-spaced function points. 3. otherwise exact long integer is computed.SciPy Reference Guide.central_diff_weights(Np.

SciPy Reference Guide. dx=1. n=1. Parameters None : Returns lena : ndarray Lena image Examples >>> import scipy. dx : int. 512 x 512 size. Release 0. Notes Decreasing the step size too small can result in round-off error. x0 : ﬂoat The point at which nth derivative is found.9.0. Default is 1. Miscellaneous routines (scipy. 512) >>> lena. m) Given Taylor series coefﬁcients in an.misc.lena() >>> lena.dev6665 scipy. optional Number of points to use. Given a function.0 scipy.derivative(func.misc >>> lena = scipy.pade(an.0.. Parameters func : function Input function. return x*x . n : int. args : tuple.misc) 339 . 2) 4. optional Spacing. scipy. optional Order of the derivative. Lena. use a central difference formula with spacing dx to compute the n-th derivative at x0.. return a Pade approximation to the function as the ratio of two polynomials p / q where the order of q is m.shape (512. Examples >>> def x2(x): . must be odd.max() 245 3.misc.misc. >>> derivative(x2.. args=().. order=3) Find the n-th derivative of a function at point x0. optional Arguments order : int.10.lena() Get classic image processing example image.misc. x0. at 8-bit grayscale bit-depth.

Reference . Release 0.dtype dtype(’int32’) >>> >>> >>> >>> import matplotlib.ndimage) Functions for multi-dimensional image processing.gray() plt.dev6665 >>> lena.imshow(lena) plt.SciPy Reference Guide.show() 0 100 200 300 400 500 0 100 200 300 400 500 3.0. 340 Chapter 3.10 Multi-dimensional image processing (scipy.pyplot as plt plt.10.

. footprint. ﬁlter_size) generic_gradient_magnitude(input. . function[. Calculate a multidimensional gradient magnitude using gaussian sigma[.. size.. Calculate a one-dimensional ﬁlter along the given axis.. mode.... rank[..]) One-dimensional Gaussian ﬁlter. output. footprint. Calculates a multi-dimensional rank ﬁlter. axis.... Calculates a multi-dimensional ﬁlter using the given function. mode.filters. cval]) rank_filter(input..]) gaussian_filter(input. size... Multi-dimensional convolution. axis.. Calculates a multi-dimensional median ﬁlter. size.]) percentile_filter(input.]) uniform_filter1d(input. mode.. . output. footprint. . cval=0. mode=’reﬂect’. size. axis... weights[. Calculates a multi-dimensional percentile ﬁlter.. Calculate a one-dimensional maximum ﬁlter along the given axis.. Multi-dimensional correlation. gaussian_filter1d(input.]) minimum_filter1d(input. Calculate a one-dimensional minimum ﬁlter along the given axis.]) correlate(input. mode. 3. laplace(input[. origin=0) Multi-dimensional convolution.]) prewitt(input[.]) sobel(input[. Calculate a one-dimensional uniform ﬁlter along the given axis.. . Release 0. size[. .. sigma[. Calculate a Sobel ﬁlter.]) correlate1d(input..]) scipy.ndimage. axis. cval]) uniform_filter(input[. sigma[. sigma[. size. .convolve(input. mode... output. . .SciPy Reference Guide.]) maximum_filter1d(input. Calculate a one-dimensional convolution along the given axis.]) Calculates a multi-dimensional minimum ﬁlter.]) median_filter(input[.. . output.. size[. . generic_laplace(input.10.. axis.]) gaussian_gradient_magnitude(input. generic_filter(input.. Calculate a gradient magnitude using the provided function for the derivative) gradient. size. weights[.1 Filters scipy..0. output. weights. mode. minimum_filter(input[. . cval]) Calculate a multidimensional laplace ﬁlter using an estimation for the second derivative based on differences. axis.filters convolve(input. Calculate a Prewitt ﬁlter. Multi-dimensional uniform ﬁlter. size.. Calculate a one-dimensional correlation along the given axis.. output=None.]) derivatives. footprint.ndimage) 341 . weights[. function.. order. size[. . weights[. .0. . percentile[. output.dev6665 3.... Calculates a multi-dimensional maximum ﬁlter.ndimage.... Multi-dimensional Gaussian ﬁlter. output. Calculate a multidimensional laplace ﬁlter using gaussian second output.10.]) generic_filter1d(input. output. . . axis. Multi-dimensional image processing (scipy. axis. maximum_filter(input[.]) convolve1d(input. gaussian_laplace(input. .]) derivative function. .10. Calculate a multidimensional laplace ﬁlter using the provided second derivative2[.]) derivatives.

weights : array_like Array of weights. Default is 0. k.10. . where the weights kernel. cval=0. j is the n-D spatial index over W .0. Default is ‘reﬂect’. 7]. cval : scalar. [10. 12. 0. optional The origin parameter controls the placement of the ﬁlter. 11.’nearest’.. cval=0. Reference . optional The output parameter passes an array in which to store the ﬁlter output. where W is the weights kernel.0’s (and then extracting only the original region of the result). 4]. . Default is 0. mode=’constant’. 0.convolve(a.0) array([[11. 3. 2. Parameters input : array_like Input array to ﬁlter. 0]]) >>> b = np. optional Value to ﬁll past edges of input if mode is ‘constant’. Returns result : ndarray The result of convolution of input with weights.. 0]. 0.. mode : {‘reﬂect’.0 origin : scalar.array([[1. 4]. Release 0. 0.[1. 3. >>> a = np. speciﬁed by origin in the input parameters. 3.1.’mirror’.. 7]. [12. same number of dimensions as input output : ndarray..e. 7.SciPy Reference Guide. [0. Notes Each value in result is Ci = j Ii+j−k Wj . I is the input and k is the coordinate of the center of W.dev6665 The array is convolved with the given kernel. 342 Chapter 3.[1.0 is equivalent to padding the outer edge of input with 1. [9. ‘wrap’}..1.array([[1. [5.’constant’. values beyond borders are set to be cval. [15.0. 14. 10. . Examples Perhaps the simplest case to understand is mode=’constant’..1]. 11].0]]) >>> from scipy import ndimage >>> ndimage..0. 7. extends beyond an edge of input. centered on any one value.0]. optional the mode parameter determines how the array borders are handled. 3. 0]]) Setting cval=1.. For ‘constant’ mode. because in this case borders (i. See Also: correlate Correlate an image with a kernel. 0.

0]. [0. [1. axis=-1. Parameters input : array-like input array to ﬁlter weights : ndarray one-dimensional sequence of numbers axis : integer.array([[0.1. 0]]) With mode=’nearest’. 3.array([[2. 0. 14. 2. [0.SciPy Reference Guide.[0.[0.0]. cval=0. 6.convolve(a. [0. [1. optional axis of input along which to calculate.1. the single nearest value in to an edge in input is repeated as many times as needed to match the overlapping weights. [0. 2.0]. 0]. k. >>> c = np.0]]) array([[5. 3. 0. Default is -1 output : array.dev6665 >>> ndimage.0. [5. outer values are reﬂected at the edge of input to ﬁll in missing values.1. 0. 0. 12. 0]. [3. 0.[0. origin=0) Calculate a one-dimensional convolution along the given axis. 1. [11. 8. 3]. >>> b = np. 1.0.0. 0]. 0. 0]. 0]. [1. weights. [1. 11. cval=1. >>> k = np.convolve(c. 0]. mode=’reﬂect’.ndimage) 343 . optional The output parameter passes an array in which to store the ﬁlter output. 0. 0]]) >>> k = np.[0. 1. 0]. mode=’nearest’) array([[7. output=None. 0.filters. [15. mode=’constant’. 1. k) array([[4.1.10. 1]. 0]]) This includes diagonally at the corners. 0].0) array([[13. k.array([[1. 1]]) scipy.0.0]. 0. 1. Release 0. [0. [0. 0]. 0. 0. 14]. 0]. [3. 5]]) With mode=’reflect’ (the default).1]]) >>> ndimage.array([[0.convolve(b. [16.0].ndimage. 10]. 10. 0]]) >>> ndimage. The lines of the array along the given axis are convolved with the given weights.10. 0]]) >>> k = np. 2]. 0. [3. 7].array([[2. 1.convolve1d(input. 11. Multi-dimensional image processing (scipy.

optional Value to ﬁll past edges of input if mode is ‘constant’. origin=0) Multi-dimensional correlation. Release 0.dev6665 mode : {‘reﬂect’. ‘wrap’}.SciPy Reference Guide.ndimage. mode : {‘reﬂect’. origin=0) Calculate a one-dimensional correlation along the given axis.’mirror’.0. Default is 0. optional Value to ﬁll past edges of input if mode is ‘constant’. weights. Default is -1 344 Chapter 3. optional The ‘‘origin‘‘ parameter controls the placement of the ﬁlter. Parameters input : array-like input array to ﬁlter weights : ndarray array of weights.correlate1d(input.filters. optional The origin parameter controls the placement of the ﬁlter. output=None. scipy.10.’constant’. mode=’reﬂect’. where cval is the value when mode is equal to ‘constant’. The lines of the array along the given axis are correlated with the given weights. Default is 0. optional The mode parameter determines how the array borders are handled. Default 0 : scipy.’mirror’.0 origin : scalar.’constant’. Default is ‘reﬂect’ cval : scalar. Reference . Default 0 See Also: convolve Convolve an image with a kernel.ndimage.0. output=None. weights. optional axis of input along which to calculate. same number of dimensions as input output : array. axis=-1. optional The output parameter passes an array in which to store the ﬁlter output. Parameters input : array-like input array to ﬁlter weights : array one-dimensional sequence of numbers axis : integer.0.filters. optional The mode parameter determines how the array borders are handled. mode=’reﬂect’. cval=0. ‘wrap’}.correlate(input. cval=0. Default is ‘reﬂect’ cval : scalar.0 origin : scalar. The array is correlated with the given kernel.’nearest’. where cval is the value when mode is equal to ‘constant’.’nearest’.

3} or sequence from same set. order=0.gaussian_filter1d(input.0) Multi-dimensional Gaussian ﬁlter. optional Value to ﬁll past edges of input if mode is ‘constant’. axis=-1. sigma. 2. mode=’reﬂect’. cval=0. optional Value to ﬁll past edges of input if mode is ‘constant’. or as a single number.0 Notes The multi-dimensional ﬁlter is implemented as a sequence of one-dimensional convolution ﬁlters. mode : {‘reﬂect’. optional The order of the ﬁlter along each axis is given as a sequence of integers. output=None.’constant’. Default is ‘reﬂect’ cval : scalar.0 origin : scalar. mode=’reﬂect’. Release 0. where cval is the value when mode is equal to ‘constant’. sigma.10. Parameters input : array-like input array to ﬁlter 3. cval=0. Default is ‘reﬂect’ cval : scalar.dev6665 output : array.0. Default is 0. 1. Parameters input : array-like input array to ﬁlter sigma : scalar or sequence of scalars standard deviation for Gaussian kernel. optional The mode parameter determines how the array borders are handled.ndimage) 345 . mode : {‘reﬂect’.’mirror’. ‘wrap’}. optional The mode parameter determines how the array borders are handled. order : {0. optional The ‘‘origin‘‘ parameter controls the placement of the ﬁlter. An order of 0 corresponds to convolution with a Gaussian kernel. An order of 1. 2.’mirror’. where cval is the value when mode is equal to ‘constant’. Higher order derivatives are not implemented output : array. The intermediate arrays are stored in the same data type as the output. or as a single number.ndimage. the results may be imprecise because intermediate results may be stored with insufﬁcient precision. Default 0 : scipy.ndimage.’nearest’.SciPy Reference Guide. or 3 corresponds to convolution with the ﬁrst.gaussian_filter(input. output=None. in which case it is equal for all axes.’constant’.filters. second or third derivatives of a Gaussian.0) One-dimensional Gaussian ﬁlter. for output types with a limited precision. Therefore. The standard deviations of the Gaussian ﬁlter are given for each axis as a sequence. scipy.filters. optional The output parameter passes an array in which to store the ﬁlter output.10. ‘wrap’}. Default is 0. order=0.’nearest’. optional The output parameter passes an array in which to store the ﬁlter output. Multi-dimensional image processing (scipy.

in which case it is equal for all axes. optional The mode parameter determines how the array borders are handled. or as a single number.gaussian_laplace(input. Parameters input : array-like input array to ﬁlter sigma : scalar or sequence of scalars The standard deviations of the Gaussian ﬁlter are given for each axis as a sequence. cval=0. 3}. mode=’reﬂect’. where cval is the value when mode is equal to ‘constant’.’nearest’. optional The output parameter passes an array in which to store the ﬁlter output..0 scipy. Higher order derivatives are not implemented output : array. Reference .’mirror’. output=None.’nearest’. Default is ‘reﬂect’ cval : scalar. output : array.’constant’. Default is -1 order : {0. optional An order of 0 corresponds to convolution with a Gaussian kernel.0. 2.. Parameters input : array-like input array to ﬁlter sigma : scalar or sequence of scalars The standard deviations of the Gaussian ﬁlter are given for each axis as a sequence.gaussian_gradient_magnitude(input. ‘wrap’}.’constant’. Default is ‘reﬂect’ cval : scalar. where cval is the value when mode is equal to ‘constant’. cval=0. optional Value to ﬁll past edges of input if mode is ‘constant’. Default is 0. or 3 corresponds to convolution with the ﬁrst.dev6665 sigma : scalar standard deviation for Gaussian kernel axis : integer. ‘wrap’}. An order of 1. 346 Chapter 3. optional Value to ﬁll past edges of input if mode is ‘constant’.filters.10. output=None.SciPy Reference Guide. sigma. second or third derivatives of a Gaussian. optional axis of input along which to calculate. mode=’reﬂect’.0) Calculate a multidimensional laplace ﬁlter using gaussian second derivatives.’mirror’. optional The output parameter passes an array in which to store the ﬁlter output.ndimage. mode : {‘reﬂect’. sigma. mode : {‘reﬂect’.ndimage. 1.0 scipy. Default is 0. Release 0.filters. optional The mode parameter determines how the array borders are handled. 2.0) Calculate a multidimensional gradient magnitude using gaussian derivatives. or as a single number. in which case it is equal for all axes.

At each element the provided function is called.10).0.’nearest’.0 origin : scalar. optional The output parameter passes an array in which to store the ﬁlter output. but also which of the elements within this shape will get passed to the ﬁlter function.m)). extra_keywords=None) Calculates a multi-dimensional ﬁlter using the given function.’constant’. optional dict of extra keyword arguments to pass to passed function 3.m) is equivalent to footprint=np.10. optional See footprint. Multi-dimensional image processing (scipy. ‘wrap’}. extra_arguments=(). optional Value to ﬁll past edges of input if mode is ‘constant’. optional The mode parameter determines how the array borders are handled. optional The mode parameter determines how the array borders are handled. ‘wrap’}.0 scipy. cval=0.’nearest’. size=None. mode=’reﬂect’. optional Sequence of extra positional arguments to pass to passed function extra_keywords : dict. origin=0.’mirror’. and size is 2.0. Default is ‘reﬂect’ cval : scalar. footprint=None. if the input array is shape (10. We adjust size to the number of dimensions of the input array.ones((n. optional Value to ﬁll past edges of input if mode is ‘constant’.filters. optional The output parameter passes an array in which to store the ﬁlter output. Parameters input : array-like input array to ﬁlter function : callable function to apply at each element size : scalar or tuple. Thus size=(n. so that. Default is 0. below footprint : array.2). to deﬁne the input to the ﬁlter function. where cval is the value when mode is equal to ‘constant’.generic_filter(input.ndimage. Default is 0. footprint is a boolean array that speciﬁes (implicitly) a shape.SciPy Reference Guide. output : array.’constant’. Release 0. mode : {‘reﬂect’. then the actual size used is (2.dev6665 output : array.2. optional Either size or footprint must be deﬁned.’mirror’.ndimage) 347 . The input values within the ﬁlter footprint at that element are passed to the function as a 1D array of double values. size gives the shape that is taken from the input array. where cval is the value when mode is equal to ‘constant’. function.10. Default is ‘reﬂect’ cval : scalar. mode : {‘reﬂect’.10. optional The ‘‘origin‘‘ parameter controls the placement of the ﬁlter. output=None. Default 0 : extra_arguments : sequence. at every element position.

‘wrap’}. generic_ﬁlter1d iterates over the lines of the array. and the output line.SciPy Reference Guide. extra_keywords=None) Calculate a gradient magnitude using the provided function for the gradient.generic_filter1d(input.’mirror’. mode=’reﬂect’. optional Value to ﬁll past edges of input if mode is ‘constant’. output=None.ndimage.’constant’. Parameters input : array-like input array to ﬁlter derivative : callable Callable with the following signature:: 348 Chapter 3. cval=0. optional Sequence of extra positional arguments to pass to passed function extra_keywords : dict. mode : {‘reﬂect’. calling the given function at each line. The input and output lines are 1D double arrays. Default is 0. output=None. optional dict of extra keyword arguments to pass to passed function scipy. Parameters input : array-like input array to ﬁlter function : callable function to apply along given axis ﬁlter_size : scalar length of the ﬁlter axis : integer.ndimage.filters. mode=’reﬂect’. Default is ‘reﬂect’ cval : scalar. function. origin=0.dev6665 scipy. optional The ‘‘origin‘‘ parameter controls the placement of the ﬁlter. derivative.filters. extra_keywords=None) Calculate a one-dimensional ﬁlter along the given axis. The output line must be modiﬁed in-place with the result. optional The output parameter passes an array in which to store the ﬁlter output.’nearest’. optional axis of input along which to calculate. optional The mode parameter determines how the array borders are handled.0 origin : scalar. Default 0 : extra_arguments : sequence. cval=0.0.0. Default is -1 output : array.0. axis=-1. The arguments of the line are the input line. where cval is the value when mode is equal to ‘constant’. ﬁlter_size. Release 0. extra_arguments=().10. extra_arguments=(). The input line is extended appropriately according to the ﬁlter size and origin.generic_gradient_magnitude(input. Reference .

output : array. mode : {‘reﬂect’.’nearest’.SciPy Reference Guide. extra_keywords=None) Calculate a multidimensional laplace ﬁlter using the provided second derivative function. optional Sequence of extra positional arguments to pass to passed function scipy.ndimage) 349 . Default is ‘reﬂect’ cval : scalar.’constant’. optional The output parameter passes an array in which to store the ﬁlter output. *extra_arguments.10. Default is 0. axis. optional dict of extra keyword arguments to pass to passed function extra_arguments : sequence. output. optional dict of extra keyword arguments to pass to passed function extra_arguments : sequence. cval. Release 0. output=None. Note that the output from derivative is modiﬁed inplace. where cval is the value when mode is equal to ‘constant’.’mirror’. Multi-dimensional image processing (scipy. where cval is the value when mode is equal to ‘constant’. extra_keywords below output : array. cval.dev6665 derivative(input. optional Value to ﬁll past edges of input if mode is ‘constant’. mode. optional The mode parameter determines how the array borders are handled. derivative2. be careful to copy important inputs before returning them. Parameters input : array-like input array to ﬁlter derivative2 : callable Callable with the following signature:: derivative2(input.’nearest’. optional Value to ﬁll past edges of input if mode is ‘constant’. ‘wrap’}. optional Sequence of extra positional arguments to pass to passed function 3. Default is 0. optional The mode parameter determines how the array borders are handled.0.0 extra_keywords : dict. *extra_arguments. extra_arguments=(). mode : {‘reﬂect’.ndimage.generic_laplace(input.’mirror’.0. ‘wrap’}. extra_keywords below derivative can assume that input and output are ndarrays. axis. optional The output parameter passes an array in which to store the ﬁlter output. **extra_keywords) See extra_arguments. cval=0. Default is ‘reﬂect’ cval : scalar. mode. **extra_keywords) See extra_arguments.0 extra_keywords : dict.’constant’.filters. mode=’reﬂect’.10. output.

at every element position. cval=0.0 origin : scalar.’mirror’.m)).’nearest’. Release 0.10. Default is 0. then the actual size used is (2. output=None. below footprint : array. to deﬁne the input to the ﬁlter function. optional The output parameter passes an array in which to store the ﬁlter output. if the input array is shape (10. origin=0) Calculates a multi-dimensional maximum ﬁlter.ndimage. cval=0. mode=’reﬂect’.filters. where cval is the value when mode is equal to ‘constant’.2).ndimage.10). 350 Chapter 3.2. ‘wrap’}.filters.0) Calculate a multidimensional laplace ﬁlter using an estimation for the second derivative based on differences.10. size. optional The mode parameter determines how the array borders are handled. cval=0. ‘wrap’}. Parameters input : array-like input array to ﬁlter size : scalar or tuple. mode : {‘reﬂect’. output=None. Default 0 : scipy. size gives the shape that is taken from the input array.’nearest’.0. axis=-1.’mirror’. output=None. Reference .0.ndimage. Default is 0. optional Value to ﬁll past edges of input if mode is ‘constant’.’constant’. optional The output parameter passes an array in which to store the ﬁlter output.0 scipy.dev6665 scipy.m) is equivalent to footprint=np.laplace(input.’constant’. We adjust size to the number of dimensions of the input array. optional See footprint.filters. optional The mode parameter determines how the array borders are handled.0. Parameters input : array-like input array to ﬁlter output : array.maximum_filter1d(input.maximum_filter(input. optional Either size or footprint must be deﬁned. where cval is the value when mode is equal to ‘constant’. Default is ‘reﬂect’ cval : scalar. mode=’reﬂect’. output : array. optional Value to ﬁll past edges of input if mode is ‘constant’. optional The ‘‘origin‘‘ parameter controls the placement of the ﬁlter. size=None. origin=0) Calculate a one-dimensional maximum ﬁlter along the given axis.ones((n. The lines of the array along the given axis are ﬁltered with a maximum ﬁlter of given size. mode=’reﬂect’.SciPy Reference Guide. footprint=None. so that. and size is 2. Default is ‘reﬂect’ cval : scalar. mode : {‘reﬂect’. but also which of the elements within this shape will get passed to the ﬁlter function. Thus size=(n. footprint is a boolean array that speciﬁes (implicitly) a shape.

0 origin : scalar. Default is -1 output : array.’nearest’. footprint is a boolean array that speciﬁes (implicitly) a shape. optional The mode parameter determines how the array borders are handled.m) is equivalent to footprint=np. Default is ‘reﬂect’ cval : scalar.10. Release 0. where cval is the value when mode is equal to ‘constant’. footprint=None. where cval is the value when mode is equal to ‘constant’. if the input array is shape (10. mode : {‘reﬂect’.’mirror’. cval=0. Default is 0. optional output=None. optional Value to ﬁll past edges of input if mode is ‘constant’. ‘wrap’}.m)). origin=0) Calculates a multi-dimensional median ﬁlter.’constant’. Multi-dimensional image processing (scipy.SciPy Reference Guide. size=None. optional Either size or footprint must be deﬁned. optional The output parameter passes an array in which to store the ﬁlter output. Parameters input : array-like input array to ﬁlter size : scalar or tuple.0. ‘wrap’}. optional Value to ﬁll past edges of input if mode is ‘constant’. Default 0 : scipy. at every element position.ones((n.10). Thus size=(n.10.0 origin : scalar. output : array.filters. optional The mode parameter determines how the array borders are handled. below footprint : array. to deﬁne the input to the ﬁlter function. optional The output parameter passes an array in which to store the ﬁlter output.2. Default is ‘reﬂect’ cval : scalar.2). optional axis of input along which to calculate.’nearest’.median_filter(input.ndimage) 351 .’constant’. size gives the shape that is taken from the input array. Default is 0.’mirror’. We adjust size to the number of dimensions of the input array.dev6665 Parameters input : array-like input array to ﬁlter size : int length along which to calculate 1D maximum axis : integer. optional See footprint. mode : {‘reﬂect’.0. then the actual size used is (2. optional The ‘‘origin‘‘ parameter controls the placement of the ﬁlter. 3. mode=’reﬂect’. so that. and size is 2. but also which of the elements within this shape will get passed to the ﬁlter function.10.ndimage.

cval=0. below footprint : array. and size is 2. Parameters input : array-like input array to ﬁlter size : scalar or tuple. Thus size=(n.0 origin : scalar.2. cval=0.’mirror’.0. where cval is the value when mode is equal to ‘constant’. Reference . mode=’reﬂect’.’constant’. Default 0 : scipy. Parameters input : array-like input array to ﬁlter size : int length along which to calculate 1D minimum axis : integer.2). Release 0.0. mode : {‘reﬂect’. size. origin=0) Calculates a multi-dimensional minimum ﬁlter.ndimage. footprint is a boolean array that speciﬁes (implicitly) a shape. optional axis of input along which to calculate. Default is 0. ‘wrap’}. size gives the shape that is taken from the input array. origin=0) Calculate a one-dimensional minimum ﬁlter along the given axis. optional See footprint. Default is -1 output : array.ndimage. mode=’reﬂect’. output=None. at every element position. optional Either size or footprint must be deﬁned.m)).10.’nearest’.10.minimum_filter(input.ones((n. Default 0 scipy.0. Default is ‘reﬂect’ cval : scalar. optional The output parameter passes an array in which to store the ﬁlter output. optional The mode parameter determines how the array borders are handled.m) is equivalent to footprint=np. 352 Chapter 3. optional Value to ﬁll past edges of input if mode is ‘constant’. to deﬁne the input to the ﬁlter function. optional output=None.filters.dev6665 The origin parameter controls the placement of the ﬁlter. The lines of the array along the given axis are ﬁltered with a minimum ﬁlter of given size. so that. We adjust size to the number of dimensions of the input array. if the input array is shape (10. optional The ‘‘origin‘‘ parameter controls the placement of the ﬁlter. then the actual size used is (2.’mirror’.10). size=None. ‘wrap’}. output : array. but also which of the elements within this shape will get passed to the ﬁlter function.minimum_filter1d(input. axis=-1.’constant’. mode : {‘reﬂect’.’nearest’.filters. optional The output parameter passes an array in which to store the ﬁlter output.SciPy Reference Guide. footprint=None.

size=None. Default 0 : scipy. optional The mode parameter determines how the array borders are handled. optional The output parameter passes an array in which to store the ﬁlter output.’nearest’.2).. optional axis of input along which to calculate. optional Value to ﬁll past edges of input if mode is ‘constant’.0. Default is ‘reﬂect’ cval : scalar. Default is 0.m)). ‘wrap’}. i. then the actual size used is (2. optional Either size or footprint must be deﬁned. axis=-1.ones((n.0) Calculate a Prewitt ﬁlter. footprint=None. so that. optional Value to ﬁll past edges of input if mode is ‘constant’. Thus size=(n.ndimage. cval=0.’mirror’.10.prewitt(input.2. below footprint : array.’constant’.0 origin : scalar. Default is -1 3. Default is ‘reﬂect’ cval : scalar.SciPy Reference Guide. percentile. size gives the shape that is taken from the input array.ndimage) 353 .10). to deﬁne the input to the ﬁlter function. Release 0. output=None. where cval is the value when mode is equal to ‘constant’. Default is 0. mode=’reﬂect’. origin=0) Calculates a multi-dimensional percentile ﬁlter. and size is 2.ndimage.0 origin : scalar. percentile = -20 equals percentile = 80 size : scalar or tuple. cval=0. optional The ‘‘origin‘‘ parameter controls the placement of the ﬁlter. footprint is a boolean array that speciﬁes (implicitly) a shape. where cval is the value when mode is equal to ‘constant’. output=None. output : array.filters.filters.percentile_filter(input. mode=’reﬂect’. We adjust size to the number of dimensions of the input array.m) is equivalent to footprint=np. optional The ‘‘origin‘‘ parameter controls the placement of the ﬁlter.dev6665 The mode parameter determines how the array borders are handled. Parameters input : array-like input array to ﬁlter percentile : scalar The percentile parameter may be less then zero. Multi-dimensional image processing (scipy. Default 0 : scipy. but also which of the elements within this shape will get passed to the ﬁlter function. if the input array is shape (10. Parameters input : array-like input array to ﬁlter axis : integer.10. at every element position.10.e. optional See footprint.0. mode : {‘reﬂect’.

but also which of the elements within this shape will get passed to the ﬁlter function. mode : {‘reﬂect’. rank = -1 indicates the largest element. optional The output parameter passes an array in which to store the ﬁlter output. ‘wrap’}. size : scalar or tuple.’constant’.0 origin : scalar.10). Thus size=(n. optional 354 Chapter 3. Parameters input : array-like input array to ﬁlter axis : integer. axis=-1. mode=’reﬂect’.rank_filter(input. Default is 0. Release 0. optional Value to ﬁll past edges of input if mode is ‘constant’. Default is 0. origin=0) Calculates a multi-dimensional rank ﬁlter.10.dev6665 output : array. optional The ‘‘origin‘‘ parameter controls the placement of the ﬁlter. size=None.’constant’. ‘wrap’}.0. then the actual size used is (2.’mirror’.e. cval=0. optional The output parameter passes an array in which to store the ﬁlter output.ndimage. to deﬁne the input to the ﬁlter function. optional The mode parameter determines how the array borders are handled. output=None. Default is ‘reﬂect’ cval : scalar. Default 0 : scipy. and size is 2.sobel(input.2).0) Calculate a Sobel ﬁlter. rank. at every element position. where cval is the value when mode is equal to ‘constant’.SciPy Reference Guide. footprint is a boolean array that speciﬁes (implicitly) a shape. optional Either size or footprint must be deﬁned.0. Parameters input : array-like input array to ﬁlter rank : integer The rank parameter may be less then zero. Reference . cval=0.ones((n. where cval is the value when mode is equal to ‘constant’. mode=’reﬂect’. output=None.’nearest’.2. We adjust size to the number of dimensions of the input array. footprint=None. optional See footprint. i. size gives the shape that is taken from the input array.m)).’nearest’. mode : {‘reﬂect’.filters. so that. optional Value to ﬁll past edges of input if mode is ‘constant’. Default is ‘reﬂect’ cval : scalar.. below footprint : array.’mirror’.ndimage.filters. if the input array is shape (10. output : array. optional The mode parameter determines how the array borders are handled.m) is equivalent to footprint=np.10.0 scipy.

output=None. output=None.ndimage. Release 0. optional 3.’mirror’. Default is ‘reﬂect’ cval : scalar. scipy.ndimage) 355 . cval=0. ‘wrap’}. where cval is the value when mode is equal to ‘constant’. origin=0) Multi-dimensional uniform ﬁlter.uniform_filter1d(input. The intermediate arrays are stored in the same data type as the output. mode=’reﬂect’. Default 0 : Notes The multi-dimensional ﬁlter is implemented as a sequence of one-dimensional uniform ﬁlters. Default is 0.10. optional Value to ﬁll past edges of input if mode is ‘constant’. Default is -1 output : array.0 origin : scalar. Default is ‘reﬂect’ cval : scalar.’nearest’. Default is 0. for output types with a limited precision. optional The output parameter passes an array in which to store the ﬁlter output. optional Value to ﬁll past edges of input if mode is ‘constant’.’constant’.0.0.’constant’. Parameters input : array-like input array to ﬁlter size : integer length of uniform ﬁlter axis : integer. size.0 scipy.uniform_filter(input. Multi-dimensional image processing (scipy.filters. mode : {‘reﬂect’.’mirror’. Parameters input : array-like input array to ﬁlter size : int or sequence of ints The sizes of the uniform ﬁlter are given for each axis as a sequence.10. output : array. mode=’reﬂect’. optional The output parameter passes an array in which to store the ﬁlter output. or as a single number. ‘wrap’}. Therefore. origin=0) Calculate a one-dimensional uniform ﬁlter along the given axis.filters. axis=-1. The lines of the array along the given axis are ﬁltered with a uniform ﬁlter of given size.dev6665 axis of input along which to calculate.SciPy Reference Guide. optional The mode parameter determines how the array borders are handled. in which case the size is equal for all axes. mode : {‘reﬂect’.0. optional The mode parameter determines how the array borders are handled.ndimage.’nearest’. size=3. the results may be imprecise because intermediate results may be stored with insufﬁcient precision. optional The ‘‘origin‘‘ parameter controls the placement of the ﬁlter. cval=0. where cval is the value when mode is equal to ‘constant’.

Default is ‘reﬂect’ cval : scalar. where cval is the value when mode is equal to ‘constant’. optional Value to ﬁll past edges of input if mode is ‘constant’. axis.10. If n is larger than or equal to zero. optional The axis of the real transform.ndimage. size is the same for all axes. axis. size[. n=-1. Multi-dimensional Gaussian fourier ﬁlter.fourier fourier_ellipsoid(input. ‘wrap’}. Default is 0.dev6665 axis of input along which to calculate. Parameters input : array_like The input array. the input is assumed to be the result of a real fft. output]) Multi-dimensional ellipsoid fourier ﬁlter. then the input is assumed to be the result of a complex fft. The array is multiplied with the fourier transform of a ellipsoid of given sizes. n. size has to contain one value for each axis.fourier_ellipsoid(input. Default is -1 output : array. optional If n is negative (default).2 Fourier ﬁlters scipy. n : int. Returns return_value : ndarray or None The ﬁltered input. Release 0.SciPy Reference Guide. output]) fourier_gaussian(input. If a sequence. output]) fourier_shift(input. axis. and n gives the length of the array before transformation along the real transform direction. Default 0 : 3. optional The output parameter passes an array in which to store the ﬁlter output. size : ﬂoat or sequence The size of the box used for ﬁltering. n. optional The ‘‘origin‘‘ parameter controls the placement of the ﬁlter. shift[. None is returned.0.’constant’.10. Reference . axis=-1.0 origin : scalar.fourier.’nearest’. output : ndarray. Multi-dimensional fourier shift ﬁlter. the result of ﬁltering the input is placed in this array. 356 Chapter 3. axis. size[. None is returned in this case. optional If given.ndimage. output=None) Multi-dimensional ellipsoid fourier ﬁlter. output]) fourier_uniform(input. Multi-dimensional uniform fourier ﬁlter. size. axis : int. optional The mode parameter determines how the array borders are handled. scipy. mode : {‘reﬂect’. n. If output is given as a parameter.’mirror’. n. sigma[. If a ﬂoat.

shift has to contain one value for each axis. None is returned. or 3. n : int. axis=-1.ndimage. the input is assumed to be the result of a real fft. output=None) Multi-dimensional Gaussian fourier ﬁlter. axis : int. then the input is assumed to be the result of a complex fft.dev6665 Notes This function is implemented for arrays of rank 1. shift. The array is multiplied with the fourier transform of a shift operation.ndimage. scipy. n=-1. optional If n is negative (default).fourier.fourier_gaussian(input. the result of ﬁltering the input is placed in this array. If n is larger than or equal to zero.SciPy Reference Guide. Parameters input : array_like The input array. n : int. If a ﬂoat. the input is assumed to be the result of a real fft. output : ndarray. sigma. If n is larger than or equal to zero. If a sequence. shift is the same for all axes.ndimage) 357 . shift : ﬂoat or sequence The size of the box used for ﬁltering. optional If given. and n gives the length of the array before transformation along the real transform direction.10. optional 3. and n gives the length of the array before transformation along the real transform direction. axis : int. optional If n is negative (default). scipy.10. None is returned in this case. sigma has to contain one value for each axis. Parameters input : array_like The input array. optional The axis of the real transform.fourier_shift(input. 2. Returns return_value : ndarray or None The ﬁltered input. sigma : ﬂoat or sequence The sigma of the Gaussian kernel. output=None) Multi-dimensional fourier shift ﬁlter. axis=-1. Release 0. optional The axis of the real transform.0. If a ﬂoat.fourier. If a sequence. The array is multiplied with the fourier transform of a Gaussian kernel. sigma is the same for all axes. Multi-dimensional image processing (scipy. If output is given as a parameter. n=-1. output : ndarray. then the input is assumed to be the result of a complex fft.

fourier_uniform(input. Reference . output : ndarray. . 358 Chapter 3. reshape. matrix[..affine_transform(input. the result of ﬁltering the input is placed in this array.0. Apply an arbritrary geometric transform. size : ﬂoat or sequence The size of the box used for ﬁltering. axes. coordinates[..]) map_coordinates(input. . order. If output is given as a parameter. None is returned. output=None. Map the input array to new coordinates by interpolation. offset. Returns return_value : ndarray or None The ﬁltered input. axis.. mode.. scipy.interpolation affine_transform(input. cval=0. zoom[. output.. Rotate an array. output]) zoom(input..SciPy Reference Guide..ndimage.]) spline_filter(input[. the result of shifting the input is placed in this array. Returns return_value : ndarray or None The shifted input. optional If n is negative (default)..3 Interpolation scipy. Shift an array. shift[. axis : int. .]) rotate(input. n : int.. output_shape=None. then the input is assumed to be the result of a complex fft. size has to contain one value for each axis. Calculates a one-dimensional spline ﬁlter along the given axis.]) shift(input. matrix. The array is multiplied with the fourier transform of a box of given size. optional The axis of the real transform. If a sequence. size is the same for all axes. 3.ndimage. If output is given as a parameter. order.0. If n is larger than or equal to zero. . Zoom an array. Multi-dimensional spline ﬁlter.0.]) Apply an afﬁne transformation. output]) spline_filter1d(input[. size. None is returned in this case. the input is assumed to be the result of a real fft. None is returned. . n=-1. optional If given.10. None is returned in this case. axis=-1.fourier.dev6665 If given.ndimage. preﬁlter=True) Apply an afﬁne transformation.. angle[. output. . If a ﬂoat. and n gives the length of the array before transformation along the real transform direction.. offset=0.]) geometric_transform(input. mode=’constant’. order. Release 0.10. order. scipy. mode..interpolation. mapping[. output=None) Multi-dimensional uniform fourier ﬁlter. Parameters input : array_like The input array. order=3.

extra_arguments=(). Parameters input : array_like 3. The value of the input at those coordinates is determined by spline interpolation of the requested order. The order has to be in the range 0-5. If False. optional Points outside the boundaries of the input are ﬁlled according to the given mode (‘constant’. it is assumed that the matrix is diagonal.geometric_transform(input. If output is given as a parameter.10. output_shape : tuple of ints. it is assumed that the input is already ﬁltered. matrix : ndarray The matrix must be two-dimensional or can also be given as a one-dimensional sequence or array. Returns return_value : ndarray or None The transformed input.10. offset is the same for each axis. the corresponding coordinates in the input. ‘nearest’. output=None. In the latter case. Multi-dimensional image processing (scipy. mode : str. optional The order of the spline interpolation.ndimage) 359 . If a ﬂoat. or the dtype of the returned array. preﬁlter=True.interpolation. offset : ﬂoat or sequence. extra_keywords={}) Apply an arbritrary geometric transform.0. optional The array in which to place the output.ndimage. Points outside the boundaries of the input are ﬁlled according to the given mode. None is returned. Default is 0. default is 3. The value of the input at those coordinates is determined by spline interpolation of the requested order. Parameters input : ndarray The input array. scipy. The given mapping function is used to ﬁnd. optional The parameter preﬁlter determines if the input is pre-ﬁltered with spline_ﬁlter before interpolation (necessary for spline interpolation of order > 1). mode=’constant’. output : ndarray or dtype.0 preﬁlter : bool.0. order : int. ‘reﬂect’ or ‘wrap’). If a sequence. optional The offset into the array where the transform is applied. Release 0. cval=0.SciPy Reference Guide. Default is ‘constant’. cval : scalar. A more efﬁcient algorithms is then applied that exploits the separability of the problem.dev6665 The given matrix and offset are used to ﬁnd for each point in the output the corresponding coordinates in the input by an afﬁne transformation. for each point in the output. optional Value used for points outside the boundaries of the input if mode=’constant’. mapping. offset should contain one value for each axis. optional Shape tuple. Default is True. output_shape=None. order=3.

. 1. order : int... ‘nearest’. and returns the corresponding input coordinates as a tuple of length equal to the input array rank. extra_keywords : dict.dev6665 The input array. optional Value used for points outside the boundaries of the input if mode=’constant’. If output is given as a parameter. Returns return_value : ndarray or None The ﬁltered input.187]. cval : scalar. See Also: map_coordinates.263.. 0. . 6. 9.ndimage. extra_arguments : tuple.0 preﬁlter : bool. optional The order of the spline interpolation.geometric_transform(a. >>> sp.738]. default is 3. 2. . None is returned. [ 0. shift_func) array([[ 0. 8. return (output_coords[0] . [ 0. optional Extra arguments passed to mapping. optional The parameter preﬁlter determines if the input is pre-ﬁltered with spline_ﬁlter before interpolation (necessary for spline interpolation of order > 1).SciPy Reference Guide. optional Extra keywords passed to mapping..0. The order has to be in the range 0-5.812. output_coords[1] . ].arange(12. 4. [ 0. Reference . 3)) >>> def shift_func(output_coords): . spline_filter1d Examples >>> a = np. . output_shape : tuple of ints Shape tuple. . 0.362. mode : str.637]]) 360 Chapter 3.reshape((4. optional The array in which to place the output. Release 0. affine_transform.5. it is assumed that the input is already ﬁltered. If False. or the dtype of the returned array. Default is ‘constant’. mapping : callable A callable object that accepts a tuple of length equal to the output array rank. Default is True.0. ‘reﬂect’ or ‘wrap’). Default is 0.0.5) . optional Points outside the boundaries of the input are ﬁlled according to the given mode (‘constant’.).10. output : ndarray or dtype.

. Default is 0. preﬁlter=True) Map the input array to new coordinates by interpolation. 1. 2]. optional Points outside the boundaries of the input are ﬁlled according to the given mode (‘constant’.. coordinates. If False. Default is ‘constant’. optional Value used for points outside the boundaries of the input if mode=’constant’. order=3. The array of coordinates is used to ﬁnd. output=None.. 10.]. 2. 8. [ 6. The shape of the output is derived from that of coordinates by dropping the ﬁrst axis.ndimage >>> a = np.. order : int. 7. See Also: spline_filter.. 3)) >>> a array([[ 0. 4. The order has to be in the range 0-5. Parameters input : ndarray The input array. cval=0.].5. The shape of the output is derived from that of the coordinate array by dropping the ﬁrst axis. order=1) [ 2. the corresponding coordinates in the input.map_coordinates(a. Default is True. geometric_transform.ndimage.10.5.0. [0. [ 9.10. [[0. 7. ‘nearest’.0 preﬁlter : bool. coordinates : array_like The coordinates at which input is evaluated. it is assumed that the input is already ﬁltered. mode=’constant’. 5.ndimage.0. for each point in the output. optional The order of the spline interpolation.ndimage) 361 . Release 0. 11. ‘reﬂect’ or ‘wrap’). output : ndarray or dtype.SciPy Reference Guide.reshape((4. [ 3. mode : str. Multi-dimensional image processing (scipy.]]) >>> sp.interpolation. 1]]. cval : scalar. optional The array in which to place the output.arange(12. scipy.interpolate Examples >>> import scipy.. The values of the array along the ﬁrst axis are the coordinates in the input array at which the output value is found.).dev6665 scipy.] 3. optional The parameter preﬁlter determines if the input is pre-ﬁltered with spline_ﬁlter before interpolation (necessary for spline interpolation of order > 1)..map_coordinates(input. default is 3. or the dtype of the returned array. The value of the input at those coordinates is determined by spline interpolation of the requested order. Returns return_value : ndarray The result of transforming the input..].

angle. -33.map_coordinates(a. axes : tuple of 2 ints. order=1. 1] is output[1]. output : ndarray or dtype. Default is True. angle : ﬂoat The rotation angle in degrees.ndimage. mode=’constant’. 2].interpolation.3]) >>> sp.0. optional If reshape is true. optional Value used for points outside the boundaries of the input if mode=’constant’. reshape=True. order=3.5. while a[2. Default is the ﬁrst two axes. optional The parameter preﬁlter determines if the input is pre-ﬁltered with spline_ﬁlter before interpolation (necessary for spline interpolation of order > 1).map_coordinates(a.array([[0. ‘nearest’.ndimage. If output is given as a parameter. optional The order of the spline interpolation. order=1. or the dtype of the returned array.]) >>> sp. 8. If False. cval=0. Parameters input : ndarray The input array. cval=-33.5. optional The two axes that deﬁne the plane of rotation. order : int. output=bool) array([ True.5] gives output[0].dev6665 Above. cval=0.0. output=None. Default is 0. order=1. cval : scalar.SciPy Reference Guide. . default is 3. 4]]) >>> sp. The order has to be in the range 0-5. mode=’nearest’) array([ 2.map_coordinates(a. False]. reshape : bool. Returns return_value : ndarray or None The rotated input. Default is True.10. dtype=bool scipy..ndimage. it is assumed that the input is already ﬁltered. >>> inds = np.0 preﬁlter : bool. 0. ‘reﬂect’ or ‘wrap’). None is returned. Default is ‘constant’. inds.ndimage. 0). The array is rotated in the plane deﬁned by the two axes given by the axes parameter using spline interpolation of the requested order. Release 0. mode : str. [0.rotate(input. preﬁlter=True) Rotate an array. the interpolated value of a[0. axes=(1.5. optional Points outside the boundaries of the input are ﬁlled according to the given mode (‘constant’. Reference . 362 Chapter 3. optional The array in which to place the output. inds.3) array([ 2. inds. the output shape is adapted so that the input array is contained completely in the output.

order=3.10. shift should contain one value for each axis. output : ndarray or dtype. If output is given as a parameter. shift.ndimage) 363 . optional The shift along the axes. ‘reﬂect’ or ‘wrap’).0 preﬁlter : bool. Points outside the boundaries of the input are ﬁlled according to the given mode. ‘numpy. Default is 0.0.ndimage. for output types with a limited precision. Multi-dimensional image processing (scipy. The intermediate arrays are stored in the same data type as the output.ndimage. the results may be imprecise because intermediate results may be stored with insufﬁcient precision. Release 0. output=None.dev6665 scipy. ‘numpy. cval=0.ndimage. axis=-1. Default is True. scipy. optional Points outside the boundaries of the input are ﬁlled according to the given mode (‘constant’.ﬂoat64’>) Calculates a one-dimensional spline ﬁlter along the given axis. optional The array in which to place the output. If a ﬂoat. ‘nearest’. optional The order of the spline interpolation. If a sequence. If False. Therefore.interpolation. shift is the same for each axis. Default is ‘constant’.spline_filter(input. optional Value used for points outside the boundaries of the input if mode=’constant’. output=<type output=<type 3. or the dtype of the returned array. cval : scalar.spline_filter1d(input. See Also: spline_filter1d Notes The multi-dimensional ﬁlter is implemented as a sequence of one-dimensional spline ﬁlters. preﬁlter=True) Shift an array. order=3. see spline_ﬁlter1d. mode=’constant’. None is returned.shift(input.10.interpolation. mode : str. it is assumed that the input is already ﬁltered.interpolation. For more details. The order has to be in the range 0-5. scipy. The array is shifted using spline interpolation of the requested order.SciPy Reference Guide. order : int. Returns return_value : ndarray or None The shifted input. order=3.ﬂoat64’>) Multi-dimensional spline ﬁlter. default is 3. optional The parameter preﬁlter determines if the input is pre-ﬁltered with spline_ﬁlter before interpolation (necessary for spline interpolation of order > 1).0. Parameters input : ndarray The input array. shift : ﬂoat or sequence.

cval=0. it is assumed that the input is already ﬁltered. None is returned. Default is ‘constant’. axis : int.dev6665 The lines of the array along the given axis are ﬁltered by a spline ﬁlter. or the dtype of the returned array. default is 3. Default is 0.0. or the dtype of the returned array.float64. optional The axis along which the spline ﬁlter is applied. If a sequence. If output is given as a parameter. Parameters input : ndarray The input array. optional The zoom factor along the axes. ‘reﬂect’ or ‘wrap’).SciPy Reference Guide. optional The order of the spline interpolation.ndimage. zoom. mode=’constant’. zoom should contain one value for each axis. The order of the spline must be >= 2 and <= 5. optional Points outside the boundaries of the input are ﬁlled according to the given mode (‘constant’.interpolation. Returns return_value : ndarray or None The ﬁltered input.zoom(input. Default is True. order=3. optional The parameter preﬁlter determines if the input is pre-ﬁltered with spline_ﬁlter before interpolation (necessary for spline interpolation of order > 1). ‘nearest’. The order has to be in the range 0-5. optional Value used for points outside the boundaries of the input if mode=’constant’. Release 0. Reference . cval : scalar. 364 Chapter 3. If False.0 preﬁlter : bool. optional The array in which to place the output. zoom is the same for each axis. scipy. The array is zoomed using spline interpolation of the requested order. output : ndarray or dtype. order : int. preﬁlter=True) Zoom an array. output=None. optional The array in which to place the output. mode : str. If a ﬂoat.0.10. Default is the last axis. optional The order of the spline. zoom : ﬂoat or sequence. output : ndarray or dtype. Default is numpy. order : int. default is 3. Parameters input : array_like The input array.

Examples >>> a = np. Parameters input : ndarray Data from which to calculate center-of-mass.10. index]) maximum_position(input[.0.labels.]) Calculate the center of mass of the values of an array at labels. 3.0]. index]) variance(input[. min. Calculate the variance of the values of an n-D image array. Find objects in a labeled array.1. Calculate the sum of the values of the array. [0. structure. markers[. index : int.0]. max_label]) histogram(input. scipy. labels. labels. optionally at Apply watershed from markers using a iterative forest transform algorithm.1. as generated by ndimage.10. index]) watershed_ift(input. Release 0.dev6665 Returns return_value : ndarray or None The zoomed input. index]) mean(input[. labels. Dimensions must be the same as input. labels.0. Find the positions of the maximums of the values of an array at labels. Label features in an array. index]) extrema(input[. Calculate the histogram of the values of an array. Calculate the minimums and maximums of the values of an array at labels. If not speciﬁed. labels=None. Calculate the maximum of the values of an array over labeled regions.array(([0. Multi-dimensional image processing (scipy. Calculate the standard deviation of the values of an n-D image array. all labels greater than zero are used. labels. 3.1. labels.measurements.center_of_mass(input.. bins[.ndimage.ndimage) 365 . labels. sequence of int. index]) find_objects(input[. index=None) Calculate the center of mass of the values of an array at labels.0]. index]) label(input[. index]) minimum_position(input[. Calculate the minimum of the values of an array over labeled regions.SciPy Reference Guide.. Find the positions of the minimums of the values of an array at labels. max.ndimage. along with their positions.1. [0. None is returned.0. labels. labels : ndarray or None. index]) sum(input[. labels. labels. labels. structure. optionally at labels. .measurements center_of_mass(input[. Calculate the mean of the values of an array at labels. output]) maximum(input[. index]) minimum(input[. optional Labels for objects in input. optional Labels for which to calculate centers-of-mass. or None. index]) standard_deviation(input[.4 Measurements scipy.10. Returns centerofmass : tuple. or list of tuples Co-ordinates of centers-of-masses. If output is given as a parameter.

(3. nlbl+1)) (array([1. [1. Returns minimums. 0. lbl.label(a) >>> ndimage.0. 9]). [9. 2). 0. [(1.0. 1. 3.0. must be same shape as input. 7].0.extrema(a. labels=None. If None. 0. 9.0].arange(1. 2. Parameters input : ndarray Nd-image data to process.5)] scipy.array([[1.5) Calculation of multiple objects in an image >>> b = np. [0.0. along with their positions. 3.1. (0.0]. 1. 4].ndimage.0.1. 0)) Features to process can be speciﬁed using labels and index: >>> lbl.1])) >>> lbl = ndimage.33333333333333331.1.0.0. center_of_mass Examples >>> a = np. (3.0. [0. min_positions. array([5. 3. 7. index=np.2]) [(0. int.array(([0.0)]) 366 Chapter 3. 0]. Reference . 2.0)]. index : None. 0. labels : ndarray. [5. index=None) Calculate the minimums and maximums of the values of an array at labels.0. (3.5. 3. maximums : int or ndarray Values of minimums and maximums in each feature.center_of_mass(a) (2. 0.0]. minimum.0). optional Labels to include in output.label(b)[0] >>> ndimage.SciPy Reference Guide.3333333333333333).0])) >>> from scipy import ndimage >>> ndimage. Release 0.measurements. 3]).center_of_mass(b.0).0.1. If not None. 0.0. 0. max_positions : tuple or list of tuples Each tuple gives the n-D coordinates of the corresponding minimum or maximum.measurements. (3. or sequence of int. optional Labels of features in input.1].measurements. or None.extrema(a) (0. [0. See Also: maximum. 0. nlbl = ndimage. 4. 1.1.extrema(input.0). (1. 0]]) >>> from scipy import ndimage >>> ndimage.0). [(0. (2. all values where non-zero labels are used.dev6665 [0. maximum_position. lbl. [0.1. [0. minimum_position.0.1.10.

5. 0. 4] = 1 >>> a[:2. 2. index=None) Calculate the histogram of the values of an array. [0. 1. 0]. 0)) scipy. Returns object_slices : list of slices A list of slices. non-zero labels are processed: >>> ndimage. min. If max_label is not given. 2. 0. 5. max_label : int. [0. 0. 0). Slices correspond to the minimal parallelepiped that contains the object.measurements. Examples >>> a = np. None] scipy. 5. dtype=np.zeros((6. If a number is missing. 0. 3. (slice(0. Release 0. slice(2. slice(2. None)).10. slice(0. [0.10. 0. 5. None)). None). 0. slice(2. 0. labels=None. 5. None). Labels and index can limit the scope of the histogram to speciﬁed sub-regions within the array. Multi-dimensional image processing (scipy. Parameters input : ndarray of ints Array containing objects deﬁned by different labels. 2. 0. max_label=2) [(slice(2. [2. None).ndimage) 367 . 1. center_of_mass Notes This function is very useful for isolating a volume of interest inside a 3-D array. 1.histogram(input. 0. and bins.measurements.ndimage.SciPy Reference Guide.find_objects(a == 1. 2.dev6665 If no index is given.find_objects(a) [(slice(2. None is returned instead of a slice. Parameters input : array_like 3. >>> ndimage.find_objects(input. 0. :3] = 2 >>> a[0. 0]. 3]. the positions of all objects are returned. [0. 5] = 3 >>> a array([[2. 2:4] = 1 >>> a[4. 3. slice(0. 0. Histogram calculates the frequency of values in an array within bins determined by min. 2.int) >>> a[2:4. 1. 0. that cannot be “seen through”. 0]]) >>> ndimage. 0. bins. (slice(0. 2. lbl) (1. (3. 1. 0]. max. See Also: label. None))] >>> ndimage. optional Maximum label to be searched for in input.ndimage. one for the extent of each labeled object. None). max. 0. 1. 0.0.6). None)). 0]. None). optionally at labels. (0. (slice(0. 5. max_label=2) [(slice(2.extrema(a.find_objects(a. max_label=0) Find objects in a labeled array. 9. None)).

0. [ 0. 0]) Indices can be used to count only certain objects: >>> ndimage. [ 0. 0. 2. structure=None. lbl) array([0. 2) array([0.0. If None. .10. 0.label(a) >>> ndimage. 0]) scipy. . . Release 0. 0. If no structuring element is provided. 0. 1.histogram(a. 0. for a 2D input array. 1.label(input. . Parameters input : array_like An array-like object to be labeled. lbl. 0. 1. nlbl = ndimage. 0. ]. sequence of int.2146. 2.2787].6573. If not None. 1. 10) array([13. structure must be symmetric.dev6665 Data for which to calculate histogram.histogram(a. Reference . 0.histogram(a. 2. 1. 0. 1. . ]. . index : int. max : int Minimum and maximum values of range of histogram bins. 0. ]. 1.measurements.measurements. optional Label or labels for which to calculate histogram. Any non-zero values in input are counted as features and zero values are considered the background. 0. That is. 0]) With labels and no indices.measurements. 0. output=None) Label features in an array. or None. 0.3094]]) >>> from scipy import ndimage >>> ndimage. 10. .7778. Examples >>> a = np. 0. 1. 0. 0. non-zero elements are counted: >>> lbl. must be same shape as input. structure : array_like. min. all values where label is greater than zero are used Returns hist : ndarray Histogram counts. 0. one is automatically generated with a squared connectivity equal to one. labels : array_like or None. 0. [ 0. 1.7181. optional A structuring element that deﬁnes feature connections.array([[ 0. 0. 0.SciPy Reference Guide. 0. optional Labels for objects in input. 0.5962. . bins : int Number of bins. 1. 0.ndimage. 0. . 1.measurements. . 2. 0. 0. 1. 1. [ 0. 10. 0. the default structuring element is: 368 Chapter 3.

it speciﬁes the type of the resulting labeled feature array If output is an array-like object. data-type.1. 1.0]]) >>> labeled_array. 0.1. then output will be updated with the labeled features from this function Returns labeled_array : array_like An array-like object where each unique feature has a unique value num_features : int How many objects were found If ‘output‘ is None or a data type. [0.0.1. [1.1.0]] output : (None.0. >>> s = [[1..0.0. . 2.0].0. Release 0. ‘num_features‘). optional If output is a data type.1...1.0.1].. [0. 1.dev6665 [[0. 0. 0. array_like). [2. . 0.0].0].1]] 3. this function returns a tuple.1. num_features = label(a) Each of the 4 features are labeled with a different integer: >>> print num_features 4 >>> print labeled_array array([[0.2) or. 1. .1. 0.. Multi-dimensional image processing (scipy. 0. [1. : See Also: find_objects generate a list of slices for the labeled features (or objects).10. 3.1]. 0. 0]. then it will be updated with values in : ‘labeled_array‘ and only ‘num_features‘ will be returned by this function. then label it using the default (cross-shaped) structuring element: >>> a = array([[0. 0.SciPy Reference Guide. [1.0]. 0. : (‘labeled_array‘.1. 0].1.ndimage) 369 .0..10.1.1. [0. 0]. 0. : If ‘output‘ is an array. 0]]) Generate a structuring element that will consider features connected even if they touch diagonally: >>> s = generate_binary_structure(2.0. useful for ﬁnding features’ position or dimensions Examples Create an image with some features.0.0. 4. [0.1]. [0.0. [1.

6. 0. 0. 0. index : array_like. 5. [0. index=None) Calculate the maximum of the values of an array over labeled regions. 0. labels=None. num_features = label(a. 0.dev6665 Label the image using the new structuring element: >>> labeled_array. minimum.0. If index or labels are not speciﬁed.:2] = 1 >>> labels[2:. Release 0. Returns output : ﬂoat or list of ﬂoats List of maxima of input over the regions determined by labels and whose index is in index. Examples >>> a = np.reshape((4. optional An array of integers marking different regions over which the maximum value of input is to be computed. 1. standard_deviation Notes The function returns a Python list and not a Numpy array. 3. 1. 0]. the maximum over all elements where labels is non-zero is returned.10. 0. sum. 2. 1. [2. 15]]) >>> labels = np. 11]. optional A list of region labels that are taken into account for computing the maxima. 1. [12.SciPy Reference Guide. a ﬂoat is returned: the maximal value of input if labels is None. 0]. If labels is not speciﬁed.maximum(input. mean. 2.array to convert the list to an array. and the maximal value of elements where labels is greater than zero if index is None. labels : array_like. and 4 from above are now considered a single feature): >>> print num_features 2 >>> print labeled_array array([[0.zeros_like(a) >>> labels[:2.ndimage. [ 4. For each region speciﬁed by labels. use np. extrema. If index is None. structure=s) Show the 2 labeled features (note that features 1.arange(16). 0. 0]]) scipy.4)) >>> a array([[ 0. Reference . Parameters input : array_like Array_like of values.measurements. 3]. the maximal values of input over the region is computed. 0]. 14. 7]. 9. [0. labels must have the same shape as input. the maximum over the whole array is returned. variance. 0. 10. 0. See Also: label. 1. 1:3] = 2 >>> labels 370 Chapter 3. [ 8. 13. maximum_position. 0. 1.

0. 1.standard_deviation. [1. Returns out : list Sequence of same length as index. labels=labels. Release 0. Default is None. Labels must be None or an array of the same dimensions as the input. [0. optional Array of labels of same shape. 0.ndimage. labels_nb + 1)) [5. 0.dev6665 array([[1. 2]. all values where label is greater than zero are used.mean(input. [0. scipy. 0].10.0.maximum_position(input. [5. 0. ndimage. labels=None. 7. 2.maximum. ndimage.10.0] scipy. [0. ndimage.maximum(a) 15. 0]. 1. 7]. If none. [9.0. 0. 2.0. 1. 2].measurements. 9.label ndimage. ndimage. Multi-dimensional image processing (scipy.0. 0. optional Labels of the objects over which the mean is to be computed.0 >>> ndimage. 0].ndimage. 14. Index must be None.label(b) >>> labels array([[1. index=[1. a single label or sequence of labels.arange(1. labels=labels) 14. 2. index=None) Find the positions of the maximums of the values of an array at labels. See Also: ndimage. 0]]) >>> from scipy import ndimage >>> ndimage. 3. [1.ndimage) 371 .array([[1. [0. 0.maximum(a.minimum. 0. labels_nb = ndimage.measurements. [3. 2. or broadcastable to the same shape as input. labels=None.maximum(a. 0]]) >>> labels. in which case the mean for all values where label is greater than 0 is calculated.variance. 3. 0. 0]]) >>> ndimage. 0]. 4].2]) [5. Parameters input : array_like Array on which to compute the mean of elements over distinct regions. All elements sharing the same label form one region over which the mean of the elements is computed. 3. with the mean of the different regions labeled by the labels in index.0] >>> ndimage.SciPy Reference Guide. index=None) Calculate the mean of the values of an array at labels. 0. 3.maximum(b. 0. 1. 0. 2.0 >>> b = np. index=np. labels=labels. labels : array_like.sum. 0]. index : int or sequence of ints.

0].reshape((5. 0. labels_nb >>> labels array([[1. 0. 0. If index is None. 0. maximum. 0. 0. For each region speciﬁed by labels.label(a) 372 Chapter 3.3:5] = 1 >>> index = np. 7].array to convert the list to an array. 0]. mean. 0.array([[1.0] scipy. 0. [0. the minimum over all elements where labels is non-zero is returned. Examples >>> a = np. the minimal values of input over the region is computed.10. 0. 0]. If index or labels are not speciﬁed. index=index) [10. labels=None. [0.zeros_like(a) >>> labels[3:5. 0]. 0. index=None) Calculate the minimum of the values of an array over labeled regions. 21. labels must have the same shape as input. index: array_like. 0.0.mean(a.ndimage. . [5.. [9. and the minimal value of elements where labels is greater than zero if index is None.SciPy Reference Guide. Returns output : ﬂoat or list of ﬂoats List of minima of input over the regions determined by labels and whose index is in index. labels=labels. 0... 2. 0.unique(labels) >>> labels array([[0. extrema. . 0..dev6665 Examples >>> a = np. optional : A list of region labels that are taken into account for computing the minima. If labels is not speciﬁed. 1. 0]]) = ndimage. 1]]) >>> index array([0. [0. variance.. labels: array_like. 0. Reference .5)) >>> labels = np. Release 0. Parameters input: array_like : Array_like of values. the minimum over the whole array is returned. sum. 3. 0. 0]. use np. 3. 4]. >>> labels.285714285714286. 1. 0. standard_deviation Notes The function returns a Python list and not a Numpy array.minimum(input. minimum_position. 1].measurements. a ﬂoat is returned: the minimal value of input if labels is None. .. optional : An array_like of integers marking different regions over which the minimum value of input is to be computed. 1. See Also: label. [0. 0. [0. 0.arange(25). 1]) >>> ndimage.

See Also: label. optional labels to include in output. index=None) Calculate the standard deviation of the values of an n-D image array. 3. 0].array([[1. 3.standard_deviation(a. index : None. 0.standard_deviation(input.ndimage) 373 .0 >>> ndimage. ]) If no index is given. 0]]) >>> from scipy import ndimage >>> ndimage. 7]. all values where label is greater than zero are used.minimum(a.arange(1.10.dev6665 [1.minimum_position(input. If none. 2.label(a) >>> ndimage. If not None. extrema Examples >>> a = np. Index must be None. a single label or sequence of labels. index=np. nlbl = ndimage.0] >>> ndimage.standard_deviation(a. lbl) 2.10. labels=labels. 0. all values where labels is non-zero are used. If None.SciPy Reference Guide.7585095613392387 Features to process can be speciﬁed using labels and index: >>> lbl. 2]. 3.arange(1.minimum(a.standard_deviation(a) 2. 4]. nlbl+1)) array([ 1.4874685927665499 3. optionally at speciﬁed sub-regions. minimum. 1. 0. [0. labels_nb + 1)) [1. or None.0. 3. [9. Release 0. 0]]) >>> ndimage. Parameters input : array_like Nd-image data to process. 1. labels=None. index=None) Find the positions of the minimums of the values of an array at labels. maximum. [0. index=np. must be same shape as input. optional Labels to identify sub-regions in input. for each sub-region if labels and index are speciﬁed. Multi-dimensional image processing (scipy. 2].0 scipy. scipy.0.ndimage. [5.ndimage. labels=None.0. lbl. 0. 0. 0. 0. int. variance. Labels must be None or an array of the same dimensions as the input. 4. 0. or sequence of int. 0. non-zero labels are processed: >>> ndimage.measurements.5 . 3. [3. labels : array_like. labels=labels) 1.minimum(a) 0.479.measurements. Returns std : ﬂoat or ndarray Values of standard deviation.

Returns output : list A list of the sums of the values of input inside the regions deﬁned by labels.609375 374 Chapter 3. extrema Examples >>> a = np. optional labels to include in output.variance(a) 7.0. 0. index=[1.3] >>> labels = [1. 0.0] scipy.2. optional Labels deﬁning sub-regions in input. [9. index : scalar or array A single label number or a sequence of label numbers of the objects to be measured. must be same shape as input. See Also: mean Examples >>> input = [0.sum(input. labels : array_like. 0.SciPy Reference Guide.2. minimum. or None. [0.measurements. labels. 4]. labels=None.10. 2. If not None. If None. Parameters input : array_like Nd-image data to process. Parameters input : array_like Values of input inside the regions deﬁned by labels are summed together. for each sub-region if labels and index are speciﬁed. standard_deviation. Reference . int. [5. Returns vars : ﬂoat or ndarray Values of variance. 0]. labels : array of integers. index=None) Calculate the sum of the values of the array. index=None) Calculate the variance of the values of an n-D image array. See Also: label.array([[1.0.1.measurements. 5.ndimage. labels=None.dev6665 scipy. optionally at speciﬁed sub-regions.variance(input. Release 0. 0.ndimage. all values where labels is non-zero are used.1. 7]. 3. maximum. 0]]) >>> from scipy import ndimage >>> ndimage.2] >>> sum(input. 0. 3.2]) [1. same shape as input Assign labels to the values of the array. index : None. or sequence of int.

SciPy Reference Guide. lbl) 6. An output array can optionally be provided. ]) If no index is given.10.variance(a. If none is provided an element is generated iwth a squared connecitiviy equal to one. Release 0. output=None) Apply watershed from markers using a iterative forest transform algorithm. 2. lbl.ndimage. 3.10. all non-zero labels are processed: >>> ndimage. Multi-dimensional image processing (scipy. structure=None.variance(a.ndimage) 375 . A structuring element deﬁning the connectivity of the object can be provided. index=np.watershed_ift(input.1875.1875 scipy.0.label(a) >>> ndimage. nlbl+1)) array([ 2. markers. Negative markers are considered background markers which are processed after the other markers. nlbl = ndimage.25 .dev6665 Features to process can be speciﬁed using labels and index: >>> lbl.measurements.arange(1. 9.

structure. Release 0.. . structure.morphology. Multi-dimensional black tophat ﬁlter.]) morphological_gradient(input[. size. structure.. using either a structuring element. grey_opening(input[.. grey_erosion(input[.]) Multi-dimensional binary opening with the given structuring element..binary_closing(input.]) black_tophat(input[. Multi-dimensional greyscale closing..ndimage. Non-zero (True) elements form the subset to be closed. Multi-dimensional binary closing with the given structuring element. footprint.0. or a footprint..]) binary_hit_or_miss(input[. Calculate a greyscale dilation.]) binary_erosion(input[... . size. footprint. origin=0) Multi-dimensional binary closing with the given structuring element... ..10. metric. Distance transform for chamfer type of transforms... .]) scipy. 376 Chapter 3. Generate a binary structure for binary morphological operations. Multi-dimensional binary erosion with a given structuring element. output=None.]) binary_propagation(input[... footprint. Multi-dimensional binary hit-or-miss transform..]) binary_dilation(input[.]) distance_transform_bf(input[.]) footprint corresponding to a ﬂat structuring element. Fill the holes in binary objects. .]) distance_transform_edt(input[. structure. . connectivity) grey_closing(input[. Parameters input : array_like Binary array_like to be closed.Multi-dimensional morphological laplace.... Multi-dimensional binary propagation with the given structuring element. . .ndimage.dev6665 3. size. mask. iterations[. Exact euclidean distance transform. structure.. sampling. structure=None. size.. .. . structure1. . .. metric.. or a footprint.....Distance transform function by a brute force algorithm. . . Multi-dimensional white tophat ﬁlter. Multi-dimensional greyscale opening. .]) binary_fill_holes(input[. Calculate a greyscale erosion. Multi-dimensional binary dilation with the given structuring element. .]) grey_dilation(input[.. .SciPy Reference Guide..]) distance_transform_cdt(input[. Multi-dimensional morphological gradient.. binary_opening(input[.10. size. footprint.]) white_tophat(input[.... structure. . size.]) iterate_structure(structure. size. The closing of an input image by a structuring element is the erosion of the dilation of the image by the structuring element.. Iterate a structure by dilating it with itself.. .]) generate_binary_structure(rank.]) footprint corresponding to a ﬂat structuring element. size.]) morphological_laplace(input[..morphology binary_closing(input[. iterations=1. using either a structuring element..5 Morphology scipy. Reference .

output : ndarray. 0. 0.astype(np.int) binary_dilation. 1. each operations is repeated until the result does not change anymore. 1. See Also: grey_closing. Release 0. 0]]) >>> # Closing is the erosion of the dilation of the input >>> ndimage.0. [0. Together with opening (binary_opening). 0. optional Structuring element used for the closing. [0. 1. [R35] Examples >>> a = np. 1. References [R34]. binary_erosion. Returns out : ndarray of bools Closing of the input by the structuring element. 1. Multi-dimensional image processing (scipy. 1.5).binary_closing(a). 0. 1. a new array is created. by default 0. ﬂoat}. 1. 0. [0.dev6665 structure : array_like. [0. 1. Non-zero elements are considered True. 1. 1. 0]]) >>> # Closing removes small holes >>> ndimage.ndimage) 377 . optional Array of the same shape as input.int) >>> a[1:-1.zeros((5. 0.e.astype(np. only nearest neighbors are connected to the center.SciPy Reference Guide. into which the output is placed. 1. If iterations is less than 1. a[2. closing can be used for noise removal.10. 0]. by default). Closing therefore ﬁlls holes smaller than the structuring element. 0. 1. 0]. origin : int or tuple of ints. optional Placement of the ﬁlter. 0. 0.binary_dilation(a). 0]. generate_binary_structure Notes Closing [R34] is a mathematical morphology operation [R35] that consists in the succession of a dilation and an erosion of the input with the same structuring element. binary_opening. 0. If no structuring element is provided an element is generated with a square connectivity equal to one (i. 1. 0. 0]. diagonallyconnected elements are not considered neighbors). 1.10.2] = 0 >>> a array([[0.int) array([[0. 0]. 1. then the erosion step are each repeated iterations times (one. 0]. 1:-1] = 1. optional The dilation step of the closing. 3. dtype=np. 0.. [0. [0. 0]. 0. [0. iterations : {int. 1. [0. By default. 0].

0. iterations=1.10. [0. 0]. 1. 1. 1. [0. 1. 1. 1. 0]. Non-zero elements are considered True.binary_closing(a. 0. 0. 0]. 0. 0]. 1. 1. [0. 0. 0. 1. 1. 0]. 0. 1. 0. 1. 0.binary_dilation(a)).ones((2. 0.int) array([[0. [0.astype(np. 1. [0.SciPy Reference Guide. 0. 0]. [0. 0. 1. [0. 1. 1. 1. 1. 1. 0. 1. closing can also >>> # coarsen boundaries with fine hollows. a[1:3. 1.binary_erosion(ndimage. 0. 0. 1.3] = 0 >>> a array([[0. [0. 1. 0. 1. >>> ndimage. 1. 1]. 0. 0. [0. 1. 1. 0]. 1. 0. 0. 0]. 1.0. 1. 0]. 0. 1. 0]]) >>> # In addition to removing holes. output=None. [0. 1. 0. 0. border_value=0. 0]. structure=np. If no structuring element is provided an element is generated with a square connectivity equal to one. 0. [0. 0]. [0. 1. 0]]) >>> ndimage. 1. Release 0. ﬂoat}. 1. brute_force=False) Multi-dimensional binary dilation with the given structuring element. 0. mask=None. [0. [1. 1. 0]. 0. 0. 1. 0]]) scipy. 1. 0]. [0. [0. 0. 0]. 0. 1. 1. 1. 1. 1. 0. 0]]) >>> a = np. 0. 1.int) array([[0.int) >>> a[1:6. 0. 0]. 0]. 1. 1. 0. 1. 0. 0. [0. 0]]) >>> ndimage. 0. 1. [0. [0. 0. Parameters input : array_like Binary array_like to be dilated. 0.dev6665 array([[0. 0. 0]. 1.2))).zeros((7. [0. 0]. [1.binary_dilation(input. 1.astype(np. 0. 1. 0. 0]. 0. 1.7). structure : array_like. 0. 0. 0. 1. iterations : {int. 1. 0. 0]. Reference . 0. 1. 1]. structure=None. 0]. 0. [0. [0. 2:5] = 1.morphology. 0.ndimage. [0. [0. 0. 0]. 1. 1. 0. 0. 1. 0. 1. 0. 1. 0. 1. 0. optional 378 Chapter 3.binary_closing(a). 0]. 0. 1]. 1. 1. optional Structuring element used for the dilation.astype(np. 0. Non-zero (True) elements form the subset to be dilated. dtype=np. 0. 1. 0. 0. origin=0. 0. 0. 0.int) array([[0. 1. 0. 0. 0. 1. [1. 0. 0.

[ 0.. [ 0. False...]. 0. 0... 0. 0... 1. mask : array_like.ndimage) 379 . [ 0.dtype) array([[ 0. 0. False].zeros((5. 1. False. False. output : ndarray. 0. 1.. a new array is created. 0. 0.]. the dilation is repeated until the result does not change anymore. 1. 0.. [False.].. False].. into which the output is placed.. False. 1. optional Placement of the ﬁlter. [False. 0.. border_value : int (cast to 0 or 1) Value at the border in the output array. binary_erosion.. when its center lies within the non-zero points of the image. [ 0. [ 0. by default).]. False. By default.. 0. 5)) >>> a[2..10..10. 0. 0..0. 0.... 0. False.]. [R37] Examples >>> a = np. [ 0.. False].astype(a.. 0. 0. True. Release 0. 0.. [ 0. 1. dtype=bool) >>> ndimage. True. False.dev6665 The dilation is repeated iterations times (one.]. 0. 0. If iterations is less than 1.. [False. 0. False. Multi-dimensional image processing (scipy... 0. 3. References [R36]. 0. 0. 0. origin : int or tuple of ints.. optional Array of the same shape as input. False]]..]]) >>> ndimage. 0.. 0. 0. True.binary_dilation(a). True... only those elements with a True value at the corresponding mask element are modiﬁed at each iteration.. False. binary_opening..]]) binary_closing. Returns out : ndarray of bools Dilation of the input by the structuring element.SciPy Reference Guide.. generate_binary_structure Notes Dilation [R36] is a mathematical morphology operation [R37] that uses a structuring element for expanding the shapes in an image.binary_dilation(a) array([[False.. False]. 0. The binary dilation of an image by a structuring element is the locus of the points covered by the structuring element. True. 0. by default 0. 0... 0. 2] = 1 >>> a array([[ 0. 0.. False. [ 0. optional If a mask is given.]. [False.. 0.]. See Also: grey_dilation.

[ 0.0.. Non-zero elements are considered True. 1. False]].morphology...]. [ 1.. Non-zero (True) elements form the subset to be eroded. 0....dtype) array([[ 0.. If iterations is less than 1. True]. 1. 0. 0. Binary erosion is a mathematical morphology operation used for image processing.]]) >>> ndimage.. dtype=bool) >>> # 3x3 structuring element with connectivity 2 >>> struct2 = ndimage..]. [ True.. optional If a mask is given.10.generate_binary_structure(2. 0... origin=0. True]. True.. True. [False. True]]. structure : array_like.. output=None. 0.. structure=struct1).].generate_binary_structure(2. [ 0. 1) >>> struct1 array([[False... 1. 0. the erosion is repeated until the result does not change anymore. ﬂoat}. [ 0. 0... True.]]) >>> ndimage.].. 0.SciPy Reference Guide. 1. 0. 0.. [ 0... 1.. 1... 0.]. 0. an element is generated with a square connectivity equal to one. False]..binary_erosion(input. only those elements with a True value at the corresponding mask element are modiﬁed at each iteration.]. 0.. optional 380 Chapter 3..].. 1..\ . True. 1. 0. 0. 1. mask=None.. 0. 0.binary_dilation(a.].]. [ True. If no structuring element is provided. True. 0.]. 1. [ 0. 1. 0. optional The erosion is repeated iterations times (one....].dtype) array([[ 0. [ 0. 1. 1. 0.binary_dilation(a.... structure=struct1. iterations=1.dev6665 >>> # 3x3 structuring element with connectivity 1. 0. 0.dtype) array([[ 0. 0. 1. 1. brute_force=False) Multi-dimensional binary erosion with a given structuring element.. structure=None. [ 0.astype(a. optional Structuring element used for the erosion.. 0. 1.. used by default >>> struct1 = ndimage. 1. iterations=2)..ndimage.. 2) >>> struct2 array([[ True.. mask : array_like. [ 0. 1. 0.. Parameters input : array_like Binary image to be eroded. True]. iterations : {int. 0. 0. 1. Reference ... 1.]. 0.. 0. [ 0. dtype=bool) >>> ndimage.binary_dilation(a.]]) scipy. output : ndarray. 1. 1. 1. [ 0. 0. by default). [ True... 0. 0. 0.. structure=struct2).. 1..astype(a.. 1.astype(a. 0... 1... True. Release 0... border_value=0.. [ 0.

0. 0. 0. 0]. 0]. [0. [0.SciPy Reference Guide. 0]. 0. a new array is created. 0]. [0. 1. 0]. 1. 1. Returns out: ndarray of bools : Erosion of the input by the structuring element. 0. 0. 0. 0. 0. 1. 0. 0. 0. 0.ones((5.zeros((7. 0. 0]. 0. 0]. 0. 0. 0. 1. Release 0. 0. 1. 0. into which the output is placed. 0. 0. 0]. [0. 0]. 0. [0. 0.7). 1. 0. 0. 1. References [R38]. 0. 0. 0. 0. 0. [0. [0. 2:5] = 1 >>> a array([[0. 0. By default. dtype=np. 1. [0. 0]]) binary_closing.astype(a. 0. 0. 0. 0. 0. 0. 0]. 0. [0. 0. 1.dtype) array([[0. origin: int or tuple of ints. 1. 0. 0.astype(a. 0. 0. 0. 0. 0]. [0.int) >>> a[1:6. 0. 0]]) >>> ndimage. 0. 1. optional : Placement of the ﬁlter.binary_erosion(a). 0. 1. 0]. [0.10. 1. [0.dev6665 Array of the same shape as input. 0. 0. 0.binary_erosion(a. 0]. 0. binary_dilation. 0. border_value: int (cast to 0 or 1) : Value at the border in the output array. 0. 0. [0. 0. [0. 0.dtype) array([[0. 0. 0. 0. 0. 0. 0]. generate_binary_structure Notes Erosion [R38] is a mathematical morphology operation [R39] that uses a structuring element for shrinking the shapes in an image. 0. 0. 0. binary_opening. 0. 0. Multi-dimensional image processing (scipy. [R39] Examples >>> a = np. 0. 0. 0. 1. 0. 3. 0. [0. 0.ndimage) 381 . 0. 0. [0. 0.5))). 0]. 1. 1. 0. The binary erosion of an image by a structuring element is the locus of the points where a superimposition of the structuring element centered on the point is entirely contained in the set of non-zero elements of the image. 0. [0. 0]. 0. 0]. 0. 0. [0. 0. 0]. by default 0. 0. 0. 1. See Also: grey_erosion.10. 0. structure=np. 0]]) >>> #Erosion removes objects smaller than the structure >>> ndimage.0. 0.

0]. [0. large-size elements make computations faster but may miss holes separated from the background by thin regions. Release 0. Holes are not connected to the boundary and are therefore not invaded. 0. 1.binary_fill_holes(input.ones((5. 1. 0]. 0]. Returns out: ndarray : Transformation of the initial image input where holes have been ﬁlled. 0]. The result is the complementary subset of the invaded region. [0. optional : Structuring element used in the computation. 1. 1:4] = 1 >>> a[2.morphology. origin: int. [0. 0.2] = 0 >>> a array([[0. 1. 0]. into which the output is placed. 1. 0. [0. 1. 1. output: ndarray. 1. By default. 0]]) >>> # Too big structuring element >>> ndimage.0. using binary dilations. 0.binary_fill_holes(a. 1.zeros((5.binary_fill_holes(a). 0]. 0]. 5). 0. [0. 1. 0.astype(int) array([[0.ndimage. 0. 0. tuple of ints. References [R40] Examples >>> a = np. 0. structure=None.SciPy Reference Guide. 1. optional : Array of the same shape as input. [0. 0. 1. See Also: binary_dilation. output=None. [0. structure=np. 0]]) >>> ndimage. 0. 1.dev6665 scipy. 1.astype(int) 382 Chapter 3. label Notes The algorithm used in this function consists in invading the complementary of the shapes in input from the outer boundary of the image. 1. [0. optional : Position of the structuring element. 1.5))). dtype=int) >>> a[1:4. 1. Reference . origin=0) Fill the holes in binary objects. binary_propagation. The default element (with a square connectivity equal to one) yields the intuitive result where all holes in the input have been ﬁlled.10. 0. Parameters input: array_like : n-dimensional binary array with holes to be ﬁlled structure: array_like. a new array is created. 0. 0].

structure1=None. 0. 0. If no value is provided. the complementary of structure1 is taken.SciPy Reference Guide. by default 0 for a centered structure. 0. origin2 : int or tuple of ints. 1. output=None. [0.7). optional Placement of the ﬁrst part of the structuring element structure1. a[4:6. 1.morphology. origin2=None) Multi-dimensional binary hit-or-miss transform. optional Second part of the structuring element that has to miss completely the foreground. 1. 0. 0]. 0. structure1 : array_like (cast to booleans). 0. 0]. [0. 0. by default 0 for a centered structure. Parameters input : array_like (cast to booleans) Binary image where a pattern is to be detected. output : ndarray. 0. 1] = 1. 1. structure2). Returns output : ndarray Hit-or-miss transform of input with the given structuring element (structure1. 3. 0.dev6665 array([[0. optional Part of the structuring element to be ﬁtted to the foreground (non-zero elements) of input.binary_hit_or_miss(input. origin1 : int or tuple of ints. 4:6] = 1 >>> a array([[0. 1. 1. 0].morphology.int) >>> a[1. 0. If no value is provided. optional Array of the same shape as input. 0. 0]. [0. 0]]) scipy. 0]. a[2:4. 0.ndimage) 383 . Release 0.10. then origin2 is set to origin1. dtype=np. structure2 : array_like (cast to booleans). [0. 2:4] = 1. origin1=0. By default.10.zeros((7. 0].ndimage. See Also: ndimage. [0. 1. 0. 0. structure2=None. 1. binary_erosion References [R41] Examples >>> a = np. Multi-dimensional image processing (scipy. a new array is created. into which the output is placed. If a value is provided for origin1 and not for origin2. optional Placement of the second part of the structuring element structure2. The hit-or-miss transform ﬁnds the locations of a given pattern inside the input image. a structure of square connectivity 1 is chosen. 1. 0.0. 0.

0. Non-zero (True) elements form the subset to be opened. 0]. 1]. 1. If iterations is less than 1. 0. 0. 0. 0. 0. 1. 0. 1. 0]. 0. 0. 0. 1. 0]. 0. 0]]) scipy.astype(np. [0. 1. 0. 0. 0. [0. 0. 0].0.. by default). 0. 0. 0]. 0.ndimage. 0. Parameters input : array_like Binary array_like to be opened. 0. [0. 0. 0].binary_hit_or_miss(a. 1]]) >>> # Find the matches of structure1 in the array a >>> ndimage.int) array([[0. 1.dev6665 [0. 0. 0. 0. [0. 0. iterations=1. optional The erosion step of the opening. [0. [0. optional Structuring element used for the opening. 0. 1. [0. 0. 0. 0.int) array([[0. 0. a new array is created. 0]. [0. 0. origin=0) Multi-dimensional binary opening with the given structuring element. 0]. 0]. [0. 0. structure1=structure1). 0. 0. 0. Reference . 0. 1. 0. diagonallyconnected elements are not considered neighbors). 0. 0]. 384 Chapter 3. 0. Release 0. 0. 0. 0. 0. optional Array of the same shape as input. [0. 0. structure=None. 0. 0.1) here >>> ndimage. 0. 0. The opening of an input image by a structuring element is the dilation of the erosion of the image by the structuring element. 0. structure : array_like. 1. only nearest neighbors are connected to the center.astype(np. 1. 0]. 0]. 0. 0. 0. [0. [0. 1. 0.morphology.SciPy Reference Guide. 0]]) >>> structure1 = np. output : ndarray. then the dilation step are each repeated iterations times (one. 0. 0. 0. 0]. 0. 0. 0. [0. 0. 0.binary_hit_or_miss(a.. [0. [0.e. [0.. 0. output=None. [0. 0. 0. 1. 0. 0. iterations : {int. Non-zero elements are considered True. each operation is repeated until the result does not change anymore. 0. 0.10. 0]]) >>> # Change the origin of the filter >>> # origin1=1 is equivalent to origin1=(1. 0. By default. [0. ﬂoat}. 0. 0]. 0]. 0]. into which the output is placed. 0. 1. 0]. 0. 0. 1. 0. 0. 1]]) >>> structure1 array([[1. 1. If no structuring element is provided an element is generated with a square connectivity equal to one (i. 0. 0. 0. 0. 0. [0. structure1=structure1. 0. 0.\ . 1. 0. 1].array([[1. [0.binary_opening(input. origin1=1). 0. 0. 0].

0]. [0. 1. 0. 1. 0.binary_erosion(a). 0]. 0]. 1.int) array([[0. by default 0. 1. [0. [0. 3.int) array([[0. 0]. [0. 1. 1. [0.binary_opening(a). References [R42]. [0. [0.int) array([[0.astype(np. 1.zeros((5. 0. 0]. 1. [0. Release 0. 0]. 1. [0. a[4. 1. 0]. 1. 0. [0. 0]. 1. [R43] Examples >>> a = np. 1. 0]]) >>> # Opening is the dilation of the erosion of the input >>> ndimage. 1. 1. 1. optional Placement of the ﬁlter. 0. 0. Together with closing (binary_closing).int) >>> a[1:4. 0.0. 1. 0. 1. 0. 0. 1. 0. 0. [0. 0. 0. Opening therefore removes objects smaller than the structuring element. 0. 0. [0. 0]]) >>> ndimage.SciPy Reference Guide. 0.astype(np.binary_dilation(ndimage. 0. 0. 0. 0].10. 0. 0. [0. Returns out : ndarray of bools Opening of the input by the structuring element.10. 0]. 0]. 0]. 0]. 0. 0. 0. 0.int) array([[0. binary_closing.ones((3.5). 1.astype(np. [0.binary_erosion(a)). 0]. 1. generate_binary_structure Notes Opening [R42] is a mathematical morphology operation [R43] that consists in the succession of an erosion and a dilation of the input with the same structuring element. 1:4] = 1. [0.ndimage) 385 . 0. 1. 0. 0. 0.astype(np. 0. dtype=np. structure=np. 0. 1. Multi-dimensional image processing (scipy. [0. 1. See Also: grey_opening.3))). 1]]) >>> # Opening removes small objects >>> ndimage. 0. 0. 4] = 1 >>> a array([[0.binary_opening(a. 0. 0]. 0. 0. 1. 1. 0]. opening can be used for noise removal. [0. 1. 0]. 0. 0]]) >>> # Opening can also smooth corners >>> ndimage. 0. [0. 1. binary_erosion. 0. 0].dev6665 origin : int or tuple of ints. 0. 0]. binary_dilation.

0. 0. 0. 0. 0]. 0. 0]. 0. 0. 0. 0. 0. [R45] Examples >>> input = np. 0]. 0. [0. 0. origin=0) Multi-dimensional binary propagation with the given structuring element.ndimage. The output may depend on the structuring element. 0. a new array is created. 0. 1. 0]. Release 0. 0. structure : array_like Structuring element used in the successive dilations. 0. 0. 8). Reference . into which the output is placed. 2] = 1 >>> mask = np.morphology.binary_propagation(input. 0. mask=None. optional Array of the same shape as input. By default. dtype=np. 0. 8). 0. 0. 0]. Returns ouput : ndarray Binary propagation of input inside mask. If no structuring element is provided. [0. Notes This function is functionally equivalent to calling binary_dilation with the number of iterations less then one: iterative dilation until the result does not change anymore. 0. 0]. 0. border_value=0.dev6665 [0. origin : int or tuple of ints. 0. 0]. output : ndarray. 0.int) >>> input[2. 0. Parameters input : array_like Binary image to be propagated inside mask. especially if mask has several connex components. structure=None. 0. 0. 0. 0. 0. 386 Chapter 3. by default 0. optional Placement of the ﬁlter. 0. The succession of an erosion and propagation inside the original image can be used instead of an opening for deleting small objects while keeping the contours of larger objects untouched. 0]. [0. References [R44]. [0. 1. 0. 0. dtype=np. 0]]) scipy. [0. 6:8] = 1 >>> input array([[0. [0. 0. 0. 0. 0. an element is generated with a squared connectivity equal to one. [0. 0. 0. 0.int) >>> mask[1:4.zeros((8.SciPy Reference Guide. 4] = mask[6:8. 0. 1:4] = mask[4. 0. 0. 0. 0.10. 0.zeros((8. mask : array_like Binary mask deﬁning the region into which input is allowed to propagate. output=None.

0]. mask=a). 0. 0. 0] = 1. 0. 1. [0. 0. 0. 0. 0. 0. 0]. 1. a[0.3))). [0. 0. 0. 1. 0. 1. [0. 0]]) >>> ndimage. 0]. [0. 0. 0.binary_propagation(b. 1. 0. 0. [0. 0. 1. 0. 0. 1. 0]. 0. 0. mask=mask. 0. 0]. [0.. [0. 0. 0.\ . a[5. 0. 0]]) >>> ndimage. 0. 0]. 0. 0. 1. 0. 0. 5] = 1 >>> a array([[1. 0. [0. 0]. 0. 0]]) >>> mask array([[0. 1. 1. 1. 1. 1.int) array([[0. Multi-dimensional image processing (scipy. 0. 0. 0. 0. 0. 1. 0. 0. 1. 0]. 0. [0. 0. 0. [0. 1. 0]. 1. [0. [0. 0. 0]. 0]. 0. 0. 0. [0. Release 0. 0. 0. 0. [0.dev6665 [0. 0.ndimage) 387 . 0. 0]. 0. 0.int) array([[0. 0.binary_opening(a). 0].0. 0]. 0. 0. 1. 0. 0. 0. 0. 0]. 0]. [0. 0.ones((3. 1. 1. 0. [0. structure=np. [0. 0. 0. [0. 0. 0]]) >>> # Comparison between opening and erosion+propagation >>> a = np. 0. [0. 0. 0. 1]]) >>> ndimage.10. 0. 0. 0]]) >>> b = ndimage. 0]. 0. 0. 0. 0]. 0. 0. 0. 1.astype(np. 0. 1. 0. dtype=np. 0. 0. mask=mask). 0. 1. 0. 1. 0. 0.astype(np. 0. 1. 1]. 0]. 0. 0. 0. 0. 0. 0]. 0. 0. 0]. 0. 0. 0]. 1. 0. 0. 0. 0. 0. 1. 0. 1. 0. [0. 0. 0. 0]. 0. 0. 0.int) array([[0. 0. 0. 0]. 0. 0. 0. 0]. [0. 0.SciPy Reference Guide. 0]. 0]. 0. 1]]) >>> ndimage. 0. 0. 0. 0. 0]. 0. 0]. 0. 0. 1. 0. [0. 0. 0.int) >>> a[2:5. 0]. 0. 1. 1. 0. [0. 0. 1. 1. 0. 1. 0. 1. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. [0. 1. [0.10. 2:5] = 1. [0. 0. 1. [0. [0. 1. 1. 0.int) array([[0. 0. 0. 0. 0.zeros((6. 0.astype(np. 0. 1. [0. 0. 0. 0. 0. 0. 0. 0. 1. 0. 0]. 0. 0. 0. 0. 0]. 0. 0]. 1. 0. 0. 0. 1. 0]. 0. 3. 0. 0. 0. 1.binary_erosion(a) >>> b. 0. [0.binary_propagation(input. [0.6). 0. [0. [0. 1. 0. 0. [0. 0]. 0]. [0. 1.. 0. [0.binary_propagation(input. 0.astype(np. 0. 0.astype(int) array([[0. [0. 0. 0. 0. 0. 0]. 0. 0. 0. 0.

distances=None. a metric is generated using generate_binary_structure with a squared distance equal to the rank of the array. The metric determines the type of chamfering that is done. 1.ndimage. see also the function distance_transform_cdt for more efﬁcient taxicab and chessboard algorithms. 1. 1.morphology.0. 0. where cval is the value when mode is equal to ‘constant’. [0.distance_transform_bf(input. metric=’euclidean’. return_distances=True. scipy. 0]. size=None. the feature transform. the distances and indices arguments can be used to give optional output arrays that must be of the correct size and type (ﬂoat64 and int32). 0. 0. 0. The origin parameter controls the placement of the ﬁlter. This function calculates the distance transform of the input. origin=0) Multi-dimensional black tophat ﬁlter. indices=None) Distance transform function by a brute force algorithm. 1. 1. Either a size or a footprint. In this case the index of the closest background element is returned along the ﬁrst axis of the result. 0]]) scipy. return_distances=True. An output array can optionally be provided. 0. the feature transform can be calculated. return_indices=False. Optionally the sampling along each axis can be given by the sampling parameter which should be a sequence of length equal to the input rank.dev6665 [0. If the metric is equal to ‘taxicab’ a structure is generated using generate_binary_structure with a squared distance equal to 1. with its shortest distance to the foreground (any element non-zero). or the structure must be provided. the feature transform can be calculated. Reference . In addition to the distance transform. structure=None. 388 Chapter 3. metric=’chessboard’. This function employs a slow brute force algorithm. grey_closing References [R46]. 0].ndimage. [0. output=None. indices=None) Distance transform for chamfer type of transforms.SciPy Reference Guide. and return_indices ﬂags can be used to indicate if the distance transform. 0. Release 0. mode=’reﬂect’. 0]. return_indices=False. or a single number in which the sampling is assumed to be equal along all axes. Three types of distance metric are supported: ‘euclidean’. 1. This parameter is only used in the case of the euclidean distance transform. 1. In addition to the distance transform. See Also: grey_opening. The return_distances. sampling=None.morphology.morphology.distance_transform_cdt(input. by replacing each background element (zero values). The mode parameter determines how the array borders are handled.10.black_tophat(input.ndimage.0. 1. 1. ‘taxicab’ and ‘chessboard’. [R47] scipy. 0. distances=None. In this case the index of the closest background element is returned along the ﬁrst axis of the result. or both must be returned. footprint=None. [0. cval=0. If the metric is equal to ‘chessboard’. These choices correspond to the common interpretations of the taxicab and the chessboard distance metrics in two dimensions.

must be of length equal to the input rank. Can be any type but will be converted into binary: 1 wherever input equates to True. must be of type int32.morphology. return_indices : bool. In addition to the distance transform. indices : ndarray. if a single number.dev6665 The return_distances. the feature transform.distance_transform_edt(input. index matrix. optional Spacing of elements along each dimension.ndimage. indices=None) Exact euclidean distance transform. sampling : ﬂoat or int. The distances and indices arguments can be used to give optional output arrays that must be of the correct size and type (both int32). Parameters input : array_like Input data to transform.0.10. a grid spacing of unity is implied. Default is False. distances=None. or sequence of same. optional Whether to return indices matrix. optional Used for output of indices. If a sequence. return_distances=True. scipy. and n is the number of dimensions. return_indices=False. Returns result : ndarray or list of ndarray Either distance matrix. Release 0. return_distances : bool. and return_indices ﬂags can be used to indicate if the distance transform. this is used for all axes. Default is True. 3. Notes The euclidean distance transform gives values of the euclidean distance: n y_i = sqrt(sum (x[i]-b[i])**2) i where b[i] is the background point (value 0) with the smallest Euclidean distance to input points x[i]. optional Used for output of distance array. Multi-dimensional image processing (scipy. depending on return_x ﬂags and distance and indices input parameters. distance : ndarray. optional Whether to return distance matrix. sampling=None. or a list of the two. must be of type ﬂoat64.10. At least one of return_distances/return_indices must be True. the feature transform can be calculated. In this case the index of the closest background element is returned along the ﬁrst axis of the result.ndimage) 389 .SciPy Reference Guide. or both must be returned. If not speciﬁed. 0 elsewhere.

2. [0. Reference . ]. . [2. 2. 1. 0. 2. 0. 1. . [ 0. [ 0. 2. 2. 0.SciPy Reference Guide. 1. ]. 3.4142.) + a. 1. ]. [1. . . 1.1. .0. 4]. 1. 1. 3. 4]]. . . [ 0. ]. 0. [ 0. . 1. 3. [ 0. 1. 2.distance_transform_edt(a. . .1]) array([[ 0. 1. . 0. 4. . 3]. . 0. 4. 1.1. 1.1.1]. 1. .4142. return_indices=True) >>> inds array([[[0. 0.rank(a). [ 0. . 2. 2.1. . 3]. 3. .1]. 1. 0. 1. 3]. 4].0]. 1. 1. . 0. [0. . . [3. 3. [ 0.distance_transform_edt(a. ]. [[0.1.zeros(((np. [0. 0.1. .distance_transform_edt(a. 0. 2. 1. 1. [0. 4. 2.4142. 1.4142. 1. 1.int32) >>> ndimage. [[0. [0. dtype=np. 0. .array(([0. . 4. 3. 1. 2. . 3]. ]]) >>> indices array([[[0. 1. . . .1. 3.1. . ]. . 1. . 1.distance_transform_edt(a) array([[ 0. 1. 3].10. [2.1. 4. 4]. 1. 4. 1. 1. 0.1. .1]. . [ 0. [0. 1. [ 0. 4]]]) 390 Chapter 3. . 4.4142. 3]. 1. . . ]]) Asking for indices as well: >>> edt. . [0. . 3]. . . . 1. 4. 3. 3.8284. 1. [ 0. 1.2361.1. 1. 3. 1. Release 0. 1. 1. 1. 0. [4.4142.6056].2361. return_indices=True. 0.shape). 3. .4142. ]]) With a sampling of 2 units along x. 4. 0. 1 along y: >>> ndimage. 1. [0. 1. ]. 3. 1. 4. 1. ]. [ 0.1. 4. 3. . 4]. 4. 1. sampling=[2. 0. 2. 1. . . indices=indices) array([[ 0. 3]. . [3. 4]]]) With arrays provided for inplace outputs: >>> indices = np. ]. 1.4142. [1. 1. [4. ]. 0. 0.2361. ]. [0. 4]. 1. 0. 4]]. 0. 4]. 1. [0. 4]. 1. [ 0. . . 2. . 1. 1. [0. [0.0. 4].1.0])) >>> from scipy import ndimage >>> ndimage. 0. 2.0.dev6665 Examples >>> a = np. 1. inds = ndimage. 3. 3. 3. 1. 2.

1.dtype) array([[ 0. 0.. 1. See Also: iterate_structure. 0. 0. 0. i.. 2] = 1 >>> a array([[ 0. 1..ones.]. [False.. 0.. 1.binary_dilation(a. 1.. 1) >>> struct array([[False. binary_erosion Notes generate_binary_structure can only create structuring elements with dimensions equal to 3..binary_dilation(b. Release 0.].]]) 3..ndimage. 1. [ 0.]. 0..e... For larger structuring elements. 0. 0.. 0. [ 0.. 1.. 0.]]) >>> ndimage. binary_dilation. with rank dimensions and all dimensions equal to 3.zeros((5. for eroding large objects. 0. 0. 0. structure=struct). [ 0.g. 0. 0. Parameters rank : int Number of dimensions of the array to which the structuring element will be applied. 0.. 0. 0.].]. [ True.10.. 1.. [ 0.. False].SciPy Reference Guide..10.]]) >>> b = ndimage... True. True..5)) >>> a[2...]. connectivity) Generate a binary structure for binary morphological operations. 0.]..ndimage) 391 . True]. 0. 0. [ 0. 0. Multi-dimensional image processing (scipy. 0... 0. 1. 0... 0. 0. one may either use iterate_structure. 0.morphology. 0... 0. 0.. 0. True. [ 0. 0.. False]].. are considered as neighbors of the central element. structure=struct)...].. [ 0. 1. minimal dimensions.]. that are useful e. 0. 1. 1..]. 0.. [ 0. [ 0. 0..dev6665 scipy. 1.. or create directly custom arrays with numpy functions such as numpy. [ 0.. 1.. 1. 0.. connectivity may range from 1 (no diagonal elements are neighbors) to rank (all elements are neighbors).astype(a.ndim. 0. connectivity : int connectivity determines which elements of the output array belong to the structure...dtype) >>> b array([[ 0. 1.e.. 0.. 1.]... as returned by np.. [ 0. Examples >>> struct = ndimage. 0. [ 1. 0.astype(a. Returns output : ndarray of bools Structuring element which may be used for binary morphological operations..].generate_binary_structure(2.generate_binary_structure(rank. dtype=bool) >>> a = np.....0. 1... Elements up to a squared distance of connectivity from the center are considered neighbors.. 0. i..

False]]]. ‘wrap’}. optional The mode parameter determines how the array borders are handled. False].10. True. Parameters input : array_like Array over which the grayscale closing is to be computed. False. mode=’reﬂect’. Default 0 Returns output : ndarray Result of the grayscale closing of input with structure. Release 0.0. structure may be a non-ﬂat structuring element. dtype=bool) scipy. False. True]. [False. cval=0. False]. [[False. True. size : tuple of ints Shape of a ﬂat and full structuring element used for the grayscale closing. [False. [ True. optional Positions of non-inﬁnite elements of a ﬂat structuring element used for the grayscale closing. footprint=None.generate_binary_structure(2.SciPy Reference Guide. output : array. True. True]].grey_closing(input. False]].morphology. [[False.generate_binary_structure(3.’mirror’. False]. A greyscale closing consists in the succession of a greyscale dilation.0. False]. Default is ‘reﬂect’ cval : scalar. 1) >>> struct # no diagonal elements array([[[False.’nearest’. [False. footprint : array of ints. Reference . False]]. True]. True. False. Default is 0. False. and a greyscale erosion. Optional if footprint is provided. optional Value to ﬁll past edges of input if mode is ‘constant’. optional Structuring element used for the grayscale closing. [False. dtype=bool) >>> struct = ndimage. False]. origin : scalar. structure : array of ints. 392 Chapter 3.0. 2) >>> struct array([[ True. [ True. optional The origin parameter controls the placement of the ﬁlter. output=None. origin=0) Multi-dimensional greyscale closing. optional An array used for storing the ouput of the closing may be provided. True. where cval is the value when mode is equal to ‘constant’. True. [False. True.’constant’. size=None. [ True. True]. mode : {‘reﬂect’. True. structure=None.ndimage.dev6665 >>> struct = ndimage.

5]. 19. [12. Parameters input : array_like Array over which the grayscale dilation is to be computed. 13. 34. 4. 3. 26. 26. structure=None. size : tuple of ints Shape of a ﬂat and full structuring element used for the grayscale dilation. 35]]) >>> # Note that the local minimum a[3. generate_binary_structure Notes The action of a grayscale closing with a ﬂat structuring element amounts to smoothen deep local minima.reshape((6. 32. scipy. 10. 28. whereas binary closing ﬁlls small holes. [24. grey_dilation.SciPy Reference Guide. or a footprint corresponding to a ﬂat structuring element. footprint=None. structure may be a non-ﬂat structuring element. structure : array of ints. 27. 33.ndimage) 393 .10. Release 0. grey_opening. 0.morphology. Grayscale dilation is a mathematical morphology operation. origin=0) Calculate a greyscale dilation. 31. output=None. 9. optional Positions of non-inﬁnite elements of a ﬂat structuring element used for the grayscale dilation. [31. 28. size=None. [ 7. it can be viewed as a maximum ﬁlter over a sliding window. 25. 22. 9. 31. 7. Optional if footprint is provided. mode=’reﬂect’. 8.3] = 0 >>> a array([[ 0.ndimage. 13. 7.grey_dilation(input. cval=0. 23]. [18. Multi-dimensional image processing (scipy.6)) >>> a[3. 16. 20. 15. 32. 2.dev6665 See Also: binary_closing. 14. using either a structuring element. 10. 19. 1.arange(36). [30. 22. optional Structuring element used for the grayscale dilation. 27. 17].3] has disappeared grey_erosion. 15. [25. 11]. 20. 29]. [13. 23]. References [R48] Examples >>> a = np. 17]. [19. size=(3. 3. 11]. 35]]) >>> ndimage. Non-zero values give the set of neighbors of the center over which the maximum is chosen. 25. 29]. 11]. 7. 8. 14. 10.grey_closing(a. For the simple case of a full and ﬂat structuring element.3)) array([[ 7. 20. 33. footprint : array of ints. 9.0. 34. 8. [ 6.10.0. 16.

0. [0. 0. 3. 3. 0. 2. footprint=np. for structuring elements deﬁned as s(y) = 0 for y in E. 0. 0]]) >>> ndimage.0. 0. 3.3] = 3 >>> a array([[0. Default is ‘reﬂect’ cval : scalar. 0. mode : {‘reﬂect’. 3.’constant’. 0]. 0. 0. 2. [0. 0.grey_dilation(a. 0. 1. 1. Grayscale dilation [R49] is a mathematical morphology operation [R50]. the grayscale dilation computes the maximum of the input image inside a sliding window deﬁned by E. 2. 2. 1. 0]. 0. 0. [0. 0.int) >>> a[2:5. 3. 0. ndimage. 0]. 1. 2:5] = 1 >>> a[4.SciPy Reference Guide. 0. 0]. 0. 1. [0. 0.ones((3. [0.0. 394 Chapter 3. 1.’nearest’.zeros((7. origin : scalar. 2. 0]. [0. References [R49]. See Also: binary_dilation. optional The origin parameter controls the placement of the ﬁlter. grey_closing. 0]. 0. 0]. 0. [0. 0. dtype=np. [0. 0. 3. Default is 0. 0. 1. 2. 0. 1. 0. 0. 0]]) >>> ndimage. 1. 3. 0. 2. 0. 0]. 0]. 1. Release 0. optional The mode parameter determines how the array borders are handled.3)) array([[0. 0].dev6665 output : array. 0]. 0. 1.4] = 2. optional An array used for storing the ouput of the dilation may be provided. 0. [R50] Examples >>> a = np. 1. 0. optional Value to ﬁll past edges of input if mode is ‘constant’. 1. [0. 3. a[2. 3. 1. 1. [0. 2. grey_erosion. [0. 0.10. ‘wrap’}. 0. size=(3. 3. 0. 0. generate_binary_structure. 1. 0. Default 0 Returns output : ndarray Grayscale dilation of input. Reference .maximum_filter Notes The grayscale dilation of an image input by a structuring element s deﬁned over a domain E is given by: (input+s)(x) = max {input(y) + s(x-y). [0. for y in E} In particular.grey_dilation(a.7). where cval is the value when mode is equal to ‘constant’. 0]. 0.3))) grey_opening.’mirror’.

Multi-dimensional image processing (scipy. 0. 1. 0. 1. 3. optional Structuring element used for the grayscale erosion. 3. Parameters input : array_like Array over which the grayscale erosion is to be computed. 0. 0. 0. 2. [1.ndimage) 395 . 2. 1. [0. 1. 4. output : array. [False. 1. 2. 4. 1. 0]. 3. [1.SciPy Reference Guide. [1. 2. 0. 3. [0. size=(3. 3. 4.3))) array([[1.grey_erosion(input. 0]. 1. 0. 0. 3. 3. it can be viewed as a minimum ﬁlter over a sliding window. 3. using either a structuring element. 1. 0]. footprint : array of ints. 1.1) >>> s array([[False. 3. True. size=None. 1. [0. [1. 3. 1. footprint=None. [0. [1. 1. 2. 2. 1]. 3. 1. footprint=s) array([[0. 0. 3. Grayscale erosion is a mathematical morphology operation. 1. or a footprint corresponding to a ﬂat structuring element. 3. 3. 3.dev6665 array([[0. optional Positions of non-inﬁnite elements of a ﬂat structuring element used for the grayscale erosion. 1. True. optional An array used for storing the ouput of the erosion may be provided. 2. True]. False]]. 0. 2.0.10.3). [0. [0. 0. 0. 2. 2. mode=’reﬂect’. 0. 1. structure : array of ints.0.grey_dilation(a. structure may be a non-ﬂat structuring element. 2. 0. 1]]) scipy. True. 2. 0]. For the simple case of a full and ﬂat structuring element.grey_dilation(a. 0]. size : tuple of ints Shape of a ﬂat and full structuring element used for the grayscale erosion. 0]. output=None.ndimage. 0. 1]. 0. 2. 0. [0. 1. 1. 1]. 0]. 0. 1. 1. 1. 0. 1. 4. 1. 2. 1]. 4. 0]. 1]. 4. [0. 3. 1. 3. Optional if footprint is provided. 0]. 0. 2. 1. 3. 1]. dtype=bool) >>> ndimage. 0. 0]]) >>> ndimage. 0. 4. 4. 0. 0]. 1.ones((3. [0. 2. [0. [0. 3. 0]. origin=0) Calculate a greyscale erosion. 3. 1. 3. 2. 1. 0. [1.morphology. Release 0. [ True. 3.generate_binary_structure(2. [0. 1. 1. structure=None. 0]]) >>> s = ndimage.10. 0]. 4. False]. 2. 2. structure=np. Non-zero values give the set of neighbors of the center over which the minimum is chosen. cval=0. 2. 2.

1) >>> footprint array([[False.0. 1:6] = 3 >>> a[4. 0. [0.7). Release 0. 3. References [R51]. for y in E} In particular. 0. 3. 3. True]. 3. 0. 3. 0. 3. 1. 0]. [0. 1. 3. [0. 0. 3.’nearest’. 0. [0. 3.3] = 1 >>> a array([[0. 0. where cval is the value when mode is equal to ‘constant’. 3.’constant’. optional The origin parameter controls the placement of the ﬁlter. optional The mode parameter determines how the array borders are handled. [R52] Examples >>> a = np.’mirror’. 1. 0. grey_dilation. [ True. 3. 0. grey_closing. 0. 3. [0. Default is 0. 0].zeros((7. 3. the grayscale erosion computes the minimum of the input image inside a sliding window deﬁned by E. 3. 0. 0. [0. origin : scalar. 3. Default is ‘reﬂect’ cval : scalar. 0].int) >>> a[1:6. 2.0.3)) array([[0. 0. 0]]) >>> ndimage. 2. 3.dev6665 mode : {‘reﬂect’. 396 Chapter 3. 0. 0. 0. 0. 0. [0. 0]. 0.4] = 2. 1. True. 0]. [0. 0]. optional Value to ﬁll past edges of input if mode is ‘constant’. a[2.grey_erosion(a. 3. dtype=np. grey_opening. 0. True.minimum_filter Notes The grayscale erosion of an image input by a structuring element s deﬁned over a domain E is given by: (input+s)(x) = min {input(y) . 0. 0. 1. 0. See Also: binary_erosion. 3. 0. 3. Reference . 0. 0. 3. 0]. 0]. ndimage. Grayscale erosion [R51] is a mathematical morphology operation [R52]. 0. 3.generate_binary_structure(2. 0. 0]]) >>> footprint = ndimage. ‘wrap’}. [0. 1. 0. 0. 0. generate_binary_structure. 0. 3. 0.10. size=(3. 3. [0. 1. 2. 0]. 0]. [0. 0]. 0. [0. 0. 0.SciPy Reference Guide.s(x-y). 0]. 3. for structuring elements deﬁned as s(y) = 0 for y in E. False]. Default 0 Returns output : ndarray Grayscale erosion of input.

optional The mode parameter determines how the array borders are handled. 0. optional Value to ﬁll past edges of input if mode is ‘constant’. 0. mode=’reﬂect’. origin : scalar. 0]. 0. False]]. 0.’mirror’. size=None. ‘wrap’}. footprint=footprint) array([[0. True. where cval is the value when mode is equal to ‘constant’. [0. Multi-dimensional image processing (scipy. Default is 0. optional The origin parameter controls the placement of the ﬁlter. 0. 0.ndimage) 397 . generate_binary_structure grey_erosion. structure may be a non-ﬂat structuring element.ndimage. cval=0. optional Structuring element used for the grayscale opening.dev6665 [False.10. optional An array used for storing the ouput of the opening may be provided.0.grey_erosion(a.SciPy Reference Guide. size : tuple of ints Shape of a ﬂat and full structuring element used for the grayscale opening. 0. 1. [0. structure : array of ints. 0. 0. 0]. 3.’nearest’. 1. 0. 1.grey_opening(input. Parameters input : array_like Array over which the grayscale opening is to be computed. 0. 0. 0. 0. 2. grey_dilation. Optional if footprint is provided. 0. output : array. 0]]) scipy. mode : {‘reﬂect’.0. Default is ‘reﬂect’ cval : scalar. grey_closing. A greyscale opening consists in the succession of a greyscale erosion. structure=None. 0]. size=(3. 3.10. See Also: binary_opening. dtype=bool) >>> # Diagonally-connected elements are not considered neighbors >>> ndimage. [0. footprint : array of ints. 0]. 0. 0. 0. [0.morphology. 0. 0. Release 0. 3. and a greyscale dilation.’constant’. optional Positions of non-inﬁnite elements of a ﬂat structuring element used for the grayscale opening. [0. output=None. 0. 0. Default 0 Returns output : ndarray Result of the grayscale opening of input with structure. 1. 0. 0]. 0. 2. 0.0. 0. 0]. 2. footprint=None. origin=0) Multi-dimensional greyscale opening. [0.3).

1) times with itself. 22. 28. 16. 15. 0]. 33.3)) array([[ 0. 4. 0]]) 398 Chapter 3. 1. [24. 9. References [R53] Examples >>> a = np. 2. [30. 17]. a tuple of the iterated structure and the modiﬁed origin is returned. [12. If not. 34. 28.SciPy Reference Guide. 1. to be dilated with itself. 22]. 25. iterations : int number of dilations performed on the structure with itself origin : optional If origin is None. 7. 3. for example). 19.morphology.3] has disappeared scipy. 35]]) >>> ndimage. 9. 28. 16]. 32.10. 22.6)) >>> a[3.astype(int) array([[0.dev6665 Notes The action of a grayscale opening with a ﬂat structuring element amounts to smoothen high local maxima. 15. Returns output: ndarray of bools : A new structuring element obtained by dilating structure (iterations . 13. Parameters structure : array_like Structuring element (an array of bools.arange(36). 1]. 3] = 50 >>> a array([[ 0. 1) >>> struct. [1.0.generate_binary_structure(2. 27.iterate_structure(structure. 4]. 14. 16. 29]. 8. 25. 2. 5]. [12. 13. [0. 26. 10]. 8. 26. [ 6. origin=None) Iterate a structure by dilating it with itself. 25. 31. 19. Release 0. 50. 14. whereas binary opening erases small objects. size=(3. [ 6.ndimage. 28].reshape((6. 22. 11]. See Also: generate_binary_structure Examples >>> struct = ndimage. 20. 26. [24. 27. 7. 10. 28]]) >>> # Note that the local maximum a[3. 3. [18. Reference . only the iterated structure is returned. 27. 1. [24. 10. 20. 1. iterations.grey_opening(a. 4. 23]. [18. 1.

[0. origin : scalar. 1. structure may be a non-ﬂat structuring element. mode : {‘reﬂect’. Parameters input : array_like Array over which to compute the morphlogical gradient. Multi-dimensional image processing (scipy. 1.0. 1. output=None. Optional if footprint is provided. [1.ndimage. where cval is the value when mode is equal to ‘constant’. optional An array used for storing the ouput of the morphological gradient may be provided.’mirror’. 0. 1. optional The mode parameter determines how the array borders are handled. 0]]) >>> ndimage.SciPy Reference Guide. 1. 0. Larger footprints give a more blurred morphological gradient. 1. footprint=None. 0.astype(int) array([[0. optional Positions of non-inﬁnite elements of a ﬂat structuring element used for the morphology operations.astype(int) array([[0. 0. 1. A larger size yields a more blurred gradient. 1. 1. [0. [0. 0. The morphological gradient is calculated as the difference between a dilation and an erosion of the input with a given structuring element. 1. 1. 1. 1. 0. 0. 1. 1. 1.iterate_structure(struct. 0.’constant’.0. 1.morphology. 1. 1. 0. 1. 0]. 3). 1. 0. 0. 1. origin=0) Multi-dimensional morphological gradient. 0. size : tuple of ints Shape of a ﬂat and full structuring element used for the mathematical morphology operations. 0]. 0. 1.ndimage) 399 . 0. 0]]) scipy.10. 1]. 0]. 1. 0.morphological_gradient(input. 1. 0]. 3. 2). 1.0. output : array. 1. 0]. 0. 0]. ‘wrap’}. [0. footprint : array of ints. 0]. 1. structure=None. structure : array of ints. optional Value to ﬁll past edges of input if mode is ‘constant’. [0. 1.dev6665 >>> ndimage. 1. [0.iterate_structure(struct. 1. Default is 0. optional Structuring element used for the morphology operations.10. size=None. optional The origin parameter controls the placement of the ﬁlter. 0]. 1. [1. mode=’reﬂect’. 1. 1. 1]. [0. Default is ‘reﬂect’ cval : scalar. Default 0 Returns output : ndarray Morphological gradient of input.’nearest’. cval=0. Release 0. [0.

0. [0. 1. 2. 0]. 2. 1. 0]. 1. 0. 0. 1. 3. 1. 1. 3. 1. 0. 1.gaussian_gradient_magnitude Notes For a ﬂat structuring element. 0. 0. [0. 0. 0]. [0. 0. cval=0. [0. 0. 0.10. 0. 1. 0. 1. 3. 0. [0. 1. 0. 1. footprint=None. 0. [0. 0. [0. 0. 0. 0.0. 0. 1. [0. 0]. 2. output=None. 0. 1. size=(3. 0]. 1. 1. mode=’reﬂect’. 1. 2.zeros((7. 1.7). 1.grey_dilation(a. 0. 0]]) >>> a = np. 1. 0. 1. dtype=np. [0. [0. [0. 0]. 1. 1.3)) array([[0. 0]. 1. [0. 1. 0. 1. 0]. 0. 0. 0. 1. 0. 0]. 0. 1.dev6665 See Also: grey_dilation. [0. 1. 1. 1. 0. ndimage. 1. size=(3. [0. 0]. 1.grey_erosion(a. 1. 1. 0. 0. a[2. 1. 0. [0. 0]. 0. [0. 2. 3. 0. 0]. [0. 1.3)) array([[0. 1. size=(3.morphological_gradient(a.4] = 2.morphological_laplace(input.3)) array([[0. Reference . 0. 0. 0. 0]]) scipy. 3.int) >>> a[2:5. [0. 0. size=(3. 0. 1. 0]. 0. 0. [0. 0. 0]]) >>> # The morphological gradient is computed as the difference >>> # between a dilation and an erosion >>> ndimage. 1. 0. 0. 0]. 0]. 0. 3. 0. 0].zeros((7. 1. 0.SciPy Reference Guide. 0].ndimage. 1. 0. 3. 2. 3. 1. 2. 0. 2:5] = 1 >>> a[4. 1. 0]. 0]. 2. 2:5] = 1 >>> ndimage. [0. 1. 0. 0. 1. Release 0. 1. 1. 0.3)) -\ . size=None. 0. 0. 1. 1. 1.morphological_gradient(a. [0. structure=None. 1.3] = 3 >>> a array([[0. 1. 0. the morphological gradient computed at a given point corresponds to the maximal difference between elements of the input among the elements covered by the structuring element centered on the point. 0]. 2. [0.morphology.. 1. [0. 1. [0.. 0. 3. 1. 1. 0. grey_erosion. 0. 1. 0]]) >>> ndimage. 1. 1. 0]. 0]. 1.int) >>> a[2:5. dtype=np. origin=0) 400 Chapter 3. 0]. 1. 0]. 1. References [R54] Examples >>> a = np. ndimage.7). 1.

OLS procedures require that the response variables be an explicit function of the explanatory variables. footprint=None. structure=None. ODR can handle both of these cases with ease. Weights can be provided to account for different variances of the observations. the user is urged to at least skim the ODRPACK User’s Guide .e.morphology.odr) 401 . and even covariances between dimensions of the variables. the classes do. Furthermore.1 Orthogonal Distance Regression (scipy. While the docstring of the function odr does not have a full explanation of its arguments.” Use See the docstrings of odr. or the structure must be provided. The mode parameter determines how the array borders are handled.white_tophat(input. cval=0. odr provides two interfaces: a single function.11 Orthogonal distance regression (scipy. The ﬁtting functions are provided by Python functions operating on NumPy arrays. The origin parameter controls the placement of the ﬁlter. The required derivatives may be provided by Python functions as well. Either a size or a footprint. The ODRPACK User’s Guide (linked above) is also quite helpful. sometimes making the equation explicit is impractical and/or introduces errors.odr) Introduction Why Orthogonal Distance Regression (ODR)? Sometimes one has measurement errors in the explanatory (a. An output array can optionally be provided. References Modules odrpack models Python wrappers for Orthogonal Distance Regression (ODRPACK). not just the response (a.dev6665 Multi-dimensional morphological laplace. where cval is the value when mode is equal to ‘constant’. Python wrappers for Orthogonal Distance Regression (ODRPACK). or may be estimated numerically..k. An output array can optionally be provided. scipy.k. 3. ODRPACK is a FORTRAN-77 library for performing ODR with possibly non-linear ﬁtting functions.11. “independent”) variable(s).0.odr) 3. The mode parameter determines how the array borders are handled. and arguments of the same name usually have the same requirements. Collection of Model instances for use with the odrpack ﬁtting package. 3. It uses a modiﬁed trust-region Levenberg-Marquardt-type algorithm [R156] to estimate the function parameters. Ordinary Least Squares (OLS) ﬁtting procedures treat the data for explanatory variables as ﬁxed.. Input and output variables may be multi-dimensional. not subject to error of any kind.11. or it can do OLS. Release 0. ODRPACK can do explicit or implicit ODR ﬁts. Either a size or a footprint. Furthermore.10.a. i. and a set of high-level classes that wrap that function.a.0. where cval is the value when mode is equal to ‘constant’.. size=None.“Know Thy Algorithm.SciPy Reference Guide. please refer to their docstrings for more information.ndimage. or the structure must be provided. output=None. The origin parameter controls the placement of the ﬁlter. and can even reduce to the OLS case if that is sufﬁcient for the problem. mode=’reﬂect’.odrpack and the functions and classes for usage instructions. Orthogonal distance regression (scipy. origin=0) Multi-dimensional white tophat ﬁlter. “dependent”) variable(s).

mydata = Data(x.pprint() 402 Chapter 3. Reference .run() 6) Examine output. wd=1.0.. beta0=[1. linear = Model(f) 3) Create a Data or RealData instance. myoutput = myodr.10. we=1. myodr = ODR(mydata. myoutput./power(sy. model and initial parameter estimate. y. 2) Create a Model. Release 0. x): ’’’ Linear function y = m*x + b ’’’ return B[0]*x + B[1] # B is a vector of the parameters. y. linear.2).2)) or mydata = RealData(x. 2./power(sx. # Return an array in the same format as y passed to Data or RealData. def f(B. sx=sx. # x is an array of the current x values. # x is same format as the x passed to Data or RealData.]) 5) Run the ﬁt. sy=sy) 4) Instantiate ODR with your data.SciPy Reference Guide.dev6665 Classes Data – stores the data and weights to ﬁt against RealData – stores data with standard deviations and covariance matrices Model – stores the model and its related information Output – stores all of the output from an ODR run ODR – collects all data and runs the ﬁtting routine Exceptions odr_error – error sometimes raised inside odr() and can be raised in the ﬁtting functions to tell ODRPACK to halt the procedure odr_stop – error to raise in ﬁtting functions to tell ODRPACK that the data or parameters given are invalid Use Basic use: 1) Deﬁne the function you want to ﬁt against.

.]) ODR(data. if M>1. Credits • Thanks to Arnold Moene and Gerard Vermeulen for ﬁxing some killer bugs.odr) 403 . we. The ODR class gathers all information and coordinates the running of the The Output class stores the output of an ODR run. Robert Kern robert. we. beta0. the input and output arrays of the ﬁtting function (and its Jacobians) are passed to FORTRAN without transposition. Of course. some are from other sources.py for examples of how to set up ﬁts of your own. fjacb. fjacd. covx. sy. wd. iﬁxb. y. Except for the Jacobians. M). extra_args. then your Python functions will be dealing with arrays that are indexed in reverse of the ODRPACK documentation.kern@gmail.. . the one-dimensional case. beta0. N).j’th elements (@f_i/@x_j) evaluated at the n’th observation will be returned as jacd[j. The Data class stores the data to ﬁt. Some are taken from the User’s Guide. fjacb.. fjacb.com Functions odr(fcn. j. 3. i.]) report_error(info) Classes Data(x[.]) Output(output) RealData(x[. The Model class stores information about the function you wish to ﬁt. The RealData class stores the weightings as actual standard deviations Interprets the return code of the odr routine.py . ﬁx. then nothing matters. . k] is next to A[i. No real biggie.1]. Contributions are welcome. NumPy. Therefore. x[..10. In C and. it will be passed to the Python function as an array of shape (M.e. meta]) Exceptions odr_error odr_stop Collection of Model instances for use with the odrpack ﬁtting package. delta0. n].]) The Model class stores information about the function you wish to ﬁt. consequently. y. but watch out for your indexing of the Jacobians: the i. For efﬁciency and convenience. • Models – Some common models are instantiated in the accompanying module models. arrays are stored row ﬁrst: A[i. If M==1.. ﬁx. • Examples – See the accompanying ﬁle test/test. wd.SciPy Reference Guide. an array element A(i. sx. Release 0. it really is easier to deal with x[0] and x[1] than x[:. k) will be next to A(i+1. meta]) Model(fcn[. Orthogonal distance regression (scipy.0] and x[:. where the ODRPACK documentation says that the X array is of shape (N. you can always use the transpose() function from scipy explicitly. j. i. y. k+1]. . covy. extra_args. . j.11.0. Notes • Array formats – FORTRAN stores its arrays in memory column ﬁrst...dev6665 Read the docstrings and the accompanying tests for more advanced usage.. model[. k). j. Functions polynomial(order) Classes Model(fcn[. fjacd. Factory function for a general polynomial model.

x iﬁxb: optional : sequence of integers with the same length as beta0 that determines which parameters are held ﬁxed. 31 of the ODRPACK User’s Guide if you absolutely must set the value here. covy. rptﬁle=None. .odr. ﬁx. Use the method set_iprint postinitialization for a more readable interface. meta]) odr_error odr_stop The ODR class gathers all information and coordinates the running of the The Data class stores the data to ﬁt. Members of instances of the ODR class have the same names as the arguments to the initialization routine. See p. covx.10. we. Use the method set_job post-initialization for a more readable interface. fjacb. Optional if model provides an “estimate” function to estimate these values. iﬁxb. Release 0. errﬁle=None.x that determines which input observations are treated as ﬁxed. a value > 0 makes the parameter free. iﬁxx: optional : an array of integers with the same shape as data.. stpb=None.. ﬁx. iprint=None. beta0. y. 404 Chapter 3. sy. Parameters data: : instance of the Data class model: : instance of the Model class beta0: : a rank-1 sequence of initial parameter values. iﬁxb=None. fjacd. wd. iwork=None) The ODR class gathers all information and coordinates the running of the main ﬁtting routine. job: optional : an integer telling ODRPACK what tasks to perform. maxit=None. a value > 0 makes it free. model. 33-34 of the ODRPACK User’s Guide if you absolutely must set the value here.SciPy Reference Guide. ndigit=None. sx. delta0. The Output class stores the output of an ODR run. Reference . The RealData class stores the weightings as actual standard deviations class scipy. One can use a sequence of length m (the dimensionality of the input observations) to ﬁx some dimensions for all observations. sclb=None. meta]) Model(fcn[. y. work=None. . beta0=None. The Model class stores information about the function you wish to ﬁt. delta0=None. stpd=None. extra_args.]) Data(x[.ODR(data.. taufac=None. partol=None. model[. job=None. A value of 0 ﬁxes the observation.]) Output(output) RealData(x[. See pp. scld=None. delta0: optional : a (double-precision) ﬂoat array to hold the initial values of the errors in the input variables.. A value of 0 ﬁxes the parameter. iprint: optional : an integer telling ODRPACK what to print. iﬁxx=None. Must be same shape as data. sstol=None.dev6665 Classes ODR(data.0.

shape == (m.odr) 405 . scld: optional : array (scld.11. If scld. stpd: optional : array (stpd.0. Again. sstol must be less than 1. taufac must be less than 1. The default value is 1.shape == (m. For restarts. stpb: optional : sequence (len(stpb) == len(beta0)) of relative step sizes to compute ﬁnite difference derivatives wrt the parameters. Specify them yourself if the automatic procedure goes awry. then the values are broadcast to all observations. Orthogonal distance regression (scipy. 3. these factors are automatically computed if you do not provide them. If stpd is a rank-1 array with length m (the dimensionality of the input variable). taufac: optional : ﬂoat specifying the initial trust region.10.). sclb: optional : sequence (len(stpb) == len(beta0)) of scaling factors for the parameters.x.)) of scaling factors for the errors in the input variables. Release 0. Normally appropriate scaling factors are computed if this argument is not speciﬁed.x.dev6665 errﬁle: optional : string with the ﬁlename to print ODRPACK errors to.shape == data. maxit is the total number of iterations performed and defaults to 50.shape == (m. The initial trust region is equal to taufac times the length of the ﬁrst computed Gauss-Newton step. sstol: optional : ﬂoat specifying the tolerance for convergence based on the relative change in the sum-of-squares. partol: optional : ﬂoat specifying the tolerance for convergence based on the relative change in the estimated parameters. maxit: optional : integer specifying the maximum number of iterations to perform. maxit is the number of additional iterations to perform and defaults to 10. Do Not Open This File Yourself! rptﬁle: optional : string with the ﬁlename to print ODRPACK summaries to. Do Not Open This File Yourself! ndigit: optional : integer specifying the number of reliable digits in the computation of the function. The purpose of these scaling factors are to scale all of the parameters to around unity.shape == data. then the scaling factors are broadcast to all observations. For ﬁrst runs. The default value is eps**(1/2) where eps is the smallest value such that 1 + eps > 1 for double precision computation on the machine.SciPy Reference Guide.shape or stpd. partol must be less than 1.shape or scld.)) of relative step sizes to compute ﬁnite difference derivatives wrt the input variable errors. The default value is eps**(2/3) for explicit models and eps**(1/3) for implicit models.

See the ODRPACK User’s Guide for a full explanation of how these weights are used in the algorithm.output. Release 0. Each argument is attached to the member of the instance of the same name. then the Data instance can only be used to ﬁt with implicit models where the dimensionality of the response is equal to the speciﬁed value of y. y=None. If wd = 0. we weights the effect a deviation in the response variable has on the ﬁt. If we is a rank-1 array of length n (the number of data points). then the i’th element is the weight for the i’th response variable observation (single-dimensional only).Data(x. If we is a rank-2 array of shape (q. The structures of x and y are described in the Model class docstring. Basically. wd=None.output. a higher value of the weight for a particular data point makes a deviation at that point more detrimental to the ﬁt. These arguments heavily use the structured arguments feature of ODRPACK to conveniently and ﬂexibly support all options. then the covariant weighting matrix for each observation is set to the identity matrix (so each dimension of each observation has the same weight).dev6665 work: optional : array to hold the double-valued working data for ODRPACK. q).10. n). If the ﬁt is implicit. then we[:. we=None.SciPy Reference Guide. then this is the full covariant weighting matrix broadcast to each observation.run() or ODR. When restarting. 406 Chapter 3. we – if we is a scalar. takes the value of self. If we is a rank-3 array of shape (q. ﬁx=None. takes the value of self.work. output: : an instance if the Output class containing all of the returned data from an invocation of ODR. q. If we is a rank-2 array of shape (q. then this vector is the diagonal of the covariant weighting matrix for all data points. If y is an integer. then we[:. then only a positive scalar value is used. If we is a rank-1 array of length q (the dimensionality of the response variable).0.iwork. then that value is used for all data points (and all dimensions of the input variable). meta is an freeform dictionary for application-speciﬁc use. iwork: optional : array to hold the integer-valued working data for ODRPACK. the structure of these arguments has the n’th dimensional axis ﬁrst. Reference . When restarting.odr. then that value is used for all data points (and all dimensions of the response variable). n). wd – if wd is a scalar. To handle multidimensional inputs and responses easily. meta={}) The Data class stores the data to ﬁt. The structures of wd and we are described below.restart() Methods restart run set_iprint set_job class scipy.:. wd weights the effect a deviation in the input variable has on the ﬁt.i] is the full speciﬁcation of the covariant weighting matrix for each observation.i] is the diagonal of the covariant weighting matrix for the i’th observation.

freeform dictionary for metadata Methods set_meta class scipy.e fcn(beta. The initialization method stores these into members of the same name. implicit=0. Orthogonal distance regression (scipy. at the least. x) –> y fjacb – Jacobian of fcn wrt the ﬁt parameters beta fjacb(beta.x that determines which input observations are treated as ﬁxed. and fjacd. x) –> @f_i(x. m). If wd is a rank-3 array of shape (m.i] is the diagonal of the covariant weighting matrix for the i’th observation. The estimate object takes an instance of the Data class. one can provide a function that will provide reasonable starting values for the ﬁt parameters possibly given the set of data. (beta. A value of 0 ﬁxes the observation. and fjacd operate on NumPy arrays and return a NumPy array. fjacb=None. n). If wd is a rank-1 array of length n (the number of data points). If wd is a rank-2 array of shape (m. fjacb. then the i’th element is the weight for the i’th input variable observation (single-dimensional only).:.SciPy Reference Guide.dev6665 If wd is a rank-1 array of length m (the dimensionality of the input variable). m. x) ~= 0 and there is no y data to ﬁt against meta – optional freeform dictionary of metadata for the model Note that the fcn. meta=None) The Model class stores information about the function you wish to ﬁt. If wd is a rank-2 array of shape (m. fjacb. x) –> @f_i(x. speciﬁes that the model is implicit. if TRUE.Model(fcn. estimate=None.0. One can use a sequence of length m (the dimensionality of the input observations) to ﬁx some dimensions for all observations. extra_args=None. Also.11. fjacd=None. then this vector is the diagonal of the covariant weighting matrix for all data points.i] is the full speciﬁcation of the covariant weighting matrix for each observation. extra_args should be a tuple of extra arguments to pass to fcn. and optionally stores functions which compute the Jacobians used during ﬁtting. then wd[:. It stores the function itself. then this is the full covariant weighting matrix broadcast to each observation. Here are the rules for the shapes of the argument and return arrays: 3. a value > 0 makes it free. ﬁx – ﬁx is the same as iﬁxx in the class ODR. It is an array of integers with the same shape as data.B)/@B_j fjacd – Jacobian of fcn wrt the (possibly multidimensional) input variable fjacd(beta. fcn – ﬁt function fcn(beta. meta – optional. x) + extra_args) estimate – provide estimates of the ﬁt parameters from the data: estimate(data) –> estbeta implicit – boolean variable which. then wd[:.odr.B)/@x_j extra_args – if speciﬁed. i.10.odr) 407 . Each will be called like the following: apply(fcn. n). Release 0.

y = array([[2.beta)[l.Output(output) The Output class stores the output of an ODR run.). then x is rank-1 array. i. If q == 1. optional ﬂoat. 38). then y is a rank-1 array.) If the input data is multi-dimensional. optional ndarray.j.e.shape = (q. Takes one argument for initialization. beta = array([B_1.i] = @f_l(X.. as output by ODRPACK (cf.B)/@B_k evaluated at the i’th data point.. If m == 1. B_2. y.SciPy Reference Guide. then the return array’s shape is (m. optional dict. it has the same shape as the input data array passed to odr().0.]]). then y is a rank-2 array. Sum of squares of delta error. Reason for returning. the shape is (q.. Indices into work for drawing out values (cf. only the return array’s shape is (q. [3. & dictionaries recursively.]. then the return array is only rank-2 and with shape (p.. ODRPACK UG p. n) such that fjacb(x. Release 0.e. Standard errors of the estimated parameters...odr.. Sum of squares of eps error. Residual variance.k. . n is the number of observations.beta)[l. 2.. . Array of x + delta. n). i.shape = (m.]]). Final work array. p. Notes The attributes listed as “optional” above are only present if odr was run with full_output=1.. of shape (q.. x. Reference . fjacd – as with fjacb.e. n) such that fjacd(x. Methods set_meta class scipy. of shape (p. n). the return value from the function odr. n) where q is the dimensionality of the response variable. 408 Chapter 3. . info interpreted into English. optional Estimated parameter values. optional ﬂoat. Covariance matrix of the estimated parameters. x. optional ﬂoat. . of shape (p. B_p]) fjacb – if the response variable is multi-dimensional. If m == q == 1. y. [2.. Attributes beta sd_beta cov_beta delta eps xplus y res_var sum_sqare sum_square_delta sum_square_eps inv_condnum rel_error work work_ind info stopreason Methods pprint Support to pretty-print lists.dev6665 x – if the input data is single-dimensional. . Array of estimated errors in input variables. i. i.shape = (n. Array y = fcn(x + delta).. 3.) If the response variable is multidimensional..p). of same shape as y. optional list of str. then the return array’s shape is (q. optional ndarray. y = array([2. 4. optional ndarray.shape = (n..i] = @f_l(X. then x is a rank-2 array..B)/@X_j at the i’th data point. x = array([[1. Array of estimated errors in response variables.. n) In all cases. 2.). Relative error in function values computed within fcn.. the shape is (n. 6. x = array([1. 83). m. y – if the response variable is single-dimensional. . ODRPACK UG p.e. optional int.. If q == 1. optional ﬂoat. . Inverse condition number (cf. optional ﬂoat. 77). ndarray ndarray ndarray ndarray. i. of same shape as x. optional ﬂoat. m is the dimensionality of the input data. 4.e. Sum of squares error.]. 4. ODRPACK UG p. beta – rank-1 array of length p where p is the number of parameters.]).]). tuples. optional ndarray.).10. n).

meta is an freeform dictionary for application-speciﬁc use. sx=None.Data(x. a value > 0 makes it free.ﬁx and ODR.0.RealData(x. y=None. we[i] = numpy.. partol=-1. errﬁle=None. y.]) scipy.odr(fcn. The weights needed for ODRPACK are generated on-the-ﬂy with __getattr__ trickery. One can use a sequence of length m (the dimensionality of the input observations) to ﬁx some dimensions for all observations. we=None./numpy. sx and sy are standard deviations of x and y and are converted to weights by dividing 1.odr. y=None. To handle multidimensional inputs and responses easily. stpb=None.10. See the ODRPACK User’s Guide for a full explanation of how these weights are used in the algorithm. extra_args=None. If y is an integer.SciPy Reference Guide.odr_stop Functions odr(fcn. we=None.odr. Release 0.x that determines which input observations are treated as ﬁxed. iﬁxb=None.odr. then the Data instance can only be used to ﬁt with implicit models where the dimensionality of the response is equal to the speciﬁed value of y. the structure of these arguments has the n’th dimensional axis ﬁrst. wd=None.odr. meta={}) The RealData class stores the weightings as actual standard deviations and/or covariances. Setting both will raise an exception. The structures of x and y are described in the Model class docstring. x[. taufac=0. wd weights the effect a deviation in the input variable has on the ﬁt. sclb=None. full_output=0) class scipy.odr_error exception scipy. iﬁxx=None.0.0. x. fjacb.q) These arguments follow the same structured argument conventions as wd and we only restricted by their natures: sx and sy can’t be rank-3. job=0.odr) 409 . iwork=None. Same with sy and covy. but covx and covy can be. ﬁx=None.power(sx. Methods set_meta exception scipy. maxit=-1. rptﬁle=None. ﬁx=None. beta0. iprint=0. Basically. 2) covx and covy are arrays of covariance matrices and are converted to weights by performing a matrix inversion on each observation’s covariance matrix. ndigit=0. 3.shape == (n. wd = 1. meta={}) The Data class stores the data to ﬁt. wd=None.11.inv(covy[i]) # i in range(len(covy)) # if covy. stpd=None. The argument and member ﬁx is the same as Data. A value of 0 ﬁxes the observation. wd. These arguments heavily use the structured arguments feature of ODRPACK to conveniently and ﬂexibly support all options.0.odr.g.dev6665 class scipy. beta0. a higher value of the weight for a particular data point makes a deviation at that point more detrimental to the ﬁt. y. we weights the effect a deviation in the response variable has on the ﬁt.0 by their squares.. E. fjacd=None. covx=None. The structures of wd and we are described below. scld=None. fjacb=None. work=None. Orthogonal distance regression (scipy. Each argument is attached to the member of the instance of the same name. covy=None.g. Only set either sx or covx (not both).q. sy=None. we.linalg. sstol=-1.iﬁxx: It is an array of integers with the same shape as data. E. .

dev6665 we – if we is a scalar. then this vector is the diagonal of the covariant weighting matrix for all data points. a value > 0 makes it free. If we is a rank-3 array of shape (q. freeform dictionary for metadata Methods set_meta set_meta(**kwds) Update the metadata dictionary with the keywords and data provided by keywords. m).:. If wd = 0. It is an array of integers with the same shape as data. One can use a sequence of length m (the dimensionality of the input observations) to ﬁx some dimensions for all observations. ﬁx – ﬁx is the same as iﬁxx in the class ODR. then this is the full covariant weighting matrix broadcast to each observation. n). then the covariant weighting matrix for each observation is set to the identity matrix (so each dimension of each observation has the same weight). n). Release 0. If wd is a rank-2 array of shape (m. then the i’th element is the weight for the i’th input variable observation (single-dimensional only). If wd is a rank-1 array of length m (the dimensionality of the input variable). If the ﬁt is implicit. If wd is a rank-1 array of length n (the number of data points). q). then the i’th element is the weight for the i’th response variable observation (single-dimensional only).i] is the full speciﬁcation of the covariant weighting matrix for each observation. If we is a rank-1 array of length q (the dimensionality of the response variable). If wd is a rank-2 array of shape (m. 410 Chapter 3. wd – if wd is a scalar.i] is the diagonal of the covariant weighting matrix for the i’th observation. then this is the full covariant weighting matrix broadcast to each observation. A value of 0 ﬁxes the observation. then that value is used for all data points (and all dimensions of the input variable). n). then we[:. fjacd=None.0.odr. then wd[:. then that value is used for all data points (and all dimensions of the response variable). fjacb=None. meta=None) The Model class stores information about the function you wish to ﬁt. extra_args=None. Examples data. Reference . If we is a rank-2 array of shape (q. then this vector is the diagonal of the covariant weighting matrix for all data points.i] is the full speciﬁcation of the covariant weighting matrix for each observation.10. title=”Ag110 + Ag108 Decay”) class scipy. then wd[:.Model(fcn. Lab 26”. If we is a rank-1 array of length n (the number of data points).set_meta(lab=”Ph 7.SciPy Reference Guide.x that determines which input observations are treated as ﬁxed. then only a positive scalar value is used. estimate=None. meta – optional. If wd is a rank-3 array of shape (m. then we[:. implicit=0. If we is a rank-2 array of shape (q. n). q.i] is the diagonal of the covariant weighting matrix for the i’th observation.:. m.

.shape = (n. then the return array is only rank-2 and with shape (p. x) –> y fjacb – Jacobian of fcn wrt the ﬁt parameters beta fjacb(beta.. 4. i. Orthogonal distance regression (scipy. The estimate object takes an instance of the Data class. y = array([[2. B_p]) fjacb – if the response variable is multi-dimensional. y – if the response variable is single-dimensional.e. 3. extra_args should be a tuple of extra arguments to pass to fcn.i] = @f_l(X. The initialization method stores these into members of the same name.. n). y = array([2..shape = (q. x) –> @f_i(x. and optionally stores functions which compute the Jacobians used during ﬁtting. y. fjacb. n). if TRUE. i. i. p. (beta.0. it has the same shape as the input data array passed to odr(). and fjacd.]). n). m. x) ~= 0 and there is no y data to ﬁt against meta – optional freeform dictionary of metadata for the model Note that the fcn. then x is a rank-2 array.shape = (m.e. .beta)[l. n is the number of observations.10. n) where q is the dimensionality of the response variable. x.. 3. 2.) If the response variable is multidimensional. i. i. at the least.i] = @f_l(X.]). then y is a rank-1 array. Methods set_meta set_meta(**kwds) Update the metadata dictionary with the keywords and data provided here. If q == 1. 4.B)/@B_j fjacd – Jacobian of fcn wrt the (possibly multidimensional) input variable fjacd(beta. 2. Each will be called like the following: apply(fcn.e..]]).]]). [2. beta – rank-1 array of length p where p is the number of parameters. and fjacd operate on NumPy arrays and return a NumPy array..). fjacb.. . then the return array’s shape is (q.. B_2. then y is a rank-2 array.odr) 411 . one can provide a function that will provide reasonable starting values for the ﬁt parameters possibly given the set of data. beta = array([B_1.) If the input data is multi-dimensional. then the return array’s shape is (m..k. [3. the shape is (q. If m == q == 1. m is the dimensionality of the input data. Release 0.. the shape is (n.11. x = array([[1.. only the return array’s shape is (q.e. 6. y.]. If q == 1. If m == 1. . Also.. n) such that fjacb(x. x.shape = (n. .e.dev6665 It stores the function itself. x) + extra_args) estimate – provide estimates of the ﬁt parameters from the data: estimate(data) –> estbeta implicit – boolean variable which. x = array([1. then x is rank-1 array. i.e fcn(beta.beta)[l. n) In all cases..SciPy Reference Guide.j. fcn – ﬁt function fcn(beta.B)/@X_j at the i’th data point..B)/@x_j extra_args – if speciﬁed. Here are the rules for the shapes of the argument and return arrays: x – if the input data is single-dimensional. 4. x) –> @f_i(x.. fjacd – as with fjacb..B)/@B_k evaluated at the i’th data point.. n) such that fjacd(x. . speciﬁes that the model is implicit..]. .

iprint=None. See pp. 31 of the ODRPACK User’s Guide if you absolutely must set the value here. Parameters data: : instance of the Data class model: : instance of the Model class beta0: : a rank-1 sequence of initial parameter values. Release 0. A value of 0 ﬁxes the observation. Use the method set_job post-initialization for a more readable interface. Optional if model provides an “estimate” function to estimate these values. Must be same shape as data. A value of 0 ﬁxes the parameter. rptﬁle=None. a value > 0 makes it free. beta0=None.x that determines which input observations are treated as ﬁxed. Do Not Open This File Yourself! ndigit: optional : 412 Chapter 3. sstol=None. Reference .dev6665 Examples set_meta(name=”Exponential”.0. errﬁle=None. stpb=None. iﬁxb=None. iprint: optional : an integer telling ODRPACK what to print. Members of instances of the ODR class have the same names as the arguments to the initialization routine. sclb=None. job: optional : an integer telling ODRPACK what tasks to perform. iﬁxx=None. See p. job=None. a value > 0 makes the parameter free. equation=”y = a exp(b x) + c”) class scipy. One can use a sequence of length m (the dimensionality of the input observations) to ﬁx some dimensions for all observations. Use the method set_iprint postinitialization for a more readable interface. scld=None.odr. delta0=None. delta0: optional : a (double-precision) ﬂoat array to hold the initial values of the errors in the input variables. taufac=None. errﬁle: optional : string with the ﬁlename to print ODRPACK errors to. iﬁxx: optional : an array of integers with the same shape as data. work=None. stpd=None. maxit=None.SciPy Reference Guide. Do Not Open This File Yourself! rptﬁle: optional : string with the ﬁlename to print ODRPACK summaries to.ODR(data. partol=None. ndigit=None. model.x iﬁxb: optional : sequence of integers with the same length as beta0 that determines which parameters are held ﬁxed.10. iwork=None) The ODR class gathers all information and coordinates the running of the main ﬁtting routine. 33-34 of the ODRPACK User’s Guide if you absolutely must set the value here.

shape or scld. partol: optional : ﬂoat specifying the tolerance for convergence based on the relative change in the estimated parameters. maxit: optional : integer specifying the maximum number of iterations to perform.x. output: : 3.0. sclb: optional : sequence (len(stpb) == len(beta0)) of scaling factors for the parameters. For ﬁrst runs. The default value is eps**(1/2) where eps is the smallest value such that 1 + eps > 1 for double precision computation on the machine.shape == (m. work: optional : array to hold the double-valued working data for ODRPACK. Orthogonal distance regression (scipy. When restarting. The purpose of these scaling factors are to scale all of the parameters to around unity. then the values are broadcast to all observations. taufac: optional : ﬂoat specifying the initial trust region.). then the scaling factors are broadcast to all observations. maxit is the number of additional iterations to perform and defaults to 10.)) of scaling factors for the errors in the input variables.work. takes the value of self.shape == data. taufac must be less than 1. stpb: optional : sequence (len(stpb) == len(beta0)) of relative step sizes to compute ﬁnite difference derivatives wrt the parameters. If scld. maxit is the total number of iterations performed and defaults to 50. For restarts. Release 0.10. Again. takes the value of self. The default value is eps**(2/3) for explicit models and eps**(1/3) for implicit models. stpd: optional : array (stpd.iwork.shape or stpd.)) of relative step sizes to compute ﬁnite difference derivatives wrt the input variable errors.shape == (m. If stpd is a rank-1 array with length m (the dimensionality of the input variable). scld: optional : array (scld.dev6665 integer specifying the number of reliable digits in the computation of the function.shape == (m. Specify them yourself if the automatic procedure goes awry.odr) 413 . sstol must be less than 1.output. sstol: optional : ﬂoat specifying the tolerance for convergence based on the relative change in the sum-of-squares.11. When restarting.output. The initial trust region is equal to taufac times the length of the ﬁrst computed Gauss-Newton step.shape == data. iwork: optional : array to hold the integer-valued working data for ODRPACK. Normally appropriate scaling factors are computed if this argument is not speciﬁed.SciPy Reference Guide. The default value is 1.x. partol must be less than 1. these factors are automatically computed if you do not provide them.

If iprint is not set manually or with this method. The default value from class initialization is for all of these options set to 0. The permissible values are 0. so_iter=None. iteration.restart() Methods restart run set_iprint set_job restart(iter=None) Restarts the run with iter more iterations. There are three reports: initialization. var_calc=None. iter_step=None. iter. ﬁnal=None. then ODRPACK defaults to no printing. The argument iter_step (0 <= iter_step <= 9) speciﬁes how often to make the iteration report. Reference . If an argument is not speciﬁed. set_iprint(init=None. and “long report” respectively. 1. regardless of the other arguments. If no ﬁlename is speciﬁed with the member rptﬁle. and ﬁnal respectively. They are represented by the arguments init. run() Run the ﬁtting routine with all of the information given. and 2 representing “no report”. then ODRPACK prints to stdout. del_init=None. Returns output : Output instance This object is also assigned to the attribute . If the rptﬁle is None. optional ODRPACK’s default for the number of new iterations is 10. restart=None) Sets the “job” parameter is a hopefully comprehensible way. Returns output : Output instance This object is also assigned to the attribute . 1. Parameters iter : int. and ﬁnal reports.SciPy Reference Guide. “short report”.output . then no iteration report is made. so_init=None. so_ﬁnal=None) Set the iprint parameter for the printing of computation reports. then they are set in the iprint member. but one cannot specify to print to stdout but not a ﬁle since one can do that by not specifying a rptﬁle ﬁlename. Parameters ﬁt_type : {0.output . set_job(ﬁt_type=None. deriv=None. 2} int 0 -> explicit ODR 1 -> implicit ODR 414 Chapter 3.0.10. If iter_step == 0. If any of the arguments are speciﬁed here. the report will be made for every iter_step’th iteration starting with iteration one. iter=None. Release 0.run() or ODR.dev6665 an instance if the Output class containing all of the returned data from an invocation of ODR. One can tell ODRPACK to print to stdout in addition to the speciﬁed ﬁlename by setting the so_* arguments to this function. then any so_* arguments supplied will raise an exception. then the value is left as is.

odr) 415 .Output(output) The Output class stores the output of an ODR run. To initialize the input variable offsets by yourself. 31 of the ODRPACK User’s Guide only in that one cannot specify numbers greater than the last value for each variable. set del_init to 1 and put the offsets into the “work” variable correctly. 1.0. the ﬁtting procedure will change deriv to 0. 1} int 0 -> ﬁt is not a restart 1 -> ﬁt is a restart Notes The permissible values are different from those given on pg. 1. 3.odr.SciPy Reference Guide. ﬁnite differences. 1} int 0 -> initial input variable offsets set to 0 1 -> initial offsets provided by user in variable “work” restart : {0. Release 0. 3} int 0 -> forward ﬁnite differences 1 -> central ﬁnite differences 2 -> user-supplied derivatives (Jacobians) with results checked by ODRPACK 3 -> user-supplied derivatives. If one does not supply functions to compute the Jacobians.10.11. 2} int 0 -> calculate asymptotic covariance matrix and ﬁt parameter uncertainties (V_B. class scipy. s_B) using derivatives recomputed at the ﬁnal solution 1 -> calculate V_B and s_B using derivatives from last iteration 2 -> do not calculate V_B and s_B del_init : {0. 2. Notes The attributes listed as “optional” above are only present if odr was run with full_output=1.dev6665 2 -> ordinary least-squares deriv : {0. no checking var_calc : {0. Orthogonal distance regression (scipy. Takes one argument for initialization. as a default. the return value from the function odr.

we=None. tuples. Final work array. . & dictionaries recursively.odr. rptﬁle=None. info interpreted into English. scld=None. ODRPACK UG p. ftol.]) fmin_cg(f.SciPy Reference Guide.. . 416 Chapter 3. exception scipy. Residual variance. ftol.]) fmin_ncg(f. optional ﬂoat. iwork=None.. optional ﬂoat. sstol=-1.. 83). norm. args. optional ndarray. Minimize a function using the BFGS algorithm. x. norm. Dfun. full_output=0) 3. x0[. optional ﬂoat. ndarray ndarray ndarray ndarray. gtol. Sum of squares error. taufac=0. Inverse condition number (cf. optional ﬂoat.0. Sum of squares of delta error. Indices into work for drawing out values (cf. Covariance matrix of the estimated parameters. x0[. Release 0. Standard errors of the estimated parameters. optional Estimated parameter values.odr(fcn. extra_args=None. ndigit=0. as output by ODRPACK (cf. work=None. xtol. Sum of squares of eps error.p). xtol. fprime. Minimize the sum of squares of a set of equations. fjacb=None.. Reason for returning. optional ﬂoat. 77).. of shape (p. x0. args.0. optional ﬂoat. x0[. of shape (q. fprime.dev6665 Attributes beta sd_beta cov_beta delta eps xplus y res_var sum_sqare sum_square_delta sum_square_eps inv_condnum rel_error work work_ind info stopreason Methods pprint Support to pretty-print lists. x0[.odr.]) fmin_powell(func. sclb=None. of same shape as y. x0[. job=0. stpd=None.). optional int.optimize) 3. errﬁle=None. . maxit=-1. beta0.0... maxiter. wd=None. of same shape as x. Array of x + delta. args. optional dict. .. iﬁxx=None. . partol=-1. iprint=0.odr.odr_error exception scipy.. fhess_p.]) leastsq(func. y. Reference . optional ndarray.10. optional ndarray. Relative error in function values computed within fcn.. args.12. ODRPACK UG p. iﬁxb=None. fjacd=None. Minimize a function using modiﬁed Powell’s method.odr_stop scipy. fprime[.12 Optimization and root ﬁnding (scipy.). full_output. Minimize a function using a nonlinear conjugate gradient algorithm. Array y = fcn(x + delta). Array of estimated errors in response variables..1 Optimization General-purpose fmin(func. 38). of shape (p. args. Array of estimated errors in input variables. . Minimize a function using the Newton-CG method. stpb=None. pprint() Pretty-print important results. optional list of str.0. gtol. optional ndarray. ODRPACK UG p.]) fmin_bfgs(f.]) Minimize a function using the downhill simplex algorithm. fhess..

12. callback : callable Called after each iteration.fmin(func. Other Parameters xtol : ﬂoat Relative error in xopt acceptable for convergence.dev6665 scipy. retall=0. disp=1.optimize.*args) The objective function to be minimized. Release 0. iter : int Number of iterations performed.optimize) 417 . Returns xopt : ndarray Parameter that minimizes function. ftol : number Relative error in func(xopt) acceptable for convergence.SciPy Reference Guide. x0. ftol=0.0001. Parameters func : callable func(x. where xk is the current parameter vector. 2 : Maximum number of iterations reached. maxfun=None.*args). f(x. as callback(xk). callback=None) Minimize a function using the downhill simplex algorithm. i. args : tuple Extra arguments passed to func.0001. Optimization and root ﬁnding (scipy. funcalls : int Number of function calls made. maxiter=None. maxfun : number Maximum number of function evaluations to make. warnﬂag : int 1 : Maximum number of function evaluations made.0.e. x0 : ndarray Initial guess. disp : bool 3.10. full_output : bool Set to True if fopt and warnﬂag outputs are desired. allvecs : list Solution at each iteration. maxiter : int Maximum number of iterations to perform. full_output=0. args=(). fopt : ﬂoat Value of function at minimum: fopt = func(xopt). xtol=0.

direc=None) Minimize a function using modiﬁed Powell’s method. funcalls : int Number of function calls made. Parameters func : callable f(x. Returns xopt : ndarray Parameter which minimizes func. args=().dev6665 Set to True to print convergence messages. maxiter=None. x0 : ndarray Initial guess. xtol=0.0.0001. callback=None. ftol=0. callback(xk).SciPy Reference Guide. x0. called after each iteration.0001. Called as 418 Chapter 3. Release 0. maxfun=None. Reference . where xk is the current parameter vector. scipy. direc : ndarray Initial direction set. fopt : number Value of function at minimum: fopt = func(xopt). direc : ndarray Current direction set. Notes Uses a Nelder-Mead simplex algorithm to ﬁnd the minimum of function of one or more variables. retall : bool Set to True to return list of solutions at each iteration. callback : callable An optional user-supplied function. retall=0. disp=1. warnﬂag : int Integer warning ﬂag: 1 : Maximum number of function evaluations. 2 : Maximum number of iterations. allvecs : list List of solutions at each iteration. full_output=0. iter : int Number of iterations.fmin_powell(func. args : tuple Extra arguments passed to func.*args) Objective function to be minimized.optimize.10.

full_output : bool If True. and warnﬂag are returned.12. callback : callable 3. gtol=1.4901161193847656e-08. full_output=0.*args) Function which computes the gradient of f. gtol : ﬂoat Stop when norm of gradient is less than gtol.10. Inf is max. maxiter=None.fmin_cg(f. x0 : ndarray Initial guess. Parameters f : callable f(x. print convergence messages.0000000000000001e-05. retall : bool If True. fprime : callable f’(x. ftol : ﬂoat Relative error in func(xopt) acceptable for convergence. maxiter : int Maximum number of iterations to perform. args : tuple Extra arguments passed to f and fprime. norm : ﬂoat Order of vector norm to use.0. fprime=None. epsilon=1.optimize) 419 . funcalls. x0. norm=inf. -Inf is min. disp : bool If True. Release 0. maxfun : int Maximum number of function evaluations to make. retall=0. use this value for the step size (can be scalar or vector). epsilon : ﬂoat or ndarray If fprime is approximated. disp=1.*args) Objective function to be minimized. Optimization and root ﬁnding (scipy. callback=None) Minimize a function using a nonlinear conjugate gradient algorithm.dev6665 Other Parameters xtol : ﬂoat Line-search error tolerance. return a list of the solution at each iteration.optimize. Notes Uses a modiﬁcation of Powell’s method to ﬁnd the minimum of a function of N variables. scipy. iter. xi. fopt. args=().SciPy Reference Guide. direc.

fopt : ﬂoat Minimum value found. whose gradient is given by fprime using the nonlinear conjugate gradient algorithm of Polak and Ribiere. Parameters f : callable f(x. scipy. Notes Optimize the function. Reference . ‘Numerical Optimization’. func_calls. f(xopt). f(xopt) == fopt. where xk is the current parameter vector.0. then this vector containing the result at each iteration is returned. full_output=0. args=(). Other Parameters maxiter : int Maximum number of iterations to perform. 120-122. i. x0. warnﬂag : int 1 : Maximum number of iterations exceeded. allvecs : ndarray If retall is True (see other parameters below). f. grad_calls : int The number of gradient calls made. fprime : callable f’(x.0000000000000001e-05. epsilon=1. grad_calls. func_calls : int The number of function_calls made. and warnﬂag in addition to xopt. disp : bool Print convergence message if True. retall : bool Return a list of results at each iteration if True. Called as callback(xk).fmin_bfgs(f. called after each iteration.optimize. callback=None) Minimize a function using the BFGS algorithm. gtol=1.e. maxiter=None. full_output : bool If True then return fopt.SciPy Reference Guide.dev6665 An optional user-supplied function. pg. retall=0. x0 : ndarray Initial guess.10.4901161193847656e-08. norm=inf. disp=1. Returns xopt : ndarray Parameters which minimize f.*args) 420 Chapter 3. fprime=None. 1999.*args) Objective function to be minimized. 2 : Gradient and/or function calls not changing. Release 0. See Wright & Nocedal.

grad_calls. callback : callable An optional user-supplied function to call after each iteration. disp : bool Print convergence message if True.dev6665 Gradient of f.return fopt.12. Only returned if retall is True. Bopt : ndarray Value of 1/f’‘(xopt). f(xopt) == fopt. gtol : ﬂoat Gradient norm must be less than gtol before succesful termination. -Inf is min) epsilon : int or ndarray If fprime is approximated. i. the inverse hessian matrix. use this value for the step size. Optimization and root ﬁnding (scipy.SciPy Reference Guide. where xk is the current parameter vector. Other Parameters maxiter : int Maximum number of iterations to perform. grad_calls : int Number of gradient calls made. gopt : ndarray Value of gradient at minimum. args : tuple Extra arguments passed to f and fprime. i. Returns xopt : ndarray Parameters which minimize f. norm : ﬂoat Order of norm (Inf is max. func_calls : int Number of function_calls made. full_output : bool If True. allvecs : list Results at each iteration. func_calls. Called as callback(xk). 2 : Gradient and/or function calls not changing.10. fopt : ﬂoat Minimum value.e. 3. which should be near 0. and warnﬂag in addition to xopt. Release 0.0. f’(xopt). warnﬂag : integer 1 : Maximum number of iterations exceeded.e.optimize) 421 .

i. disp=1. 422 Chapter 3. args=(). i. scipy. p.*args) Function which computes the Hessian of f times an arbitrary vector.fmin_ncg(f. Notes Optimize the function. fcalls : int Number of function calls made. callback=None) Minimize a function using the Newton-CG method. args : tuple Extra arguments passed to f. 1999. and fhess (the same set of extra arguments is supplied to all of these functions). gcalls : int Number of gradient calls made. retall=0.e. hcalls : int Number of hessian calls made. epsilon=1.0000000000000001e-05. fprime.10. and Shanno (BFGS) See Wright. f(xopt) == fopt. Returns xopt : ndarray Parameters which minimizer f. Reference . Parameters f : callable f(x. Release 0. epsilon : ﬂoat or ndarray If fhess is approximated.p. Fletcher. fprime. Called as callback(xk).*args) Function to compute the Hessian matrix of f. fopt = f(xopt). x0. f. fhess_p=None.4901161193847656e-08.dev6665 retall : bool Return a list of results at each iteration if True. whose gradient is given by fprime using the quasi-Newton method of Broyden.*args) Gradient of f. maxiter=None. 198.SciPy Reference Guide. and Nocedal ‘Numerical Optimization’. use this value for the step size. avextol=1. fhess=None. fopt : ﬂoat Value of the function at xopt. pg. full_output=0. callback : callable An optional user-supplied function which is called after each iteration. where xk is the current parameter vector. fprime : callable f’(x.*args) Objective function to be minimized.optimize.e. fhess_p : callable fhess_p(x. x0 : ndarray Initial guess.0. fhess_p. fhess : callable fhess(x. Goldfarb.

x = arg min(sum(func(y)**2. then the hessian product will be approximated using ﬁnite differences on fprime. ftol=1. Dfun=None. Release 0. full_output : bool If True.0. fhess_p must compute the hessian times an arbitrary vector. Dfun : callable A function or method to compute the Jacobian of func with derivatives across the rows. retall : bool If True. the Jacobian will be estimated. 1 : Maximum number of iterations exceeded. ‘Numerical Optimization’. if retall is True (see below). print convergence message.optimize.49012e-08. diag=None) Minimize the sum of squares of a set of equations. then fhess_p will be ignored.optimize) 423 . If fhess is provided. disp : bool If True. ﬁnite-differences on fprime are used to compute it.axis=0)) y Parameters func : callable should take at least one (possibly length N vector) argument and returns M ﬂoating point numbers. col_deriv=0. Other Parameters avextol : ﬂoat Convergence is assumed when the average relative error in the minimizer falls below this amount.49012e08. return the optional outputs.12. scipy. return a list of results at each iteration.SciPy Reference Guide. If this is None. args : tuple Any extra arguments to func are placed in this tuple. epsfcn=0. maxfev=0. args=(). If neither fhess nor fhess_p is provided. factor=100. allvecs : list The result at each iteration. full_output : bool 3. x0 : ndarray The starting estimate for the minimization.10. Notes Only one of fhess_p or fhess need to be given.0. xtol=1. pg.0. Optimization and root ﬁnding (scipy. If it is not given. See Wright & Nocedal. 1999.dev6665 warnﬂag : int Warnings generated by the algorithm. full_output=0. x0.leastsq(func. maxiter : int Maximum number of iterations to perform. 140. gtol=0.

because there is no transpose operation). the covariance of the estimate can be approximated. xtol : ﬂoat Relative error desired in the approximate solution. .1. 100).’ipvt’ : an integer array of length N which defines a permutation matrix. diag : sequence N positive entries that serve as a scale factors for the variables. This matrix must be multiplied by the residual standard deviation to get the covariance of the parameter estimates – see curve_ﬁt. Together with ipvt. Reference . then 100*(N+1) is the maximum where N is the number of elements in x0.’fvec’ : the function evaluated at the output . None if a singular matrix encountered (indicates very ﬂat curvature in some direction). stored column wise.’fjac’ : A permutation of the R matrix of a QR factorization of the final approximate Jacobian matrix. it is assumed that the relative errors in the functions are of the order of the machine precision. where r is upper triangular 424 Chapter 3. cov_x : ndarray Uses the fjac and ipvt optional outputs to construct an estimate of the jacobian around the solution. Returns x : ndarray The solution (or the result of the last iteration for an unsuccessful call). maxfev : int The maximum number of calls to the function. epsfcn : ﬂoat A suitable step length for the forward-difference approximation of the Jacobian (for Dfun=None). infodict : dict a dictionary of optional outputs with the key s: . Should be in interval (0.0. If zero. factor : ﬂoat A parameter determining the initial step bound (factor * || diag * x||).dev6665 non-zero to return all optional outputs.10. p. such that fjac*p = q*r. Release 0. If epsfcn is less than the machine precision.’nfev’ : the number of function calls . ftol : ﬂoat Relative error desired in the sum of squares.SciPy Reference Guide. gtol : ﬂoat Orthogonality desired between the function vector and the columns of the Jacobian. col_deriv : bool non-zero to specify that the Jacobian function computes derivatives down the columns (faster.

b) Minimize a function func using the L-BFGS-B algorithm. : the vector (transpose(q) * fvec). fprime : callable fprime(x. f_eqcons.b ||_2 for x>=0. ier : int An integer ﬂag.]) fmin_tnc(func.0000000000000001e-05. *args) 3. In either case...fmin_l_bfgs_b(func.f(xdata. eqcons.]) fmin_slsqp(func. approx_grad=0. args. . mesg : str A string message giving information about the cause of failure.. using gradient information. maxfun=15000. args=(). x0[. This approximation assumes that the objective function is based on the difference between some observed target data (ydata) and a (non-linear) function of the parameters f(xdata.12. disp=None) Minimize a function func using the L-BFGS-B algorithm. x0. axis=0) Constrained (multivariate) fmin_l_bfgs_b(func. Parameters func : callable f(x.]) nnls(A. scipy. Release 0. args. Minimize a function with variables subject to bounds. the optional output variable ‘mesg’ gives more information. the solution was found. iprint=-1. Otherwise.]) fmin_cobyla(func. fprime=None.SciPy Reference Guide. params) so that the objective function is min params sum((ydata .optimize) 425 .. m=10. params))**2. fprime. *args) Function to minimise. . Optimization and root ﬁnding (scipy.’qtf’ with diagonal elements of nonincreasing magnitude. Minimize a function using the Constrained Optimization BY Linear Minimize a function using Sequential Least SQuares Programming Solve argmin_x || Ax . params) func(params) = ydata . . pgtol=1. x0[.10. the solution was not found... bounds=None. x0.0. 3 or 4.0. x0 : ndarray Initial guess. x0[. Column j of p is column ipvt(j) of the identity matrix..f(xdata. cons[. If it is equal to 1.dev6665 . factr=10000000. Notes “leastsq” is a wrapper around MINPACK’s lmdif and lmder algorithms. . epsilon=1e-08.. cov_x is a Jacobian approximation to the Hessian of the least squares objective function. fprime. 2. args.optimize.

2 if stopped for another reason.) factr : ﬂoat The iteration stops when (f^k . 1e7 for moderate accuracy.. pgtol : ﬂoat The iteration will stop when max{|proj g_i | i = 1. n} <= pgtol where pg_i is the i-th component of the projected gradient. optional If zero.|f^{k+1}|. If None. • d[’warnﬂag’] is . for numerically calculating the gradient iprint : int Controls the frequency of output.f^{k+1})/max{|f^k|. max) pairs for each element in x.dev6665 The gradient of func. then no output.0 for extremely high accuracy.. Returns x : ndarray Estimated position of the minimum. . Typical values for factr are: 1e12 for low accuracy.1 if too many function evaluations.1} <= factr * eps. bounds : list (min. m : int The maximum number of variable metric corrections used to deﬁne the limited memory matrix. Use None for one of min or max when there is no bound in that direction. . approx_grad : bool Whether to approximate the gradient numerically (in which case func returns only the function value). unless approx_grad is True in which case func returns only f. deﬁning the bounds on that parameter. *args)). maxfun : int Maximum number of function evaluations. epsilon : ﬂoat Step size used when approx_grad is True. then this over-rides iprint. iprint < 0 means no output. If positive number.0 if converged. which is automatically generated by the code. Release 0. d : dict Information dictionary.0. g = func(x. where eps is the machine precision. .10.SciPy Reference Guide. given in d[’task’] 426 Chapter 3. (The limited memory BFGS method does not store the full hessian but uses this many terms in an approximation to it. f : ﬂoat Value of func at the minimum. disp : int.. args : tuple Arguments to pass to func and fprime. then func returns the function value and the gradient (f. 10. Reference .

disp=None) Minimize a function with variables subject to bounds. rescale=-1. xtol=-1. L-BFGS-B: Algorithm 778: L-BFGS-B. FORTRAN routines for large scale bound constrained optimization (1997). bounds=None. Nocedal. *args) Gradient of func. If None. but we expect that all publications describing work using this software . 1190-1208. approx_grad : bool If true. Optimization and root ﬁnding (scipy. x0 : list of ﬂoats Initial estimate of minimum. Parameters func : callable func(x. fprime=None. References •R. epsilon=1e-08. stepmx=0. Byrd and J. max) pairs for each element in x. Lu and J.1 (released in 1997).10. SIAM Journal on Scientiﬁc and Statistical Computing . Use None or +/-inf for one of min or max when there is no bound in that direction. Byrd. ACM Transactions on Mathematical Software. maxfun=None.560. If None. 5. 550 . H. messages=15.12. then func must return the function value and the gradient (f. accuracy=0.nwu. pp. P. scale : list of ﬂoats Scaling factors to apply to each variable. or all commercial products using it. •C. A Limited Memory Algorithm for Bound Constrained Optimization. Zhu.g = func(x. and Jorge Nocedal <nocedal@ece. (1995). args : tuple Arguments to pass to function. R.SciPy Reference Guide. Richard Byrd. where f is the value of the function and g its gradient (a list of ﬂoats). bounds : list (min. eta=-1. approximate the gradient numerically. fmin=0. Should return f and g. the minimization is aborted. If the function returns None. fprime : callable fprime(x. It was written by Ciyou Zhu.dev6665 • d[’grad’] is the gradient at the minimum (should be 0 ish) • d[’funcalls’] is the number of function calls made. offset=None. It carries the following condition for use: This software is freely available. x0.edu>. quote at least one of the references given below. deﬁning the bounds on that parameter. pp. Release 0. Nocedal. *args) Function to minimize. using gradient information. scipy. Num. ftol=-1.0.optimize. 16. pgtol=-1. *args)). scale=None. approx_grad=0. 4. Vol 23. the factors are up-low for interval bounded variables and 1+|x] fo the others. H.fmin_tnc(func. Defaults to None offset : ﬂoat 3.optimize) 427 . maxCGit=1. args=(). Notes License of L-BFGS-B (Fortran code): The version included here (in fortran code) is 2.

the offsets are (up+low)/2 for interval bounded variables and x for the others. If xtol < 0. Defaults to 0.0. disp : int Integer interface to messages. fmin : ﬂoat Minimum function value estimate. If maxCGit == 0.0. Returns x : list of ﬂoats The solution. 5 = all messages maxCGit : int Maximum number of hessian*vector evaluations per main iteration.0. rescale is set to 1. xtol : ﬂoat Precision goal for the value of x in the stopping criterion (after applying x scaling factors). the direction chosen is -gradient if maxCGit < 0. Defaults to -1. Defaults to 0. never rescale. Defaults to -1. If 0. May be increased during call. pgtol is set to 1e-2 * sqrt(accuracy). If ftol < 0. If too small. If None. set to sqrt(machine_precision). if < 0 or > 1. Setting it to 0. 0 = no message. maxfun : int Maximum number of function evaluation.0. messages : : Bit mask used to select messages display during minimization values deﬁned in the MSGS dict. Defaults to MGS_ALL. 10*len(x0)).dev6665 Value to substract from each variable.min(50.0 is not recommended. ftol : ﬂoat Precision goal for the value of f in the stoping criterion. Defaults to -1. Defaults to None. eta : ﬂoat Severity of the line search. If < 0. pgtol : ﬂoat Precision goal for the value of the projected gradient in the stopping criterion (after applying x scaling factors).SciPy Reference Guide. xtol is set to sqrt(machine_precision). 428 Chapter 3.0. ftol is set to 0.3. rescale at each iteration.n/2)). If a large value.10. rescale : ﬂoat Scaling factor (in log10) used to trigger f value rescaling. maxfun is set to max(100. Release 0. it will be set to 10. maxCGit is set to max(1. If <= machine_precision. stepmx : ﬂoat Maximum step for the line search. if None. Defaults to 0. If pgtol < 0. Reference . Defaults to -1.25. accuracy : ﬂoat Relative precision for ﬁnite difference calculations.0 defaults to -1. set to 0.

disp=None) Minimize a function using the Constrained Optimization BY Linear Approximation (COBYLA) method. maxfun=1000. Optimization and root ﬁnding (scipy.0.SciPy Reference Guide. rhoend=0.0001. 0 implies no output. must all be >=0 (a single function if only 1 constraint). 2. consargs : tuple Extra arguments to pass to constraint functions (default of None means use same extra arguments as those passed to func). Deprecated.12.y) = x*y subject to the constraints x**2 + y**2 < 1 and y > 0: >>> def objective(x): . iprint : {0. Examples Minimize the objective function f(x.10. rc : int Return code as deﬁned in the RCSTRINGS dict. scipy. 1. args : tuple Extra arguments to pass to function.0.optimize) 429 . 1. *args). Release 0. x0 : ndarray Initial guess.optimize. args=(). cons : sequence Constraint functions.. return x[0]*x[1] . x0. Parameters func : callable Function to minimize.dev6665 nfeval : int The number of function evaluations.fmin_cobyla(func. >>> def constr1(x): 3.. cons. rhobeg : : Reasonable initial changes to the variables.. 3} Over-rides the iprint interface. Returns x : ndarray The argument that minimises f. iprint=1. Preferred.. 2. consargs=None. maxfun : int Maximum number of function evaluations. Use () for no extra arguments. rhobeg=1. Each function takes the parameters x as its ﬁrst argument. 3} Controls the frequency of output. disp : {0. rhoend : : Final accuracy in the optimization (not precisely guaranteed). In the form func(x.

If f_eqcons is speciﬁed.. eqcons=[].0 in a successfully optimized problem.. Release 0. disp=None. xu1). [0. args=(). ieqcons : list A list of functions of length n such that ieqcons[j](x0. Reference . return 1 . eqcons : list A list of functions of length n such that eqcons[j](x0.*args) == 0. fprime_ieqcons=None. iprint=1.] fprime : callable f(x. constr2].0. bounds : list A list of tuples specifying the lower and upper bound for each independent variable [(xl0.071067E-01 array([-0. epsilon=1.1].fmin_slsqp(func.0. f_eqcons : callable f(x.dev6665 . fprime=None. rhoend=1e-7) Normal return from subroutine COBYLA NFVALS = 64 F =-5.0 in a successfully optimized problem. If f_ieqcons is speciﬁed. sqrt(2)/2). f_eqcons=None. bounds=[].. scipy.10.SciPy Reference Guide. ieqcons=[ ].*args) >= 0. >>> fmin_cobyla(objective. ieqcons is ignored.optimize.(xl1.*args) Objective function. acc=9.*args) A function that evaluates the partial derivatives of func.. 0. iter=100.4901161193847656e-08) Minimize a function using Sequential Least SQuares Programming Python interface function for the SLSQP Optimization subroutine originally implemented by Dieter Kraft..9999999999999995e-07.000000E-01 X =-7. eqcons is ignored..0 in a successfully optimized problem. fprime_eqcons=None.(x[0]**2 + x[1]**2) . x0..998401E-14 The exact solution is (-sqrt(2)/2. xu0). x0 : 1-D ndarray of ﬂoat Initial guess for the independent variable(s).. fprime_eqcons : callable f(x. >>> def constr2(x): .. f_ieqcons=None. return x[1] . 0.70710685.*args) 430 Chapter 3.. Parameters func : callable f(x.*args) Returns a 1-D array in which each element must equal 0..*args) Returns a 1-D ndarray in which each element must be greater or equal to 0.071069E-01 7. f_ieqcons : callable f(x0. full_output=0.70710671]) MAXCV = 1.0 in a successfully optimized problem. [constr1.

Release 0. its : int. output ﬁnal objective function and summary information. args : sequence Additional arguments passed to func and fprime. len(x0) ).optimize) 431 . len(x0) ). *args) that returns the m by n array of equality constraint normals. if full_output is true The number of iterations.10.dev6665 A function of the form f(x. iter : int The maximum number of iterations. full_output : bool If False. Returns x : ndarray of ﬂoat The ﬁnal minimizer of func. *args) that returns the m by n array of inequality constraint normals. fprime_ieqcons : callable f(x. Optimization and root ﬁnding (scipy. The array returned by fprime_eqcons should be sized as ( len(eqcons). the normals will be approximated.0. The array returned by fprime_ieqcons should be sized as ( len(ieqcons). return only the minimizer of func (default). 3. If not provided.*args) A function of the form f(x. if full_output is true The exit mode from the optimizer (see below). fx : ndarray of ﬂoat. imode : int. if full_output is true The ﬁnal value of the objective function. the normals will be approximated. acc : ﬂoat Requested accuracy. iprint : int The verbosity of fmin_slsqp : • iprint <= 0 : Silent operation • iprint == 1 : Print summary upon completion (default) • iprint >= 2 : Print status of each iterate and summary disp : int Over-rides the iprint interface (preferred).SciPy Reference Guide. smode : string. epsilon : ﬂoat The step size for ﬁnite-difference derivative estimates. Otherwise. if full_output is true Message describing the exit mode from the optimizer.12. If not provided.

nnls(A. Function evaluation required (f & c) More equality constraints than independent variables More than 3*n iterations in LSQ subproblem Inequality constraints incompatible Singular matrix E in LSQ subproblem Singular matrix C in LSQ subproblem Rank-deficient equality constraint subproblem HFTI Positive directional derivative for linesearch Iteration limit exceeded Examples Examples are given in the tutorial. x0. b) Solve argmin_x || Ax . 432 Chapter 3. Available ones are ‘fast’. Parameters A : ndarray Matrix A as shown above.anneal(func. Minimize a function over a given range by brute force. Returns x : ndarray Solution vector. Notes This is a wrapper for NNLS. .9999999999999995e-07. Tf=9. scipy. maxiter=400.b ||_2 for x>=0. rnorm : ﬂoat The residual. b : ndarray Right-hand side vector. *args) Function to be optimized. ‘cauchy’.optimize. || Ax-b ||_2.]) brute(func. upper=100. lower=-100.0. x0[. ‘boltzmann’ Parameters func : callable f(x. feps=9. Global anneal(func. args. learn_rate=0. n=1. ranges[.5.SciPy Reference Guide. maxeval=None.0. schedule=’fast’. full_output..10.]) Minimize a function using simulated annealing. T0=None. full_output=0. boltzmann=1. dwell=50) Minimize a function using simulated annealing. scipy. . schedule..0. Release 0. args. m=1. Reference . quench=1.optimize.. maxaccept=None.dev6665 Notes Exit modes are deﬁned as follows -1 0 1 2 3 4 5 6 7 8 9 : : : : : : : : : : : Gradient evaluation required (g & a) Optimization terminated successfully.. Ns.0.F.0. Schedule is a schedule class implementing the annealing schedule. args=().9999999999999998e-13.

Optimization and root ﬁnding (scipy. maxaccept : int Maximum changes to accept. retval : int Flag indicating stopping condition: 3. lower. schedule : base_schedule Annealing schedule to use (a class). args : tuple Extra parameters to func. quench. maxeval : int Maximum function evaluations. full_output : bool Whether to return optional outputs. learn_rate : ﬂoat Scale constant for adjusting guesses. T0 : ﬂoat Initial Temperature (estimated as 1. Release 0. n : ﬂoat Parameters to alter fast_sa schedule.SciPy Reference Guide. feps : ﬂoat Stopping relative error tolerance for the function value in last four coolings. m. dwell : int The number of times to search the space at each temperature. upper : ﬂoat or ndarray Lower and upper bounds on x. Returns xmin : ndarray Point giving smallest value found.12.2 times the largest cost-function deviation over random points in the range).dev6665 x0 : ndarray Initial guess. maxiter : int Maximum cooling iterations. Tf : ﬂoat Final goal temperature.0.optimize) 433 . boltzmann : ﬂoat Boltzmann constant in acceptance test (increase for less stringent test at each temperature).10.

full_output=0. ﬁnish=<function fmin at 0x35929b0>) Minimize a function over a given range by brute force.10. full_output : bool If True. ranges. iters : int Number of cooling iterations.*args) Objective function to be minimized. Ns=20. giving minimum over the grid.brute(func. Ns : int Default number of samples. grid : tuple Representation of the evaluation grid. accept : int Number of tests accepted.0.mgrid. ranges : tuple Each element is a tuple of parameters or a slice object to be handed to numpy. feval : int Number of function evaluations.optimize. Jout : ndarray Function values over grid: Jout = func(*grid). 434 Chapter 3. Release 0. It has the same length as x0. args : tuple Extra arguments passed to function.dev6665 0 1 2 3 4 : : : : : Cooled to global optimum Cooled to final temperature Maximum function evaluations Maximum cooling iterations reached Maximum accepted query locations reached Jmin : ﬂoat Minimum value of function found. Parameters func : callable f(x.SciPy Reference Guide. Reference . T : ﬂoat Final temperature. scipy. fval : int Function value at minimum. if those are not provided. Returns x0 : ndarray Value of arguments to func. return the evaluation grid. args=().

Given a function and distinct initial points. xc that bracket the minimum of the function f(xa) > f(xb) < f(xc).... print messages. args. x1. x2. ierr : int An error ﬂag (0 if converged. return the minimum of the function isolated to a fractional precision of tol.fminbound(func. Optimization and root ﬁnding (scipy. tol. xb. args=(). 0 : no message printing.. search in the downhill direction (as deﬁned by the initital points) and return new points xa.. full_output : bool If True.10.SciPy Reference Guide. xtol=1.]) brent(func[.0. xb. maxfun=500. fval : number The function value at the minimum point. Scalar function minimizers fminbound(func.dev6665 Notes Find the minimum of a function evaluated on a grid given by the tuple ranges. full_output=0. xtol : ﬂoat The convergence tolerance.]) golden(func[. . Given a function of one-variable and a possible bracketing interval. 1 : non-convergence notiﬁcation messages only. x2[.0000000000000001e-05. Parameters func : callable f(x. return the minimum of the function isolated to a fractional precision of tol.optimize. args : tuple Extra arguments passed to function. Release 0. scipy. args.. Returns xopt : ndarray Parameters (over given interval) which minimize the objective function. x1. 3 : print iteration results. return optional outputs. 2 : print a message on convergence too.optimize) 435 . xa. args. . disp : int If non-zero. . x1. grow_limit. args. full_output]) bracket(func[. full_output. x2 : ﬂoat or array scalar The optimization bounds. brack.]) Bounded minimization for scalar functions.12. disp=1) Bounded minimization for scalar functions. 1 if maximum number of function calls reached). xtol. Given a function of one-variable and a possible bracketing interval. 3. maxfun : int Maximum number of function evaluations allowed.*args) Objective function to be minimized (must accept and return scalars). brack. tol.

optimize. xa. Parameters func : callable func(x.0. Notes Finds a local minimizer of the scalar function func in the interval x1 < xopt < x2 using Brent’s method.dev6665 numfunc : int The number of function calls made. scipy. scipy. It doesn’t always mean that obtained solution will satisfy xa<=x<=xb Parameters func : callable f(x.0. xa=0. search in the downhill direction (as deﬁned by the initital points) and return new points xa.golden(func.c). brack=None. args=(). where (a<b<c) and func(b) < func(a). return the minimum of the function isolated to a fractional precision of tol. xb.SciPy Reference Guide. xc that bracket the minimum of the function f(xa) > f(xb) < f(xc).b. brack : tuple Triple (a. grow_limit=110. xb : ﬂoat Bracketing interval. then they are assumed to be a starting interval for a downhill bracket search (see bracket). maxiter : int Maximum number of iterations to perform. args=().0. return optional outputs. passed to func. args : tuple Additional arguments (if present). 436 Chapter 3.*args) Objective function to minimize.0. (See brent for auto-bracketing). tol : ﬂoat x tolerance stop criterion full_output : bool If True.optimize. Notes Uses analog of bisection method to decrease the bracketed interval. grow_limit : ﬂoat Maximum grow limit.10. If bracket consists of two numbers (a. Release 0.4901161193847656e-08. tol=1.*args) Objective function to minimize. full_output=0) Given a function of one-variable and a possible bracketing interval.bracket(func. xb=1.func(c). maxiter=1000) Given a function and distinct initial points. it doesn’t always mean that obtained solution will satisfy a<=x<=c. c). args : tuple Additional arguments (if present). passed to func. Reference .

fval. If bracket consists of two numbers (a. brack=None. full_output : bool If True. return all output args (xmin. maxiter=500) Given a function of one-variable and a possible bracketing interval.optimize) 437 . xdata.SciPy Reference Guide. fval : ﬂoat Optimum value. ydata.b.12. iter : int Number of iterations. f. full_output=0. p0. funcalls : int Number of function evaluations made. sigma]) Use non-linear least squares to ﬁt a function.func(c). ydata. funcalls : int Number of objective function evaluations made.optimize.curve_fit(f.0. to data. xb. Optimization and root ﬁnding (scipy. scipy. Release 0.*args) Objective function. *params) + eps 3. brack : tuple Triple (a. Assumes ydata = f(xdata. xdata. fc : ﬂoat Objective function values in bracket. tol=1. Notes Uses inverse parabolic interpolation when possible to speed up convergence of golden section method. fa. to data. scipy.optimize. p0=None. Returns xmin : ndarray Optimum point. **kw) Use non-linear least squares to ﬁt a function.10. sigma=None. return the minimum of the function isolated to a fractional precision of tol.c) where (a<b<c) and func(b) < func(a).12. args=(). Parameters func : callable f(x.c) then they are assumed to be a starting interval for a downhill bracket search (see bracket).48e-08. **kw[. iter. f.brent(func.dev6665 Returns xa. xc : ﬂoat Bracket. fb. 3. funcalls).2 Fitting curve_fit(f. it doesn’t always mean that the obtained solution will satisfy a<=x<=c. args : Additional arguments (if present).

. Notes The algorithm uses the Levenburg-Marquardt algorithm: scipy.4. Release 0. *popt) . b. if given. c): .).5) >>> yn = y + 0. Reference . This vector. Returns popt : array Optimal values for the parameters so that the sum of the squared error of f(xdata.optimize import curve_fit >>> def func(x. sigma : None or N-length sequence If not None.. If None.. pcov = curve_fit(func.ydata is minimized pcov : 2d array The estimated covariance of popt. return a*np. then the initial values will all be 1 (if the number of parameters for the function can be determined using introspection..N)-shaped array for functions with k predictors. The independent variable where the data is measured.2*np. it represents the standard-deviation of ydata.random..normal(size=len(x)) >>> popt. xdata : An N-length sequence or an (k.exp(-b*x) + c >>> x = np.. 1. f(x. or M-length sequence Initial guess for the parameters.) p0 : None. ydata : N-length sequence The dependent data — nominally f(xdata.0. otherwise a ValueError is raised).3.10. The diagonals provide the variance of the parameter estimate. .optimize. will be used as weights in the least-squares problem.linspace(0..SciPy Reference Guide. a. Additional keyword arguments are passed directly to that algorithm.50) >>> y = func(x. 2.5. Examples >>> import numpy as np >>> from scipy. x.dev6665 Parameters f : callable The model function. yn) 438 Chapter 3.leastsq. It must take the independent variable as the ﬁrst argument and the parameters to ﬁt as separate remaining arguments. 0. scalar.

. optional The routine converges when a root is known to lie within xtol of the value return. and error is raised. Release 0.]) brenth(f. xtol : number. Our code diverges a bit from standard presentations: we choose a different formula for the extrapolation step. rtol=4. optional if convergence is not achieved in maxiter iterations. maxiter. xtol. http://mathworld. r). a zero of f between a and b.9999999999999998e-13. maxiter. args. Generally considered the best of the rootﬁnding routines here. xtol. full_output : bool.optimize) 439 f is called by apply(f. and f(a) and f(b) must have opposite signs. args.b].dev6665 3. and inverse quadratic interpolation. x0[. . the return value is (x. maxiter.. args. args. including [PressEtal1992]. a. 3. Find root of f in [a. b[. It is a safe version of the secant method that uses inverse quadratic extrapolation.com/BrentsMethod. rtol. Find root of f in [a.optimize. full_output=False. a. and r is a RootResults object.4408920985006262e16. The routine modiﬁes this to take into account the relative precision of doubles. . interval bisection. If full_output is True. a. scipy.3 Root ﬁnding Scalar functions brentq(f. . . Description: Uses the classic Brent (1973) method to ﬁnd a zero of the function f on the sign changing interval [a .12. Should be >= 0. xtol. args : tuple. optional If full_output is False... . Brent (1973) claims convergence is guaranteed for functions computable within [a. where x is the root. b. args.. rtol. Must be >= 0. f must be a continuous function. maxiter : number.b]. a. b]. rtol. b : number The other end of the bracketing interval [a. b[. fprime..html. It is sometimes known as the van Wijngaarden-Deker-Brent method.wolfram. xtol=9. Optimization and root ﬁnding (scipy.SciPy Reference Guide. tol.. rtol. Parameters f : function Python function returning a number. and [a.10. a.0.b]. (x)+args).b].b]. Another description can be found Another description is at in a recent edition of Numerical Recipes. b[. It should be easy to understand the algorithm just by reading our code. b[. optional containing extra arguments for the function f. args=(). Brent’s method combines root bracketing.12. the root is returned. a : number One end of the bracketing interval [a. [Brent1973] provides the classic description of the algorithm.]) newton(func. xtol. maxiter=100. Find a root of a function in an interval. maxiter. Find a zero using the Newton-Raphson or secant method. maxiter]) Find a root of a function in given interval. disp=True) Find a root of a function in given interval.]) bisect(f. f must be continuous.]) ridder(f.brentq(f.b] must be a sign changing interval. Return ﬂoat..

In particular. Returns x0 : ﬂoat Zero of f between a and b. newton scalar ﬁxed_point Notes f must be continuous.10. Reference .9999999999999998e-13. b : number 440 Chapter 3. fmin_cg. f must be continuous. golden. bracket n-dimensional fsolve one-dimensional brentq. disp=True) Find root of f in [a. See Also: multivariate fmin. scipy. r. brute local fminbound. Parameters f : function Python function returning a number. The version here is by Chuck Harris. ridder.b]. full_output=False. and f(a) and f(b) must have opposite signs. Release 0. fmin_powell. maxiter=100. It is a safe version of the secant method that uses hyperbolic extrapolation.. fmin_ncg nonlinear leastsq constrained fmin_l_bfgs_b. fmin_tnc.optimize. rtol=4. a : number One end of the bracketing interval [a.0.4408920985006262e16. bool} optional If True. fmin_cobyla global anneal. brenth. b. f(a) and f(b) can not have the same signs.b].SciPy Reference Guide. Generally on a par with the brent routine. brent. args=(). There was a paper back in the 1980’s .converged is True if the routine converged. a. bisect. raise RuntimeError if the algorithm didn’t converge.. but not as heavily tested. r : RootResults (present if full_output = True) Object containing information about the convergence. fmin_bfgs. A variation on the classic Brent routine to ﬁnd a zero of the function f between the arguments a and b that uses hyperbolic extrapolation instead of inverse quadratic extrapolation.dev6665 disp : {True.brenth(f. f(a) and f(b) must have opposite signs. xtol=9.

SciPy Reference Guide. Release 0. The routine modiﬁes this to take into account the relative precision of doubles.b].ridder(f.dev6665 The other end of the bracketing interval [a. maxiter=100.9999999999999998e-13. full_output : bool. full_output=False. Must be >= 0. optional f is called by apply(f.12. scipy. The routine modiﬁes this to take into account the relative precision of doubles. raise RuntimeError if the algorithm didn’t converge. maxiter : number. 3.0. Optimization and root ﬁnding (scipy. r. Returns x0 : ﬂoat Zero of f between a and b. Should be >= 0. optional if convergence is not achieved in maxiter iterations. optional containing extra arguments for the function f. a. and error is raised. optional The routine converges when a root is known to lie within xtol of the value return.b]. b : number The other end of the bracketing interval [a. disp : {True. and r is a RootResults object. xtol : number. and error is raised. Must be >= 0.4408920985006262e16. (x)+args). r). r : RootResults (present if full_output = True) Object containing information about the convergence.optimize) 441 . and f(a) and f(b) must have opposite signs. disp=True) Find a root of a function in an interval. f must be continuous. the root is returned. optional The routine converges when a root is known to lie within xtol of the value return. optional if convergence is not achieved in maxiter iterations. a : number One end of the bracketing interval [a.b]. In particular. args=(). args : tuple. xtol : number. xtol=9. optional If full_output is False. b.converged is True if the routine converged. rtol=4. If full_output is True. maxiter : number. args : tuple.10. bool} optional If True. where x is the root.optimize. the return value is (x. Parameters f : function Python function returning a number. Should be >= 0.

the return value is (x. If full_output is False. optional 442 Chapter 3.dev6665 containing extra arguments for the function f. disp=True) Find root of f in [a. Reference . r). xtol : number. xtol=9. (x)+args).b]. If full_output is True.10. Ridders’ method is faster than bisection. and f(a) and f(b) must have opposite signs. full_output=False. raise RuntimeError if the algorithm didn’t converge. args=().SciPy Reference Guide. r : RootResults (present if full_output = True) Object containing information about the convergence.optimize. See Also: brentq. b. bisect. f(a) and f(b) can not have the same signs. brenth. The routine used here diverges slightly from standard presentations in order to be a bit more careful of tolerance. full_output : bool. disp : {True. where x is the root. a : number One end of the bracketing interval [a.4408920985006262e16. the root is returned. a. In particular. References [Ridders1979] scipy. Basic bisection routine to ﬁnd a zero of the function f between the arguments a and b.converged is True if the routine converged.0. rtol=4. r. A description can also be found in any recent edition of Numerical Recipes. Slow but sure. b : number The other end of the bracketing interval [a.9999999999999998e-13.bisect(f. optional f is called by apply(f. [Ridders1979] provides the classic description and source of the algorithm. maxiter=100. Release 0. Returns x0 : ﬂoat Zero of f between a and b. newton fixed_point scalar ﬁxed-point ﬁnder Notes Uses [Ridders1979] method to ﬁnd a zero of the function f between the arguments a and b.b]. and r is a RootResults object. but not generally as fast as the Brent rountines. bool} optional If True. Parameters f : function Python function returning a number.b]. f must be continuous.

the root is returned. args : tuple. tol=1.b.SciPy Reference Guide. See Also: fixed_point scalar ﬁxed-point ﬁnder fsolve – n-dimensional root-ﬁnding scipy. fprime=None. the return value is (x. args=(). tol : ﬂoat. r : RootResults (present if full_output = True) Object containing information about the convergence. If full_output is True. Should be >= 0. disp : {True. Parameters func : function The function whose zero is wanted. and r is a RootResults object. full_output : bool. args : tuple. Must be >= 0.12.. maxiter : number.c. Returns x0 : ﬂoat Zero of f between a and b.converged is True if the routine converged. If it is None.10. r. optional f is called by apply(f. fprime : {None.optimize) 443 . where a..48e-08. The routine modiﬁes this to take into account the relative precision of doubles. x0 : ﬂoat An initial estimate of the zero that should be somewhere near the actual zero. otherwise the secant method is used.dev6665 The routine converges when a root is known to lie within xtol of the value return. where x is the root. r). are extra arguments that can be passed in the args parameter. then the secant method is used. 3.c. Optimization and root ﬁnding (scipy. optional If full_output is False. optional Extra arguments to be used in the function call. Find a zero of the function func given a nearby starting point x0. optional The derivative of the function when available and convenient. The default is None. and error is raised. raise RuntimeError if the algorithm didn’t converge. function}. x0.0. In particular. It must be a function of a single variable of the form f(x. maxiter=50) Find a zero using the Newton-Raphson or secant method. The Newton-Rapheson method is used if the derivative fprime of func is provided. bool} optional If True... optional if convergence is not achieved in maxiter iterations.newton(func.).a. (x)+args). optional containing extra arguments for the function f. Release 0.b.optimize.

12. [1.dev6665 The allowable error of the zero value. bisect. array >>> from scipy. optional Maximum number of iterations. Uses Steffensen’s Method using Aitken’s Del^2 convergence acceleration. These solvers ﬁnd x for which F(x) = 0. Reference . pg. fsolve Notes The convergence rate of the Newton-Rapheson method is quadratic while that of the secant method is somewhat less. args.]) >>> c2 = array([3.optimize. 1.3]. xtol=1e-08. brenth. 80 Examples >>> from numpy import sqrt. where func(x)=x. the stopping criterion used here is the step size and there is no quarantee that a zero has been found. Consequently the result should be veriﬁed. ridder. However.fixed_point(func. See Burden. Safer algorithms are brentq. maxiter : int. and bisect. 5. Release 0. 1. args=(). This means that if the function is well behaved the actual error in the estimated zero is approximatly the square of the requested tolerance up to roundoff error. xtol. maxiter=500) Find the point where func(x) == x Given a function of one or more variables and a starting point. Fixed point ﬁnding: fixed_point(func. maxiter]) Find the point where func(x) == x scipy. ﬁnd a ﬁxed-point of the function: i.37228132]) Multidimensional Nonlinear solvers This is a collection of general-purpose nonlinear multidimensional solvers. Routines Large-scale nonlinear solvers: 444 Chapter 3. x0[.0.2. 5th edition. Both x and F can be multidimensional.e. x0. Returns zero : ﬂoat Estimated location where function is zero.c2)) array([ 1. args=(c1. c2): return sqrt(c1/(x+c2)) >>> c1 = array([10.4920333 . ridder. c1.]) >>> fixed_point(func. but they all require that the root ﬁrst be bracketed in an interval where the function changes sign. brenth.10.optimize import fixed_point >>> def func(x. Faires. “Numerical Analysis”. See Also: brentq. The brentq algorithm is recommended for general use in one dimemsional problems when such an interval has been found.SciPy Reference Guide.

Find a root of a function.]) broyden2(F. xin.]) diagbroyden(F.broyden1(F. iter. xin. 1. using a scalar Jacobian approximation.]) Large problem [0.. . 3. 1. hy = 1. iter. alpha.. using diagonal Broyden Jacobian approximation.optimize import newton_krylov from numpy import cosh. M. . 2. [1. using Broyden’s second Jacobian approximation. xin.]) Examples Small problem Find a root of a function. 0 P_top. Find a root of a function. iter. using a tuned diagonal Jacobian approximation.]) linearmixing(F.. . w0.. 1]: Suppose that we needed to solve the following integrodifferential equation on the square [0. zeros_like. f_tol=1e-14) >>> x array([ 4.71791677. P_bottom = 1. 75 hx.2*P[1:-1] + P[:-2]) / hx/hx 3. iter. **kw[. .. P_right = 0.0. **kw[. alpha. zeros # parameters nx.cos(x) + x[::-1] . 0 def residual(P): d2x = zeros_like(P) d2y = zeros_like(P) d2x[1:-1] = (P[2:] .dev6665 newton_krylov(F. . iter.04674914. xin. mgrid.. .. Release 0. . Find a root of a function. 1] × 2 1 2 1 P = 10 0 0 cosh(P ) dx dy with P (x. alpha.. **kw[. 3. **kw[. alpha. 4] >>> import scipy. using Krylov approximation for inverse Jacobian... alpha. iter. ny = 75. xin. 2.1].1. 1) = 1 and P = 0 elsewhere on the boundary of the square.]) General nonlinear solvers: broyden1(F. xin..1. 4...10. **kw[.]) Simple iterations: excitingmixing(F. alpha. xin.. **kw[.61756251]) >>> np.optimize) 445 . Find a root of a function. rdiff./(ny-1) P_left. Find a root of a function. The solution can be found using the newton_krylov solver: import numpy as np from scipy.]) anderson(F.. Find a root of a function.SciPy Reference Guide..optimize.. using (extended) Anderson mixing./(nx-1). >>> def F(x): . Optimization and root ﬁnding (scipy. return np.91158389.optimize >>> x = scipy. 2. iter. 3.. **kw[. using Broyden’s ﬁrst Jacobian approximation.cos(x) + x[::-1] array([ 1.12..[1.

]) broyden2(F.-1] + P[:. x0 : ndarray 446 Chapter 3.2 0.0 0. sol) plt. args. Find a root of a function.1:-1] = (P[:. using Broyden’s ﬁrst Jacobian approximation.. full_output=0.0 0. col_deriv=0.show() 1. Reference . float) sol = newton_krylov(residual. method=’lgmres’.max() # visualize import matplotlib. alpha.2*P[:..2 0. .SciPy Reference Guide.]) Find the roots of a function. epsfcn=0. Find a root of a function.10*cosh(P).2 0. factor=100.4 0. alpha. Return the roots of the (non-linear) equations deﬁned by func(x) = 0 given a starting estimate.:-2])/hy/hy d2y[:. xin. y.]) broyden1(F.0] + P_bottom)/hy/hy d2y[:. fprime=None.4 0. *args) A function that takes at least one (possibly vector) argument.mean()**2 # solve guess = zeros((nx.0 0.2*P[0] = (P_right .pyplot as plt x. xin. guess.dev6665 d2x[0] d2x[-1] = (P[1] .8 1. abs(residual(sol)).10.6 General nonlinear solvers: fsolve(func. .0.2*P[:.0.1] .colorbar() plt.4 0.-1] = (P_top .0 0.2 0.2:] .0 0. band=None.. scipy.. ny). 0:1:(ny*1j)] plt. Release 0.pcolor(x.-2])/hy/hy return d2x + d2y . args=().49012e08.0] = (P[:. x0[. x0.optimize.2*P[:.. maxfev=0. verbose=1) print ’Residual’. Parameters func : callable f(x.8 0.6 0.1:-1] + P[:.6 0.6 0. fprime. diag=None) Find the roots of a function. **kw[.8 0. xtol=1..4 0.2*P[-1] + P_left)/hx/hx + P[-2])/hx/hx d2y[:. **kw[. using Broyden’s second Jacobian approximation. y = mgrid[0:1:(nx*1j).fsolve(func. iter. . iter.

Release 0.10. mesg : str If no solution is found. epsfcn : ﬂoat 3. mesg details the cause of failure.dev6665 The starting estimate for the roots of func(x) = 0. Set to 1 if a solution was found. fprime : callable(x) A function to compute the Jacobian of func with derivatives across the rows. stored column wise ’r’: upper triangular matrix produced by QR factorization of same * matrix * ’qtf’: the vector (transpose(q) * fvec) * * * * ’nfev’: ’njev’: ’fvec’: ’fjac’: ier : int An integer ﬂag. return optional outputs. Other Parameters xtol : ﬂoat The calculation will terminate if the relative error between two consecutive iterates is at most xtol. full_output : bool If True. col_deriv : bool Specify whether the Jacobian function computes derivatives down the columns (faster. produced by the QR factorization of the final approximate Jacobian matrix. If zero.0. q. infodict : dict A dictionary of optional outputs with the keys: number of function calls number of Jacobian calls function evaluated at the output the orthogonal matrix. By default. then 100*(N+1) is the maximum where N is the number of elements in x0.optimize) 447 . maxfev : int The maximum number of calls to the function.and super-diagonals within the band of the Jacobi matrix. the Jacobian will be estimated. the Jacobi matrix is considered banded (only for fprime=None). otherwise refer to mesg for more information. because there is no transpose operation). Returns x : ndarray The solution (or the result of the last iteration for an unsuccessful call). Optimization and root ﬁnding (scipy.12. band : tuple If set to a two-sequence containing the number of sub.SciPy Reference Guide. args : tuple Any extra arguments to func.

SciPy Reference Guide.. 100). reduction_method=’restart’.2. f_rtol=None. . Has no extra parameters. iter : int. 448 Chapter 3.10. no rank reduction). f_tol=None. optional Number of iterations to make. maxiter=None. Notes fsolve is a wrapper around MINPACK’s hybrd and hybrj algorithms.) that gives the name of the method and values for additional parameters.dev6665 A suitable step length for the forward-difference approximation of the Jacobian (for fprime=None). • svd: keep only the most signiﬁcant SVD components. param2. optional Initial guess for the Jacobian is (-1/alpha). This method is also known as “Broyden’s good method”. • simple: drop oldest matrix column. max_rank : int.optimize. Has no extra parameters. verbose=False. Extra parameters: – to_retain‘: number of SVD components to retain when rank reduction is done. reduction_method : str or tuple. x0 : array-like Initial guess for the solution alpha : ﬂoat. factor : ﬂoat A parameter determining the initial step bound (factor * || diag * x||). Reference . iter=None. Should be in the interval (0. line_search=’armijo’. optional Method used in ensuring that the rank of the Broyden matrix stays low. If omitted (default).. Parameters F : function(x) -> f Function whose root to ﬁnd. Default is inﬁnity (ie. Can either be a string giving the name of the method. If epsfcn is less than the machine precision. xin. optional Maximum rank for the Broyden matrix. should take and return an array-like object.0. x_rtol=None. tol_norm=None. diag : sequence N positive entries that serve as a scale factors for the variables. max_rank=None. Default is ‘‘max_rank .broyden1(F. scipy. Release 0. it is assumed that the relative errors in the functions are of the order of the machine precision. or a tuple of the form (method. callback=None.. Methods available: • restart: drop all matrix columns. make as many as required to meet tolerances. param1. **kw) Find a root of a function. x_tol=None.1. alpha=None. using Broyden’s ﬁrst Jacobian approximation.

f_rtol : ﬂoat. If more are needed to meet convergence. Notes This algorithm implements the inverse Jacobian Quasi-Newton update H+ = H + (dx − Hdf )dx† H/(dx† Hdf ) which corresponds to Broyden’s ﬁrst Jacobian update J+ = J + (df − Jdx)dx† /dx† dx 3. tol_norm : function(vector) -> scalar. as determined from the Jacobian approximation. not used.0. It is called on every iteration as callback(x. optional Print status to stdout on every iteration. optional Absolute minimum step size. Defaults to ‘armijo’. optimization is terminated as successful. x_rtol : ﬂoat.optimize) 449 . If omitted. If the step size is smaller than this. optional Maximum number of iterations to make. maxiter : int. x_tol : ﬂoat. If omitted. optional Absolute tolerance (in max-norm) for the residual. Optimization and root ﬁnding (scipy. optional Which type of a line search to use to determine the step size in the direction given by the Jacobian approximation. NoConvergence is raised.10. Default is the maximum norm. Returns sol : array-like An array (of similar array type as x0) containing the ﬁnal solution.SciPy Reference Guide. line_search : {None. default is 6e-6. f) where x is the current solution and f the corresponding residual. optional Norm to use in convergence check. Release 0. ‘wolfe’}. ‘armijo’ (default). optional Optional callback function. f_tol : ﬂoat. callback : function. not used. optional Relative minimum step size. not used. optional Relative tolerance for the residual.dev6665 verbose : bool. If omitted. If omitted. Raises NoConvergence : When a solution was not found.12.

If more are needed to meet convergence. Default is ‘‘max_rank . no rank reduction). This method is also known as “Broyden’s bad method”. optional Number of iterations to make. max_rank : int. maxiter=None. param2.dev6665 References [vR] scipy. • svd: keep only the most signiﬁcant SVD components. optional Initial guess for the Jacobian is (-1/alpha). default is 6e-6. alpha=None. or a tuple of the form (method. f_rtol=None.) that gives the name of the method and values for additional parameters. **kw) Find a root of a function. verbose=False. xin. Methods available: • restart: drop all matrix columns. If omitted. Reference . iter=None. make as many as required to meet tolerances. param1.SciPy Reference Guide.. tol_norm=None. reduction_method : str or tuple. . Extra parameters: – to_retain‘: number of SVD components to retain when rank reduction is done. Release 0. NoConvergence is raised. x_tol=None. max_rank=None. optional Method used in ensuring that the rank of the Broyden matrix stays low. Has no extra parameters. optional Absolute tolerance (in max-norm) for the residual. optional 450 Chapter 3. Can either be a string giving the name of the method.broyden2(F. optional Maximum rank for the Broyden matrix.optimize. If omitted (default). maxiter : int. iter : int. verbose : bool. reduction_method=’restart’. Has no extra parameters. Parameters F : function(x) -> f Function whose root to ﬁnd. f_tol=None..2. using Broyden’s second Jacobian approximation. x_rtol=None. f_tol : ﬂoat. optional Print status to stdout on every iteration..0.10. optional Maximum number of iterations to make. x0 : array-like Initial guess for the solution alpha : ﬂoat. • simple: drop oldest matrix column. callback=None. line_search=’armijo’. Default is inﬁnity (ie. should take and return an array-like object. f_rtol : ﬂoat.

3. inner_maxiter=20. x_rtol : ﬂoat. . line_search=’armijo’. optional Relative minimum step size.10. xin. optional Absolute minimum step size. not used. iter.newton_krylov(F.SciPy Reference Guide. alpha. f_rtol=None. not used.]) anderson(F.dev6665 Relative tolerance for the residual.0. x_rtol=None. If omitted. ‘wolfe’}. line_search : {None. rdiff=None. If omitted.]) Find a root of a function. outer_k=10.optimize. tol_norm : function(vector) -> scalar. Find a root of a function. x_tol : ﬂoat. method=’lgmres’. **kw) Find a root of a function. If omitted. f) where x is the current solution and f the corresponding residual. not used. callback=None.. verbose=False. scipy. using (extended) Anderson mixing. Default is the maximum norm. If the step size is smaller than this. Release 0.12. Defaults to ‘armijo’. . M. w0. **kw[. maxiter=None. Returns sol : array-like An array (of similar array type as x0) containing the ﬁnal solution. ‘armijo’ (default). as determined from the Jacobian approximation. References [vR] Large-scale nonlinear solvers: newton_krylov(F. rdiff. iter. f_tol=None. x_tol=None. optional Which type of a line search to use to determine the step size in the direction given by the Jacobian approximation. This method is suitable for solving large-scale problems. using Krylov approximation for inverse Jacobian.optimize) 451 .. callback : function.. tol_norm=None.. optimization is terminated as successful. Notes This algorithm implements the inverse Jacobian Quasi-Newton update H+ = H + (dx − Hdf )df † /(df † df ) corresponding to Broyden’s second method. Optimization and root ﬁnding (scipy. optional Optional callback function. Raises NoConvergence : When a solution was not found. optional Norm to use in convergence check. using Krylov approximation for inverse Jacobian. inner_M=None. iter=None. **kw[. xin. It is called on every iteration as callback(x. xin.

Reference . inner_M : LinearOperator or InverseJacobian Preconditioner for the inner Krylov iteration. Can be a string. method : {‘lgmres’.0. f_rtol : ﬂoat.. f_tol : ﬂoat. Release 0.sparse.sparse. with x giving the current point.linalg.linalg.. inner_tol. If omitted. optional Size of the subspace kept across LGMRES nonlinear iterations. See 452 Chapter 3. verbose : bool. >>> jac = BroydenFirst() >>> kjac = KrylovJacobian(inner_M=jac. NoConvergence is raised. optional Relative step size to use in numerical differentiation. inner_maxiter. ‘minres’} or function Krylov method to use to approximate the Jacobian. If omitted.linalg.sparse. : Parameters to pass on to the “inner” scipy. optional Relative tolerance for the residual.10.gmres for details. f) after each nonlinear step.dev6665 Parameters F : function(x) -> f Function whose root to ﬁnd.lgmres. maxiter : int. Note that you can use also inverse Jacobians as (adaptive) preconditioners. ‘bicgstab’. optional Print status to stdout on every iteration.SciPy Reference Guide. not used. should take and return an array-like object. iter : int. x0 : array-like Initial guess for the solution rdiff : ﬂoat. .linalg. scipy. or a function implementing the same interface as the iterative solvers in scipy.inverse).lgmres for details. optional Absolute tolerance (in max-norm) for the residual. For example. make as many as required to meet tolerances.sparse. x_tol : ﬂoat. If the preconditioner has a method named ‘update’. ‘gmres’. default is 6e-6. optional Number of iterations to make. If omitted (default). ‘cgs’. and f the current function value. outer_k : int. it will be called as update(x. The default is scipy. optional Maximum number of iterations to make. optional See Krylov solver. If more are needed to meet convergence.

line_search=’armijo’.optimize) 453 . It is called on every iteration as callback(x. callback=None. see for example [KK]. only a MxM matrix inversions and MxN multiplications are required. see [BJM].0.sparse. optional Relative minimum step size. Returns sol : array-like An array (of similar array type as x0) containing the ﬁnal solution. and for the LGMRES sparse inverse method.dev6665 Absolute minimum step size. optimization is terminated as successful. Optimization and root ﬁnding (scipy. References [KK]. f_tol=None. If omitted. ‘wolfe’}. not used. The basic idea is to compute the inverse of the Jacobian with an iterative Krylov method. Raises NoConvergence : When a solution was not found. The Jacobian is formed by for a ‘best’ solution in the space spanned by last M vectors. optional Norm to use in convergence check.SciPy Reference Guide. See Also: scipy. as determined from the Jacobian approximation. using (extended) Anderson mixing.linalg. x_tol=None.sparse. not used. callback : function. [Ey] 3. Release 0. which is a variant of restarted GMRES iteration that reuses some of the information obtained in the previous Newton steps to invert Jacobians in subsequent steps.anderson(F. x_rtol : ﬂoat. M=5.10. verbose=False.lgmres Notes This function implements a Newton-Krylov solver.optimize. For a review on Newton-Krylov methods. ‘armijo’ (default). The default here is lgmres. w0=0. x_rtol=None. Defaults to ‘armijo’. These methods require only evaluating the Jacobian-vector products. [BJM] scipy. f_rtol=None. alpha=None. tol_norm : function(vector) -> scalar. line_search : {None. If omitted. which are conveniently approximated by numerical differentiation: Jv ≈ (f (x + ω ∗ v/|v|) − f (x))/ω Due to the use of iterative matrix inverses. scipy. iter=None. **kw) Find a root of a function.linalg module offers a selection of Krylov solvers to choose from. optional Which type of a line search to use to determine the step size in the direction given by the Jacobian approximation. f) where x is the current solution and f the corresponding residual.01.gmres. If the step size is smaller than this. tol_norm=None. Default is the maximum norm. optional Optional callback function. xin. these methods can deal with large nonlinear problems. Scipy’s scipy.12. maxiter=None.sparse. As a result.linalg.

Defaults to 5. Reference . line_search : {None. optimization is terminated as successful. ‘armijo’ (default). Compared to unity. default is 6e-6. M : ﬂoat.SciPy Reference Guide. optional Relative tolerance for the residual.10. If omitted. If omitted (default).dev6665 Parameters F : function(x) -> f Function whose root to ﬁnd. optional Optional callback function. tol_norm : function(vector) -> scalar. optional Absolute minimum step size. x0 : array-like Initial guess for the solution alpha : ﬂoat. optional Absolute tolerance (in max-norm) for the residual. f_rtol : ﬂoat. callback : function. optional Number of iterations to make. NoConvergence is raised. If the step size is smaller than this. Release 0. Defaults to ‘armijo’. optional Print status to stdout on every iteration. If more are needed to meet convergence. 454 Chapter 3.0. It is called on every iteration as callback(x. optional Which type of a line search to use to determine the step size in the direction given by the Jacobian approximation. optional Regularization parameter for numerical stability. ‘wolfe’}. should take and return an array-like object. Default is the maximum norm. w0 : ﬂoat. x_tol : ﬂoat. not used. optional Number of previous vectors to retain. verbose : bool. If omitted. f_tol : ﬂoat. make as many as required to meet tolerances. optional Maximum number of iterations to make. If omitted. not used. x_rtol : ﬂoat. optional Relative minimum step size. optional Norm to use in convergence check. not used. f) where x is the current solution and f the corresponding residual. optional Initial guess for the Jacobian is (-1/alpha). If omitted. as determined from the Jacobian approximation.01. iter : int. good values of the order of 0. maxiter : int.

optimize) 455 ..0. callback=None. x0 : array-like Initial guess for the solution alpha : ﬂoat. References [Ey] Simple iterations: excitingmixing(F. 3. alphamax=1. **kw[. optional Number of iterations to make. Raises NoConvergence : When a solution was not found. using diagonal Broyden Jacobian approximation. Find a root of a function. If more are needed to meet convergence.0.10. alpha. maxiter=None.excitingmixing(F. but whether it will work may depend strongly on the problem.. **kw) Find a root of a function. alpha. Optimization and root ﬁnding (scipy.]) linearmixing(F.SciPy Reference Guide.. iter. iter. If omitted (default). optional Maximum number of iterations to make. iter. .12. **kw[. iter : int. Warning: This algorithm may be useful for speciﬁc problems. optional Initial Jacobian approximation is (-1/alpha). using a scalar Jacobian approximation.. using a tuned diagonal Jacobian approximation. Parameters F : function(x) -> f Function whose root to ﬁnd.dev6665 Returns sol : array-like An array (of similar array type as x0) containing the ﬁnal solution. alpha=None. line_search=’armijo’. optional The entries of the diagonal Jacobian are kept in the range [alpha. alpha. The Jacobian matrix is diagonal and is tuned on each iteration. using a tuned diagonal Jacobian approximation. scipy. make as many as required to meet tolerances. f_tol=None. optional Print status to stdout on every iteration. iter=None. f_rtol=None. alphamax : ﬂoat. x_tol=None. xin. alphamax]. . xin. **kw[. NoConvergence is raised. verbose=False.. xin.optimize. should take and return an array-like object. Find a root of a function. . maxiter : int.. xin. x_rtol=None.]) Find a root of a function. Release 0.]) diagbroyden(F. tol_norm=None. verbose : bool.

Release 0. should take and return an array-like object. optional Relative minimum step size. It is called on every iteration as callback(x. maxiter=None.10. make as many as required to meet tolerances. optional The Jacobian approximation is (-1/alpha). Warning: This algorithm may be useful for speciﬁc problems. not used. optional Norm to use in convergence check. Reference . callback=None.optimize. f) where x is the current solution and f the corresponding residual.dev6665 f_tol : ﬂoat. optional Which type of a line search to use to determine the step size in the direction given by the Jacobian approximation. f_rtol=None. line_search : {None. xin. optimization is terminated as successful. f_rtol : ﬂoat. If the step size is smaller than this. x_tol : ﬂoat. x0 : array-like Initial guess for the solution alpha : ﬂoat. Parameters F : function(x) -> f Function whose root to ﬁnd. tol_norm=None. x_rtol=None. optional Optional callback function. Default is the maximum norm. using a scalar Jacobian approximation. Defaults to ‘armijo’. f_tol=None.linearmixing(F. verbose=False. as determined from the Jacobian approximation. optional Relative tolerance for the residual. 456 Chapter 3. If omitted. **kw) Find a root of a function. default is 6e-6. If omitted. x_rtol : ﬂoat.SciPy Reference Guide. iter : int. line_search=’armijo’. scipy. but whether it will work may depend strongly on the problem. If omitted. callback : function. alpha=None. Raises NoConvergence : When a solution was not found. not used. tol_norm : function(vector) -> scalar. ‘wolfe’}.0. iter=None. not used. ‘armijo’ (default). optional Absolute tolerance (in max-norm) for the residual. If omitted. optional Absolute minimum step size. If omitted (default). optional Number of iterations to make. Returns sol : array-like An array (of similar array type as x0) containing the ﬁnal solution. x_tol=None.

optional Absolute minimum step size. tol_norm : function(vector) -> scalar. Returns sol : array-like An array (of similar array type as x0) containing the ﬁnal solution. If omitted. The Jacobian approximation is derived from previous iterations. Release 0. f) where x is the current solution and f the corresponding residual. **kw) Find a root of a function.0. not used. optional Optional callback function.10. f_tol=None. default is 6e-6. x_rtol : ﬂoat. optional Print status to stdout on every iteration.SciPy Reference Guide. Default is the maximum norm.12. 3. using diagonal Broyden Jacobian approximation. should take and return an array-like object. alpha=None. xin. Optimization and root ﬁnding (scipy. Raises NoConvergence : When a solution was not found. NoConvergence is raised. optional Relative tolerance for the residual. If omitted. line_search : {None. Defaults to ‘armijo’. Warning: This algorithm may be useful for speciﬁc problems. but whether it will work may depend strongly on the problem. as determined from the Jacobian approximation. callback=None.optimize. x_tol : ﬂoat. iter=None. not used. If omitted. callback : function. optional Which type of a line search to use to determine the step size in the direction given by the Jacobian approximation. line_search=’armijo’. ‘wolfe’}. optimization is terminated as successful. Parameters F : function(x) -> f Function whose root to ﬁnd. optional Maximum number of iterations to make. tol_norm=None. ‘armijo’ (default). x_rtol=None. optional Norm to use in convergence check.diagbroyden(F. by retaining only the diagonal of Broyden matrices. maxiter : int. verbose=False.optimize) 457 . optional Relative minimum step size. It is called on every iteration as callback(x. If more are needed to meet convergence.dev6665 verbose : bool. optional Absolute tolerance (in max-norm) for the residual. f_rtol : ﬂoat. scipy. not used. If the step size is smaller than this. f_rtol=None. x_tol=None. maxiter=None. If omitted. f_tol : ﬂoat.

callback : function. optional Relative minimum step size. ‘wolfe’}. If omitted. If the step size is smaller than this.0. If omitted. make as many as required to meet tolerances. If omitted. Defaults to ‘armijo’. Reference . not used. x_rtol : ﬂoat. It is called on every iteration as callback(x. x_tol : ﬂoat. optional Absolute tolerance (in max-norm) for the residual. iter : int. line_search : {None. optional Initial guess for the Jacobian is (-1/alpha). Release 0.SciPy Reference Guide. ‘armijo’ (default). optional Optional callback function. optional Number of iterations to make. optional Which type of a line search to use to determine the step size in the direction given by the Jacobian approximation. optional Relative tolerance for the residual.10. Raises NoConvergence : When a solution was not found. maxiter : int. optional Absolute minimum step size. default is 6e-6. verbose : bool. as determined from the Jacobian approximation. f_rtol : ﬂoat. not used. f_tol : ﬂoat. tol_norm : function(vector) -> scalar. not used. Returns sol : array-like An array (of similar array type as x0) containing the ﬁnal solution. optional Maximum number of iterations to make. optional Norm to use in convergence check. optional Print status to stdout on every iteration. optimization is terminated as successful. Default is the maximum norm.dev6665 x0 : array-like Initial guess for the solution alpha : ﬂoat. If omitted. If omitted (default). 458 Chapter 3. f) where x is the current solution and f the corresponding residual. If more are needed to meet convergence. NoConvergence is raised.

optional Gradient value for x=xk (xk being the current parameter estimate). Release 0. Will be recomputed if omitted. args=(). myfprime : callable f’(x. *args) Find alpha that satisﬁes strong Wolfe conditions. amax=50) Find alpha that satisﬁes strong Wolfe conditions. c1 : ﬂoat. 3. xk : ndarray Starting point. Returns alpha0 : ﬂoat Alpha for which x_new = x0 + alpha * pk. optional Additional arguments passed to objective function. pk.90000000000000002.*args) Objective function gradient (can be None). old_fval=None. grad.SciPy Reference Guide. gfk. old_fval : ﬂoat. optional Function value for x=xk. c2=0. pk[.*args) Objective function. Optimization and root ﬁnding (scipy. Parameters f : callable f(x.12.optimize. Will be recomputed if omitted.dev6665 3.line_search(f.. gfk : ndarray. gc : int Number of gradient evaluations made. pk : ndarray Search direction.0001.10. myfprime. optional Parameter for curvature condition rule. xk. xk.4 Utility Functions line_search(f. c1=0. fc : int Number of function evaluations made. old_old_fval=None.]) check_grad(func. c2 : ﬂoat. myfprime. x0. . old_old_fval : ﬂoat.optimize) 459 .0..12. scipy. gfk=None. optional Parameter for Armijo condition rule. optional Function value for the point preceding x=xk args : tuple.

For the zoom phase it uses an algorithm by [. Release 0. in2... Reference . *args) 3.1 Convolution convolve(in1.check_grad(func. sepﬁr2d(input. boundary. ‘same’. in2: array : second input. Cross-correlate two N-dimensional arrays. scipy. Convolve in1 and in2 with output size determined by mode. Convolve two 2-dimensional arrays. Convolve two N-dimensional arrays using FFT. mode=’full’) Cross-correlate two N-dimensional arrays. x0. ﬁllvalue]) correlate2d(in1. in2. pg. in2[. mode: str {‘valid’.signal. Should have the same number of dimensions as in1.convolve(in1.. scipy. Cross-correlate two 2-dimensional arrays.]. See Wright and Nocedal. grad. mode]) convolve2d(in1. mode. .0. mode=’full’) Convolve two N-dimensional arrays. hcol) -> output 460 Chapter 3.signal. 1999. mode. boundary. full [the output is the full discrete linear cross-correlation] of the inputs. ‘Numerical Optimization’.13.dev6665 Notes Uses the line search algorithm to enforce strong Wolfe conditions. in2[. same [the output is the same size as the largest input centered] with respect to the ‘full’ output. (Default) Returns out: array : an N-dimensional array containing a subset of the discrete linear cross-correlation of in1 with in2. ‘full’} : a string indicating the size of the output: valid [the output consists only of those elements that do not] rely on the zero-padding. in2[. Convolve two N-dimensional arrays.correlate(in1.10. Cross-correlate in1 and in2 with the output size determined by the mode argument. in2[. See convolve. 59-60.SciPy Reference Guide. hrow. mode]) correlate(in1.]) sepfir2d scipy. mode]) fftconvolve(in1.13 Signal processing (scipy.signal) 3. in2[.. Parameters in1: array : ﬁrst input.optimize.

. i_l. ‘same’.... i_l + k. boundary=’ﬁll’.convolve2d(in1.. optional : A string indicating the size of the output: valid [the output consists only of those elements that do not] rely on the zero-padding.‘same’: the output is the same size as the largest input centered with respect to the ‘full’ output.. (Default) 3. See convolve.fftconvolve(in1.. ‘full’} : a string indicating the size of the output: • ‘valid’: the output consists only of those elements that do not rely on the zero-padding. mode=’full’) Convolve two N-dimensional arrays using FFT.. .signal. in2: array : second input.] x[. mode: str. same [the output is the same size as the largest input centered] with respect to the ‘full’ output.signal.. Parameters in1.dev6665 Parameters in1: array : ﬁrst input. i_l. ﬁllvalue=0) Convolve two 2-dimensional arrays.. mode: str {‘valid’..10.. in2. (Default) Returns out: array : an N-dimensional array containing a subset of the discrete linear cross-correlation of in1 with in2. in2.] * conj(y[. Notes The correlation z of two arrays x and y of rank d is deﬁned as z[.. Convolve in1 and in2 with output size determined by mode and boundary conditions determined by boundary and ﬁllvalue. full [the output is the full discrete linear cross-correlation] of the inputs.k.signal) 461 . . • ‘full’: the output is the full discrete linear cross-correlation of the inputs. in2 : ndarray Two-dimensional input arrays to be convolved..]) scipy.SciPy Reference Guide....13. Signal processing (scipy.. Should have the same number of dimensions as in1..0....] = sum[. scipy.. mode=’full’. Release 0.

in2 : ndarray Two-dimensional input arrays to be convolved. optional A ﬂag indicating how to handle boundaries: • ‘ﬁll’ : pad input arrays with ﬁllvalue. Default is 0. optional Value to ﬁll pad input arrays with. (Default) boundary : str.0. mode=’full’. optional A ﬂag indicating how to handle boundaries: • ‘ﬁll’ : pad input arrays with ﬁllvalue. (default) • ‘wrap’ : circular boundary conditions.signal. Returns out : ndarray A 2-dimensional array containing a subset of the discrete linear cross-correlation of in1 with in2. Cross correlate in1 and in2 with output size determined by mode and boundary conditions determined by boundary and ﬁllvalue. 462 Chapter 3. • ‘symm’ : symmetrical boundary conditions. full [the output is the full discrete linear cross-correlation] of the inputs. Reference . • ‘symm’ : symmetrical boundary conditions. ﬁllvalue : scalar.dev6665 boundary : str.correlate2d(in1. Release 0. scipy. Default is 0. Parameters in1. in2. boundary=’ﬁll’. optional : A string indicating the size of the output: valid [the output consists only of those elements that do not] rely on the zero-padding.10.SciPy Reference Guide. same [the output is the same size as the largest input centered] with respect to the ‘full’ output. (default) • ‘wrap’ : circular boundary conditions. ﬁllvalue : scalar. Returns out : ndarray A 2-dimensional array containing a subset of the discrete linear convolution of in1 with in2. optional Value to ﬁll pad input arrays with. mode: str. ﬁllvalue=0) Cross-correlate two 2-dimensional arrays.

lamb : ﬂoat.signal.0) Compute quadratic spline coefﬁcients for rank-1 array. n) gauss_spline(x. default is 0. lamb]) qspline1d(signal[.0.sepfir2d() sepﬁr2d(input.signal. precision}) -> qk Smoothing spline (cubic) ﬁltering of a rank-2 array. Returns c : ndarray Cubic spline coefﬁcients. Release 0.0 . n) cspline1d(signal[. scipy. scipy. Signal processing (scipy. hrow. hcol) -> output Description: Convolve the rank-2 input array with the separable ﬁlter deﬁned by the rank-1 arrays hrow. 6. Compute cubic spline coefﬁcients for rank-1 array.0. precision}) -> ck qspline2d(input {. Mirror symmetric boundary conditions are assumed. n) B-spline basis function of order n. To obtain the signal back from the spline representation mirror-symmetric-convolve these coefﬁcients with a length 3 FIR window [1. optional Smoothing coefﬁcient.signal) 463 .piecewise and automatic function-generator. lamb=0.0.0]/ 8. lmbda]) B-spline basis function of order n. Notes Uses numpy.bspline(x.qspline1d(signal. This function can be used to ﬁnd an image given its B-spline representation. Parameters signal : ndarray A rank-1 array representing samples of a signal. Find the quadratic spline coefﬁcients for a 1-D signal assuming mirror-symmetric boundary conditions.signal.13.0.0]/ 6. lambda. and hcol. lambda. 1.0) Compute cubic spline coefﬁcients for rank-1 array.13.2 B-splines bspline(x.0. 1.gauss_spline(x. 4. Compute quadratic spline coefﬁcients for rank-1 array. lamb=0. n) Gaussian approximation to B-spline basis function of order n. Gaussian approximation to B-spline basis function of order n.cspline1d(signal. Find the cubic spline coefﬁcients for a 1-D signal assuming mirror-symmetric boundary conditions.SciPy Reference Guide. To obtain the signal back from the spline representation mirror-symmetric-convolve these coefﬁcients with a length 3 FIR window [1. Parameters signal : ndarray A rank-1 array representing samples of a signal.signal. scipy. 3. 3.signal. cspline2d(input {.0 .dev6665 scipy. scipy.10.0. lamb]) cspline2d qspline2d spline_filter(Iin[.

0. kernel_size]) wiener(im[. q[. Perform an order ﬁlter on the array in. Parameters a : ndarray 464 Chapter 3. Perform a median ﬁlter on an N-dimensional array. ftype. precision}) -> output symiirorder2(input.signal. symiirorder1(input. The lambda argument speciﬁes the amount of smoothing. Filter an input data set. Reference .0) Smoothing spline (cubic) ﬁltering of a rank-2 array. precision}) -> output Filter data along one-dimension with an IIR or FIR ﬁlter. precision}) -> ck Description: Return the third-order B-spline coefﬁcients over a regularly spacedi input grid for the twodimensional input image. and the output for that pixel is the element corresponding to rank in the sorted list.signal. rank) medfilt(volume[. axis. r. omega {.order_filter(a. noise]) symiirorder1 symiirorder2 lfilter(b. mysize. bp]) resample(x. The precision argument allows specifying the precision used when computing the inﬁnite sum needed to apply mirror. fftbins]) decimate(x. n. divisor) hilbert(x[. Resample x to num samples using Fourier method along the given axis. x]) deconvolve(signal. kernel_size]) medfilt2d(input[.dev6665 lamb : ﬂoat.3 Filtering order_filter(a. The domain argument acts as a mask centered over each pixel. axis]) get_window(window.SciPy Reference Guide. num[. The precision argument allows specifying the precision used when computing the inﬁnite sum needed to apply mirror. a. 3. x[. scipy. y[.symmetric boundary conditions. Returns c : ndarray Cubic spline coefﬁcients. z1 {. c0. Release 0. Nx[. scipy.10. Perform a Wiener ﬁlter on an N-dimensional array. axis.signal. window]) Perform an order ﬁlter on an N-dimensional array. The list is sorted. using an order n ﬁlter Remove linear trend along axis from data. domain. lambda. lmbda=5. N. Iin. zi]) lfiltic(b. domain. lambda. scipy. optional Smoothing coefﬁcient (must be zero for now). downsample the signal x by an integer factor q.qspline2d() qspline2d(input {. a.13. rank) Perform an order ﬁlter on an N-dimensional array. axis. precision}) -> qk Description: Return the second-order B-spline coefﬁcients over a regularly spaced input grid for the twodimensional input image.symmetric boundary conditions. type. axis]) detrend(data[. The non-zero elements of domain are used to select elements surrounding each input pixel which are placed in a list. Median ﬁlter a 2-dimensional array. scipy. The lambda argument speciﬁes the amount of smoothing.spline_filter(Iin.signal. Return a window of length Nx and type window. t.cspline2d() cspline2d(input {. Compute the analytic signal. Construct initial conditions for lﬁlter Deconvolves divisor out of signal. using a (cubic) smoothing spline of fall-off lmbda.

9... then this scalar is used as the size in each dimension. [20. 1. 4.].arange(25). [ 16. Returns out : ndarray An array the same size as input containing the median ﬁltered result.. Elements of kernel_size should be odd. 0.. etc.10.. Examples >>> import scipy.. 6. domain. 11. 2) array([[ 6.. 18.. If kernel_size is a scalar.]...13. Default size is 3 for each dimension. 14.0. 2. 14..]. 0. [ 0. 23. [15. 2.]]) scipy.. 23.. 21.].]..... 18. 9]. 0.signal) 465 . 14]. Apply a median ﬁlter to the input array using a local window-size given by kernel_size. 7. [ 20.. 5) >>> domain = np. 22. 23. 12.identity(3) >>> x array([[ 0. 0.. 24. Release 0.. 12. 16..). 0.. 10.order_filter(x. [ 0. 7.. Each dimension should have an odd number of elements. 13.. [ 5. 12... kernel_size=None) Perform a median ﬁlter on an N-dimensional array..]..]]) >>> sp. kernel_size : array_like. 17. domain : array_like A mask array with the same number of dimensions as in. 21..signal. 8. 0. Signal processing (scipy. 7.signal. rank : int A non-negative integer which selects the element from the sorted list (0 corresponds to the smallest element.dev6665 The N-dimensional input array. [ 0.. 17. 6. 13..SciPy Reference Guide. 11... domain. 19]. 3. 0..signal. 0. [ 11. 22. optional A scalar or an N-length list giving the size of the median ﬁlter window in each dimension.. 0) array([[ 0. 19. 22. 9. 24]]) >>> sp.]... 8.. [ 21. 0. 0.order_filter(x. 0. 3. [10. 19.. 1.reshape(5. 0. Parameters volume : array_like An N-dimensional input array. 24.]. Returns out : ndarray The results of the order ﬁlter in an array with the same shape as in.medfilt(volume. 5..signal >>> x = np. 4]. 1 is the next smallest element. [ 0.

Reference . scipy. kernel_size : array_like. If None.wiener(im.10.SciPy Reference Guide. mysize=None. c0 H(z) = ——————— (1-z1/z) (1 . mysize : int or arraylike. Apply a Wiener ﬁlter to the N-dimensional array im. Release 0.signal. then this scalar is used as the size in each dimension. Elements of kernel_size should be odd. The second section uses a reversed sequence.dev6665 scipy. Apply a median ﬁlter to the input array using a local window-size given by kernel_size (must be odd).z1 z) The resulting signal will have mirror symmetric boundary conditions as well. giving the size of the median ﬁlter window in each dimension. 3). kernel_size=3) Median ﬁlter a 2-dimensional array. then this scalar is used as the size in each dimension. optional A scalar or a list of length 2.medfilt2d(input. precision}) -> output Description: Implement a smoothing IIR ﬁlter with mirror-symmetric boundary conditions using a cascade of ﬁrst-order sections. Parameters im : ndarray An N-dimensional array. This implements a system with the following transfer function and mirror-symmetric boundary conditions. optional A scalar or an N-length list giving the size of the Wiener ﬁlter window in each dimension. Default is a kernel of size (3. Parameters input : array_like A 2-dimensional input array. If kernel_size is a scalar.signal.signal. If mysize is a scalar. Elements of mysize should be odd. scipy. optional The noise-power to use. Returns out : ndarray Wiener ﬁltered result with the same shape as im. Returns out : ndarray An array the same size as input containing the median ﬁltered result. noise : ﬂoat. noise=None) Perform a Wiener ﬁlter on an N-dimensional array.symiirorder1() symiirorder1(input. then noise is estimated as the average of the local variance of the input.0. Inputs: 466 Chapter 3. c0. z1 {.

scipy. x : array_like An N-dimensional input array. Signal processing (scipy. This implements the following transfer function: cs^2 H(z) = ————————————— (1 . a.10. omega {. This works for many fundamental data types (including Object type).symiirorder2() symiirorder2(input. Output: output – ﬁltered signal. r. zi=None) Filter data along one-dimension with an IIR or FIR ﬁlter.signal) 467 . omega – parameters in the transfer function. axis=-1.SciPy Reference Guide. x. The ﬁlter is a direct form II transposed implementation of the standard difference equation (see Notes). precision – speciﬁes the precision for calculating initial conditions of the recursive ﬁlter based on mirror-symmetric input. axis : int The axis of the input data array along which to apply the linear ﬁlter. If a[0] is not 1.signal. r. The second section uses a reversed sequence. c0. Output: output – ﬁltered signal.a2/z .a3/z^2) (1 . The ﬁlter is applied to each subarray along this axis (Default = -1) zi : array_like (optional) 3. then both a and b are normalized by a[0]. z1 – parameters in the transfer function. Release 0.a2 z .2 r cos omega + r^2 Inputs: input – the input signal.0.r^2 cs = 1 . scipy. a : array_like The denominator coefﬁcient vector in a 1-D sequence. precision – speciﬁes the precision for calculating initial conditions of the recursive ﬁlter based on mirror-symmetric input. using a digital ﬁlter. Filter a data sequence.13. precision}) -> output Description: Implement a smoothing IIR ﬁlter with mirror-symmetric boundary conditions using a cascade of second-order sections.a3 z^2 ) where a2 = (2 r cos omega) a3 = . x.dev6665 input – the input signal.signal. Parameters b : array_like The numerator coefﬁcient vector in a 1-D sequence.lfilter(b.

.....m-1] z[0. this is not returned.. scipy. the initial conditions are given in the vectors x and y as: x = {x[-1].m] = b[n-2]*x[m] + z[n-2..m] = b[n-1]*x[m] ..a[n-2]*y[m] z[n-2. If M=len(b)-1 and N=len(a)-1...len(b)) is the model order. + b[nb]*x[n-nb] .a[1]*y[n-1] .N).a[na]*y[n-na] using the following difference equations: y[m] = b[0]*x[m] + z[0... The transformation is done along the last axis by default.y[-N]} If x is not given. SEE signal. otherwise. x=None) Construct initial conditions for lﬁlter Given a linear ﬁlter (b.a) and initial conditions on the output y and the input x. then zeros are added to achieve the proper length. z[n-3.. divisor) Deconvolves divisor out of signal.. + a[na] z scipy. This means that the ﬁlter implements a[0]*y[n] = b[0]*x[n] + b[1]*x[n-1] + . return the inital conditions on the state vector zi which is used by lﬁlter to generate the output given the input.10.. zf holds the ﬁnal ﬁlter delay values. If zi=None or is not given then initial rest is assumed.lfiltic(b. It is a vector (or array of vectors for an Ndimensional input) of length max(len(a).a[n-1]*y[m] where m is the output sample number and n=max(len(a). .x[-M]} y = {y[-1].. The rational transfer function describing this ﬁlter in the z-transform domain is: -1 -nb b[0] + b[1]z + .signal.m] = b[1]*x[m] + z[1.signal.deconvolve(signal.SciPy Reference Guide. The output vector zi contains: zi = {z_0[-1]. Release 0. N=None. zf : array (optional) If zi is None.X(z) -1 -na a[0] + a[1]z + . Notes The ﬁlter function is implemented as a direct II transposed structure. scipy.y[-2]. Returns y : array The output of the digital ﬁlter. axis=-1) Compute the analytic signal. Reference .a[1]*y[m] .. its inital conditions are assumed zero. .signal.lﬁltic for more information.x[-2].len(b))-1.. y.hilbert(x.m-1] . a. 468 Chapter 3..dev6665 Initial conditions for the ﬁlter delays. z_K-1[-1]} where K=max(M.m-1] .. Then.. If either vector is too short. z_1[-1]. + b[nb] z Y(z) = ---------------------------------.0..

optional Number of Fourier components.get_window(window. chebwin (needs attenuation) If the window requires no parameters. kaiser (needs beta). Notes Window types: boxcar.dev6665 Parameters x : array_like Signal data N : int. of each 1-D array along axis Notes The analytic signal x_a(t) of x(t) is: x_a = F^{-1}(F(x) 2U) = x + i y where F is the Fourier transform.13. Signal processing (scipy. Nx. width). ﬂoat. optional Axis along which to do the transformation. and the next arguments the needed parameters. create a “periodic” window ready to use with ifftshift and be multiplied by the result of an fft (SEE ALSO fftfreq). Default: x.signal) 469 . general_gaussian (needs power. gaussian (needs std). See below for more details. bartlett.SciPy Reference Guide. Nx : int The number of samples in the window.0. optional If True.10. fftbins : bool. and y the Hilbert transform of x. fftbins=True) Return a window of length Nx and type window. Each of the window types listed above is also the name of a function that can be called directly to create a window of that type. slepian (needs width). it is interpreted as the beta parameter of the kaiser window. parzen. hamming. Returns xa : ndarray Analytic signal of x. References [R57] scipy.shape[axis] axis : int. 3. U the unit step function.0. or tuple The type of window to create.8. Parameters window : string. If the window requires parameters. [R57] axis argument is new in scipy 0. blackman. If window is a ﬂoating point number.signal. then window can be a string. nuttall. then window must be a tuple with the ﬁrst argument the string name of the window. barthann. triang. blackmanharris. hanning. bohman. Release 0. Default: -1.

1. If type == ’linear’ (default).89640418.08848053.89640418. By default this is the last axis (-1). 0. bp : array_like of ints. 0. 7) array([ 0. 1. 0.0). 0.08848053. Reference .89640418. scipy.dev6665 Examples >>> get_window(’triang’.decimate(x.25.89640418. .0. Parameters data : array_like The input data.08848053]) 0. optional The type of detrending.75. Release 0.0.10.SciPy Reference Guide. 0. the result of a linear least-squares ﬁt to data is subtracted from data. 0. n=None. using an order n ﬁlter By default an order 8 Chebyshev type I ﬁlter is used or a 30 point FIR ﬁlter with hamming window if ftype is ‘ﬁr’. 9) array([ 0. Parameters x : N-d array the signal to be downsampled q : int the downsampling factor n : int or None the order of the ﬁlter (1 less than the length for ‘ﬁr’) ftype : {‘iir’ or ‘ﬁr’} the type of the lowpass ﬁlter axis : int the axis along which to decimate Returns y : N-d array the down-sampled signal See Also: resample scipy. 0.63343178. 0.63343178. If type == ’constant’.signal. 0. optional The axis along which to detrend the data. 0. only the mean of data is subtracted. 0. ftype=’iir’. 0.signal. 4.32578323. 9) array([ 0. axis=-1.63343178. optional 470 Chapter 3. 0. axis=-1) downsample the signal x by an integer factor q. >>> get_window(4. 1. 0.75. q. 0.5 >>> get_window((’kaiser’.63343178. type=’linear’.5 .32578323. . 0. axis : int.25]) .32578323.08848053]) .32578323. 0. bp=0) Remove linear trend along axis from data.detrend(data. ‘constant’}. type : {‘linear’. 0.

If given. axis=0. Release 0. string. fftfreq(x.e. Signal processing (scipy. Because a Fourier method is used. window : array_like. t=None.13. 3. optional Speciﬁes the window applied to the signal in the Fourier domain. it is assumed to be the sample positions associated with the signal data in x. npoints) + noise >>> (sp.random. See below for details.SciPy Reference Guide.0. ﬂoat.10. The resampled signal starts at the same value as x but is sampled with a spacing of len(x) / num * (spacing of x).max() < 0. Returns resampled_x or (resampled_x. Parameters x : array_like The data to be resampled.dev6665 A sequence of break points. optional If t is given. Examples >>> randgen = np. Returns ret : ndarray The detrended input data. or tuple.noise).signal) 471 .01 True scipy. If window is a function. a tuple containing the resampled array and the corresponding resampled positions.randn(npoints) >>> x = 3 + 2*np.shape[axis] it is assumed to be the window to be applied directly in the Fourier domain (with dc and low-frequency ﬁrst). num : int The number of samples in the resampled signal.signal.linspace(0.RandomState(9) >>> npoints = 1e3 >>> noise = randgen. an individual linear ﬁt is performed for each part of data between two break points.resample(x. Notes The argument window controls a Fourier-domain window that tapers the Fourier spectrum before zero-padding to alleviate ringing in the resampled values for sampled signals you didn’t intend to be interpreted as bandlimited. or. resampled_t) : Either the resampled array. 1. num. If window is an array of the same length as x. callable.shape[axis]) ). then it is called with a vector of inputs indicating the frequency bins (i.detrend(x) . Break points are speciﬁed as indices into data. if t was given. the signal is assumed to be periodic. Default is 0. optional The axis of x that is resampled. axis : int. t : array_like.signal. window=None) Resample x to num samples using Fourier method along the given axis.

firwin(numtaps. whole. then it represents the old sample positions. width) remez(numtaps..p. gain[. cutoff[. Determine unique roots and their multiplicities from a list of roots.SciPy Reference Guide. tol. k[. analog.bilinear(b. gstop[. Complete IIR digital and analog ﬁlter design. a[. a[. . tol. width=None. IIR digital and analog ﬁlter design given order and critical points. fs]) firwin(numtaps. . Design a Kaiser window to limit ripple and width of transition region. the frequencies in cutoff should 472 Chapter 3. it will be Type I if numtaps is odd and Type II if numtaps is even. given the attenuation a. window. scipy. cutoff. weight.0. gpass.]) unique_roots(p[. FIR ﬁlter design using the window method. desired[. fs=1. Wn[. Calculate the minimax optimal ﬁlter using the Remez exchange algorithm.. Hz. FIR ﬁlter design using the window method. . rtype]) invres(r. plot]) freqz(b[. p. a. a.signal..]) firwin2(numtaps. plot]) iirdesign(wp. Compute partial-fraction expansion of b(s) / a(s). a[.signal.]) freqs(b. This function computes the coefﬁcients of a ﬁnite impulse response ﬁlter. the function scipy.0) Return a digital ﬁlter from an analog ﬁlter using the bilinear transform. The spacing between samples is changed from dx to: dx * len(x) / num If t is not None. and the new sample positions will be returned as well as the new samples.signal. .4 Filter design bilinear(b. . freq. Compute frequency response of analog ﬁlter. band edges). rtype]) Return a digital ﬁlter from an analog ﬁlter using the bilinear transform. pass_zero=True.. numtaps must be even if a passband includes the Nyquist frequency. tol.. tol.13. rtype]) residue(b. width. scale=True. ws. width) kaiser_beta(a) kaiserord(ripple. nfreqs.get_window is called to generate the window. Parameters numtaps : int Length of the ﬁlter (number of coefﬁcients.. rtype]) residuez(b. nyq=1. the ﬁlter order + 1).10. Compute b(s) and a(s) from partial fraction expansion: r. Type II ﬁlters always have zero response at the Nyquist rate. worN. Compute the frequency response of a digital ﬁlter..k scipy. rp. i.. The bilinear transform substitutes (z-1) / (z+1) for s. Release 0.dev6665 For any other type of window. The ﬁlter will have linear phase. bands.. Compute the Kaiser parameter beta. cutoff : ﬂoat or 1D array_like Cutoff frequency of ﬁlter (expressed in the same units as nyq) OR an array of cutoff frequencies (that is. so a ValueError exception is raised if ﬁrwin is called with numtaps even and having a passband whose right end is at the Nyquist rate. 3.. In the latter case. rs. analog.]) iirfilter(N. Compute partial-fraction expansion of b(z) / a(z). a[.]) kaiser_atten(numtaps. worN. btype.e. Reference . window=’hamming’. Compute the attenuation of a Kaiser FIR ﬁlter.0) FIR ﬁlter design using the window method. The ﬁrst sample of the returned vector is the same as the ﬁrst sample of the input vector.

signal. window : string or tuple of string and parameter values Desired window to use. if the values in cutoff are not strictly monotonically increasing. Signal processing (scipy. See scipy.signal. See Also: scipy.SciPy Reference Guide. pass_zero is True).0. The values 0 and nyq must not be included in cutoff. nyq : ﬂoat Nyquist frequency. window=’nuttall’) High-pass (‘stop’ from 0 to f): 3. Each frequency in cutoff must be between 0 and nyq. width : ﬂoat or None If width is not None. scale : bool Set to True to scale the coefﬁcients so that the frequency response is exactly unity at a certain frequency. Raises ValueError : If any value in cutoff is less than or equal to 0 or greater than or equal to nyq. f) Use a speciﬁc window function: >>> firwin(numtaps.e.signal) 473 . or if numtaps is even but a passband includes the Nyquist frequency.10.dev6665 be positive and monotonically increasing between 0 and nyq. Otherwise the DC gain is 0. In this case. Returns h : 1D ndarray Coefﬁcients of length numtaps FIR ﬁlter. pass_zero : bool If True.13.e the ﬁlter is a single band highpass ﬁlter).get_window for a list of windows and required parameters. the gain at the frequency 0 (i. f.firwin2 Examples Low-pass from 0 to f: >>> firwin(numtaps. That frequency is either: 0 (DC) if the ﬁrst passband starts at 0 (i. then assume it is the approximate width of the transition region (expressed in the same units as nyq) for use in Kaiser FIR ﬁlter design. the “DC gain”) is 1.e. Release 0. nyq (the Nyquist rate) if the ﬁrst passband ends at nyq (i. the window argument is ignored. center of ﬁrst passband otherwise.

Reference .g. window=’hamming’. optional Window function to use. f4].signal. gain. From the given frequencies freq and corresponding gains gain. [f1. f3. 1D The frequency sampling points. A value can be repeated once to implement a discontinuity. 474 Chapter 3. 129. If None. is not 0. optional The size of the interpolation mesh used to construct the ﬁlter. f2. f3] and [f4. freq : array-like. For most efﬁcient behavior. Returns taps : numpy 1D array of length numtaps The ﬁlter coefﬁcients of the FIR ﬁlter.0) FIR ﬁlter design using the window method. gain : array-like The ﬁlter gains at the frequency sampling points. nfreqs must be greater than numtaps. 257. and the last value must be nyq. [f1. f2] and [f3. ﬂoat) or ﬂoat. The Nyquist frequency can be redeﬁned with the argument nyq. 1]): >>>firwin(numtaps. nfreqs : int.0 with 1.0 being Nyquist.0 to 1. f2. or None. The default is one more than the smallest power of 2 that is not less than numtaps. f2]) Multi-band (passbands are [0.SciPy Reference Guide.dev6665 >>> firwin(numtaps. f3. freq.get_window for the complete list of possible values. Typically 0. f2].firwin2(numtaps. this function constructs an FIR ﬁlter with linear phase and (approximately) the given frequency response. pass_zero=False) Band-stop: >>> firwin(numtaps. nfreqs=None. The ﬁrst value in freq must be 0. numtaps must be less than nfreqs. [f2. Each frequency in freq must be between 0 and nyq (inclusive).0.signal. window : string or (string. If the gain at the Nyquist rate. Release 0. nyq : ﬂoat Nyquist frequency.10. pass_zero=False) scipy. f4]) Multi-band (passbands are [f1.f4]): >>> firwin(numtaps. etc). f. nyq=1. Default is “hamming”. The values in freq must be nondecreasing. See scipy. [f1. f1]. gain[-1]. this should be a power of 2 plus 1 (e. then numtaps must be odd. Parameters numtaps : int The number of taps in the FIR ﬁlter. [f1. no window function is applied. pass_zero=False) Band-pass: >>> firwin(numtaps.

The inverse FFT is applied to the desired response to create the associated convolution kernel. + b[nb-1] H(w) = ------------------------------------------------------a[0]*(jw)**(na-1) + a[1]*(jw)**(na-2) + . Because Type II ﬁlters always have a zero at the Nyquist frequency.06362756 -0. 1.0.57310236 -0. Otherwise. scaled by window. 3. Signal processing (scipy.dev6665 See Also: scipy.SciPy Reference Guide. Useful for plotting the frequency response inside freqz. Returns w : ndarray The frequencies at which h was computed.0].10. New in version 0. 0.02286961 -0. The ﬁlter is Type I if numtaps is odd and Type II if numtaps is even.0. the compute at that many frequencies. [1. If given. a : ndarray Denominator of a linear ﬁlter.9.0.. Release 0. then compute at 200 frequencies around the interesting parts of the response curve (determined by pole-zero locations). the desired response is constructed in the frequency domain.signal. worN=None. are returned.02286961] scipy. 1. h : ndarray The frequency response. 0.0]) >>> print(taps[72:78]) [-0.signal. plot=None) Compute frequency response of analog ﬁlter.freqs(b. worN : {None.5.57310236 0.firwin Notes From the given set of frequencies and gains. If a single integer.0.. plot : callable A callable that takes two arguments. 0. and that decreases linearly on [0. 1. compute the response at frequencies given in worN.5]. [R56] Examples A lowpass FIR ﬁlter with a response that is 1 on [0. The FIR ﬁlter will have linear phase. optional If None. References [R55]. Given the numerator (b) and denominator (a) of a ﬁlter compute its frequency response: b[0]*(jw)**(nb-1) + b[1]*(jw)**(nb-2) + . + a[na-1] Parameters b : ndarray Numerator of a linear ﬁlter. int}.0.06362756 0. the return parameters w and h are passed to plot.0] from 1 to 0: >>> taps = firwin2(150. a.. numtaps must be odd if gain[-1] is not zero.13. [0.signal) 475 . and the ﬁrst numtaps coefﬁcients of this kernel.0.5..

If a single integer. a=1. optional Normally. Reference . this plots the real part of the complex transfer function..10. Useful for plotting the frequency response inside freqz.dev6665 See Also: freqz Compute the frequency response of a digital ﬁlter. plot : callable A callable that takes two arguments.freqz(b. Given the numerator b and denominator a of a digital ﬁlter compute its frequency response: jw -jw -jmw jw B(e) b[0] + b[1]e + . optional If None.0. Returns w : ndarray The frequencies at which h was computed. plot=None) Compute the frequency response of a digital ﬁlter.SciPy Reference Guide.. int}. not the magnitude. frequencies are computed from 0 to pi (upper-half of unit-circle. this plots the real part of the complex transfer function. 476 Chapter 3. not the magnitude.signal. If given. the return parameters w and h are passed to plot. If whole is False. Notes Using Matplotlib’s “plot” function as the callable for plot produces unexpected results. compute frequencies from 0 to 2*pi. Otherwise.= -----------------------------------jw -jw -jnw A(e) a[0] + a[1]e + . + a[n]e Parameters b : ndarray numerator of a linear ﬁlter a : ndarray denominator of a linear ﬁlter worN : {None. whole=0.. Notes Using Matplotlib’s “plot” function as the callable for plot produces unexpected results.. then compute at 512 frequencies around the unit circle.. Release 0. worN=None. scipy.. the compute at that many frequencies. h : ndarray The frequency response. compute the response at frequencies given in worN whole : bool. + b[m]e H(e) = ---.

2.iirdesign(wp. Release 0.0. 0. angles.0 2.6] 3.2.legend() ax2 = ax1. ftype=’ellip’.grid() plt. ws.signal.5.5 Frequency (rad/sample) 3. denominator (‘ba’) or pole-zero (‘zpk’) form. Parameters wp.3.0 3. gstop.0 0.abs(w). normalized from 0 to 1 (1 corresponds to pi radians / sample). For example: • Lowpass: wp = 0. ’b’) plt.signal >>> b = sp.title(’Digital filter frequency response’) ax1 = fig. Given passband and stopband frequencies and gains construct an analog or digital IIR ﬁlter of minimum order for a given basic type. window=(’kaiser’. ws = 0.xlabel(’Frequency (rad/sample)’) plt.5 1.5]. ws = [0.3 • Highpass: wp = 0.twinx() angles = np.2 • Bandpass: wp = [0. ws = 0.5 1.semilogy(h. output=’ba’) Complete IIR digital and analog ﬁlter design. gpass.add_subplot(111) plt.show() 101 100 10-1 10-2 10-3 10-4 10-5 10-6 10-7 Digital filter frequency response 0 10 20 30 40 50 60 70 80 0.5 scipy.signal) Angle (radians) Amplitude (dB) 477 . np. 0. color=’b’) plt.ylabel(’Amplitude (dB)’. analog=0. Return the output in numerator.firwin(80. Signal processing (scipy. w = sp.0 2. ws : ﬂoat Passband and stopband edge frequencies.pyplot as plt fig = plt. ’g’) plt.signal.unwrap(np.angle(w)) plt.plot(h.10. 8)) >>> h.13. 0.1. color=’g’) plt.dev6665 Examples >>> import scipy.signal.ylabel(’Angle (radians)’.figure() plt.SciPy Reference Guide.freqz(b) >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> >>> import matplotlib.

optional For chebyshev and elliptic ﬁlters provides the minimum attenuation in the stop band. ‘zpk’]. Wn. optional The type of ﬁlter (lowpass.SciPy Reference Guide.signal. rp : ﬂoat. ftype : str.dev6665 • Bandstop: wp = [0. a : : Numerator and denominator of the IIR ﬁlter. rs=None. rp=None. Wn : array_like A scalar or length-2 sequence giving the critical frequencies. z. p. optional The type of IIR ﬁlter to design: • elliptic : ‘ellip’ • Butterworth : ‘butter’.0. btype=’band’. btype : str. : scipy. Only returned if ‘‘output=’zpk’‘‘. analog : int. 0.A) (numerator.P. ws = [0. Release 0. bandpass. Default is ‘ba’. and gain of the IIR ﬁlter. highpass. analog : int.5] gpass : ﬂoat The maximum loss in the passband (dB). denominator) or (Z. analog=0. ftype=’butter’. bandstop).1. optional 478 Chapter 3.10.6]. Default is bandpass. poles. gstop : ﬂoat The minimum attenuation in the stopband (dB). • Bessel : ‘bessel’ output : [’ba’. optional For Chebyshev and elliptic ﬁlters provides the maximum ripple in the passband. 0. Returns b. rs : ﬂoat. Design an Nth order lowpass digital or analog ﬁlter and return the ﬁlter coefﬁcients in (B. Parameters N : int The order of the ﬁlter.iirfilter(N. Reference . output=’ba’) IIR digital and analog ﬁlter design given order and critical points. Only returned if output=’ba’.2. optional Non-zero to design an analog ﬁlter (in this case wp and ws are in radians / second). k : Zeros. • Chebyshev I : ‘cheby1’. optional Type of output: numerator/denominator (‘ba’) or pole-zero (‘zpk’).K) form. • Chebyshev II: ‘cheby2’.

given by Kaiser’s formula: a = 2. This should be a positive number. Signal processing (scipy. Default is ‘ba’. See Also: butterord. Given the number of taps N and the transition width width.dev6665 Non-zero to return an analog ﬁlter.kaiser_atten(numtaps. Returns a : ﬂoat The attenuation of the ripple.signal) 479 . • Bessel : ‘bessel’ output : [’ba’. in general. kaiser_beta scipy. otherwise a digital ﬁlter is returned. ftype : str. at any discontinuity) for the ﬁlter. ‘zpk’]. • Chebyshev I : ‘cheby1’. cheb1ord. Returns beta : ﬂoat The beta parameter to be used in the formula for a Kaiser window. in dB. optional The type of IIR ﬁlter to design: • elliptic : ‘ellip’ • Butterworth : ‘butter’. given the attenuation a. 3. width : ﬂoat The desired width of the transition region between passband and stopband (or.13.285 * (N . See Also: kaiserord. cheb2ord.signal.1) * pi * width + 7. Release 0. ellipord scipy.signal.95 Parameters N : int The number of taps in the FIR ﬁlter. Parameters a : ﬂoat The desired attenuation in the stopband and maximum ripple in the passband. in dB.0. width) Compute the attenuation of a Kaiser FIR ﬁlter. compute the attenuation a in dB.10.SciPy Reference Guide.kaiser_beta(a) Compute the Kaiser parameter beta. • Chebyshev II: ‘cheby2’. optional Type of output: numerator/denominator (‘ba’) or pole-zero (‘zpk’).

Schafer. type=’bandpass’. bands : array_like A monotonic sequence containing the band edges in Hz. “Discrete-Time Signal Processing”. bands. References Oppenheim. width : ﬂoat Width of transition region (normalized so that 1 corresponds to pi radians / sample). Calculate the ﬁlter-coefﬁcients for the ﬁnite impulse response (FIR) ﬁlter whose transfer function minimizes the maximum error between the desired gain and the realized gain in the speciﬁed frequency bands using the Remez exchange algorithm. maxiter=25. beta. Release 0.10. numtaps) sig- 480 Chapter 3.SciPy Reference Guide.remez(numtaps.get_window(beta. grid_density=16) Calculate the minimax optimal ﬁlter using the Remez exchange algorithm. or the ﬁlter order plus one.475-476.get_window((‘kaiser’.signal. scipy.kaiserord(ripple. Reference . weight=None. sym=0) nal. Hz=1.0. All elements must be nonnegative and less than half the sampling frequency as given by Hz. Schafer. The number of taps is the number of terms in the ﬁlter. width) Design a Kaiser window to limit ripple and width of transition region. “Discrete-Time Signal Processing”. desired.kaiser(numtaps. scipy.dev6665 References Oppenheim. beta).475-476. p. numtaps) The empirical equations discovered by Kaiser are used. Parameters numtaps : int The desired number of taps in the ﬁlter.signal. See Also: kaiser_beta. signal. kaiser_atten Notes There are several ways to obtain the Kaiser window: signal. p. beta : : The beta parameter for the kaiser window. Parameters ripple : ﬂoat Positive number specifying maximum ripple in passband (dB) and minimum ripple in stopband. Returns numtaps : int The length of the kaiser window. desired : array_like A sequence half the size of bands containing the desired gain in each of the speciﬁed bands.

The length of weight has to be half the length of bands. Release 0.Line2D object at 0xf486790>] >>> plt. ‘hilbert’ [ﬁlter with odd symmetry. Signal processing (scipy.figure() >>> ax1 = fig. Note that this means that the behavior in the frequency ranges between those bands is unspeciﬁed and may overshoot. maxiter : int.signal. ‘hilbert’}.5].show() 3. References [R58]. 0.abs(response) >>> import matplotlib. [R59] Examples We want to construct a ﬁlter with a passband at 0. ampl.lines.signal) 481 . optional The type of ﬁlter: ‘bandpass’ : ﬂat response in bands.45.2-0. Default is 1.4. 0. optional Grid density. ‘differentiator’ : frequency proportional response in bands. See Also: freqz Compute the frequency response of a digital ﬁlter.2. [0. Default is 25.1 Hz and 0.1.0.remez(72. type : {‘bandpass’. [0.SciPy Reference Guide.add_subplot(111) >>> ax1. optional The sampling frequency in Hz. This is the default. grid_density : int. that is. Returns out : ndarray A rank-1 array containing the coefﬁcients of the optimal (in a minimax sense) ﬁlter. Default is 16.signal. response = sp. 0. 0]) >>> freq.13.10. Hz : scalar. 0. 1. type III] (for even order) or type IV (for odd order) linear phase ﬁlters.45-0.5 Hz. optional A relative weighting to give to each band region.freqz(bpass) >>> ampl = np. 0.4 Hz. and stop bands at 0-0. ’b-’) # freq in Hz [<matplotlib. The dense grid used in remez is of size (numtaps + 1) * grid_density. ‘differentiator’.pyplot as plt >>> fig = plt.semilogy(freq/(2*np.dev6665 weight : array_like. optional Maximum number of iterations of the algorithm.pi). >>> bpass = sp.

Release 0.3] >>> uniq. 2. Reference .10.3 0. 1. optional How to determine the returned root if multiple roots are within tol of each other. Default is 1e-3.001.3. rtype=’min’) Determine unique roots and their multiplicities from a list of roots.31. • ‘max’: pick the maximum of those roots.unique_roots(vals. ‘avg’}.signal.dev6665 101 100 10-1 10-2 10-3 10-4 10-5 10-6 0.2 0. • ‘avg’: take the average of those roots. tol : ﬂoat. rtype : {‘max’.0. Parameters p : array_like The list of roots. ‘min. mult = sp. 10. rtype=’avg’) Check which roots have multiplicity larger than 1: 482 Chapter 3. optional The tolerance for two roots to be considered equal. • ‘min’: pick the minimum of those roots. tol=0.SciPy Reference Guide. Returns pout : ndarray The list of unique roots. 2.signal.unique. For a more general routine. sorted from low to high.25.4 0. mult : ndarray The multiplicity of each root.5 scipy.0 0. see numpy.1 0.unique_roots(p. 1. tol=2e-2. Examples >>> vals = [0.8.2. 1. Notes This utility function is not speciﬁc to roots but can be used for any sequence of values for which uniqueness and multiplicity has to be determined.

signal..001...+ k[0] + k[1]z**(-1) .13. p : ndarray Poles. then H(s) has terms like: r[i] r[i+1] r[i+n-1] -------.... Signal processing (scipy..0.10. tol=0. + —————. rtype=’avg’) Compute partial-fraction expansion of b(s) / a(s). + a[N-1] r[0] r[1] r[-1] = -------.305]) scipy. + --------. tol=0.+ -------..+ .poly.. If M = len(b) and N = len(a).dev6665 >>> uniq[mult > 1] array([ 1. a. numpy.= ---------------------------------------------a(s) a[0] s**(N-1) + a[1] s**(N-2) + . then the partial-fraction expansion H(s) is deﬁned as: b(s) b[0] s**(M-1) + b[1] s**(M-2) + .+ . + ----------(s-p[i]) (s-p[i])**2 (s-p[i])**n Returns r : ndarray Residues.signal) 483 .signal. k : ndarray Coefﬁcients of the direct polynomial term... then the partial fraction expansion has terms like r[i] r[i+1] r[i+n-1] ————– + —————— + .residue(b. See Also: invres... + —————— (1-p[i]z**(-1)) (1-p[i]z**(-1))**2 (1-p[i]z**(1))**n 3. + b[M-1] H(s) = -----..SciPy Reference Guide.+ ----------. Release 0.. unique_roots scipy. If M = len(b) and N = len(a) b(z) b[0] + b[1] z**(-1) + .+ k(s) (s-p[0]) (s-p[1]) (s-p[-1]) If there are any repeated roots (closer together than tol).. + a[N-1] z**(-N+1) r[0] r[-1] = ————— + .residuez(b. + b[M-1] z**(-M+1) H(z) = —— = ———————————————a(z) a[0] + a[1] z**(-1) + .. a.. rtype=’avg’) Compute partial-fraction expansion of b(z) / a(z).001. (1-p[0]z**(-1)) (1-p[-1]z**(-1)) If there are any repeated roots (closer than tol).

gstop[. analog]) bessel(N. polyval.SciPy Reference Guide. Chebyshev type I digital and analog ﬁlter design. gstop[. unique_roots scipy.. poly. scipy.. output]) Butterworth digital and analog ﬁlter design.. Design an Nth order lowpass digital or analog Butterworth ﬁlter and return the ﬁlter coefﬁcients in (B.. analog.k If M = len(b) and N = len(a) b(s) b[0] x**(M-1) + b[1] x**(M-2) + . Release 0. analog. gstop[. output=’ba’) Butterworth digital and analog ﬁlter design. btype. analog.butter(N. gstop.5 Matlab-style IIR ﬁlter design butter(N.signal. analog.signal. ws.invres(r. output]) cheb2ord(wp.13.0. gpass. analog]) ellip(N. Wn[. analog=0.... tol=0. ws. ws. Wn. ws. btype=’low’. Wn[. Chebyshev type II ﬁlter order selection. gpass. Wn[. ws.10. scipy.P. Elliptic (Cauer) digital and analog ﬁlter design. rtype=’avg’) Compute b(s) and a(s) from partial fraction expansion: r. btype. Wn[. p. k. output]) buttord(wp. btype. rp. Butterworth ﬁlter order selection.buttord(wp. analog]) cheby1(N. then the partial fraction expansion has terms like r[i] r[i+1] r[i+n-1] ——– + ———– + . polyval. + a[N-1] r[0] r[1] r[-1] = ——– + ——– + . + b[M-1] H(s) = —— = ———————————————a(s) a[0] x**(N-1) + a[1] x**(N-2) + . Reference .p. gpass. rs. output]) ellipord(wp. Wn[. Return the order of the lowest order digital Butterworth ﬁlter that loses no more than gpass dB in the passband and has at least gstop dB attenuation in the stopband.001. poly. output]) cheb1ord(wp. rp. + ———– (s-p[i]) (s-p[i])**2 (s-p[i])**n See Also: residue. gstop[. gpass. Elliptic (Cauer) ﬁlter order selection. Bessel digital and analog ﬁlter design. btype.. Parameters wp. analog=0) Butterworth ﬁlter order selection. analog]) cheby2(N. See Also: buttord. Chebyshev type I ﬁlter order selection. unique_roots 3. rs. ws : ﬂoat 484 Chapter 3. gpass. btype.A) or (Z. analog. Chebyshev type I digital and analog ﬁlter design. + ——— + k(s) (s-p[0]) (s-p[1]) (s-p[-1]) If there are any repeated roots (closer than tol).dev6665 See Also: invresz.signal.K) form.

0. Should be used with butter to give ﬁlter results.10. btype=’low’. For example: • Lowpass: wp = 0. ws = [0. wn : ndarray or ﬂoat The Butterworth natural frequency (i.signal.1.2.5]. rp. normalized from 0 to 1 (1 corresponds to pi radians / sample).dev6665 Passband and stopband edge frequencies.6] • Bandstop: wp = [0. Signal processing (scipy.1.3. ws : ﬂoat Passband and stopband edge frequencies.5] gpass : ﬂoat The maximum loss in the passband (dB). For example: • Lowpass: wp = 0.1. Returns ord : int The lowest order for a Butterworth ﬁlter which meets specs. ws = 0.signal. Design an Nth order lowpass digital or analog Chebyshev type I ﬁlter and return the ﬁlter coefﬁcients in (B.2. 0.3 • Highpass: wp = 0. gpass.5] gpass : ﬂoat The maximum loss in the passband (dB). analog=0) Chebyshev type I ﬁlter order selection. ws. 0. ws = 0. normalized from 0 to 1 (1 corresponds to pi radians / sample). output=’ba’) Chebyshev type I digital and analog ﬁlter design. Parameters wp.2.cheby1(N.2.signal) 485 . 0. optional Non-zero to design an analog ﬁlter (in this case wp and ws are in radians / second). 0. 0.1.2 • Bandpass: wp = [0. ws = 0.SciPy Reference Guide. Wn. ws = 0.2. ws = [0.2 • Bandpass: wp = [0.3 • Highpass: wp = 0.2. ws = [0. See Also: cheb1ord. the “3dB frequency”). analog : int. gstop.e. scipy. analog=0.cheb1ord(wp. Return the order of the lowest order digital Chebyshev Type I ﬁlter that loses no more than gpass dB in the passband and has at least gstop dB attenuation in the stopband.5]. 0.13. 0.6].6] • Bandstop: wp = [0. ws = [0.P. gstop : ﬂoat The minimum attenuation in the stopband (dB).K) form. Release 0.3. gstop : ﬂoat 3. scipy.A) or (Z.0.6].

gstop : ﬂoat The minimum attenuation in the stopband (dB). wn : ndarray or ﬂoat The Chebyshev natural frequency (the “3dB frequency”) for use with cheby1 to give ﬁlter results. rs. 0. ws = 0.signal.K) form.signal. gstop.10. 0. btype=’low’. ws : ﬂoat Passband and stopband edge frequencies. ws = 0. scipy.6].SciPy Reference Guide. Wn. normalized from 0 to 1 (1 corresponds to pi radians / sample).6] • Bandstop: wp = [0.1. Returns ord : int The lowest order for a Chebyshev type I ﬁlter that meets specs.dev6665 The minimum attenuation in the stopband (dB).A) or (Z.3. optional Non-zero to design an analog ﬁlter (in this case wp and ws are in radians / second). wn : ndarray or ﬂoat 486 Chapter 3.cheby2(N. analog=0.5]. analog=0) Chebyshev type II ﬁlter order selection.cheb2ord(wp. output=’ba’) Chebyshev type I digital and analog ﬁlter design. analog : int. Reference . See Also: cheb2ord. Description: Return the order of the lowest order digital Chebyshev Type II ﬁlter that loses no more than gpass dB in the passband and has at least gstop dB attenuation in the stopband.5] gpass : ﬂoat The maximum loss in the passband (dB). analog : int.2 • Bandpass: wp = [0. Design an Nth order lowpass digital or analog Chebyshev type I ﬁlter and return the ﬁlter coefﬁcients in (B.P.2.1. scipy.0. For example: • Lowpass: wp = 0.2.3 • Highpass: wp = 0. Release 0. gpass. ws = [0. Returns ord : int The lowest order for a Chebyshev type II ﬁlter that meets specs. Parameters wp. optional Non-zero to design an analog ﬁlter (in this case wp and ws are in radians / second).2. 0. 0. ws = [0. ws.

Return the order of the lowest order digital elliptic ﬁlter that loses no more than gpass dB in the passband and has at least gstop dB attenuation in the stopband.scipy. Design an Nth order lowpass digital or analog Bessel ﬁlter and return the ﬁlter coefﬁcients in (B.signal.2. btype=’low’. 3.K) form. scipy.2 • Bandpass: wp = [0. ws = 0.10. Release 0.6] • Bandstop: wp = [0. ws = [0. Parameters wp. output=’ba’) Bessel digital and analog ﬁlter design.3.1. normalized from 0 to 1 (1 corresponds to pi radians / sample). analog=0) Elliptic (Cauer) ﬁlter order selection. See Also: ellipord. optional Non-zero to design an analog ﬁlter (in this case wp and ws are in radians / second).signal. For example: • Lowpass: wp = 0.dev6665 The Chebyshev natural frequency (the “3dB frequency”) for use with cheby2 to give ﬁlter results.ellip(N. ws.SciPy Reference Guide. 0. Signal processing (scipy. Wn.5].0.P. analog=0. 0. scipy.2.P.A) or (Z.5] gpass : ﬂoat The maximum loss in the passband (dB).13.6]. rp. Design an Nth order lowpass digital or analog elliptic ﬁlter and return the ﬁlter coefﬁcients in (B. gpass.signal. Wn.K) form. output=’ba’) Elliptic (Cauer) digital and analog ﬁlter design. ws = [0. rs.1.2.ellipord(wp.3 • Highpass: wp = 0. analog : int. btype=’low’. ws : ﬂoat Passband and stopband edge frequencies. Returns : —— : ord : int The lowest order for an Elliptic (Cauer) ﬁlter that meets specs. wn : ndarray or ﬂoat The Chebyshev natural frequency (the “3dB frequency”) for use with ellip to give ﬁlter results. 0.bessel(N.A) or (Z. gstop. gstop : ﬂoat The minimum attenuation in the stopband (dB).signal) 487 . ws = 0. 0. analog=0.

T=None. Impulse response of a single-input. **kwargs[.10. gain). T[. X0. T. N]) step(system[. N]) step2(system. yout : ndarray A 1-D array containing the impulse response of the system (except for singularities at zero). X0.impulse(system. Parameters system : LTI class or tuple If speciﬁed as a tuple. T : array_like. U. class scipy. by using Impulse response of continuous-time system. or (A. Computed if not given. Parameters system : an instance of the LTI class or a tuple describing the system. B. X0.signal. The following gives the number of elements in the tuple and the interpretation. T. T. T.lti(*args. T. optional Time points. N=None) Step response of continuous-time system. Simulate output of a continuous-time linear system. T=None. N]) impulse2(system. D).dev6665 3. Step response of continuous-time system. C. N=None) Impulse response of continuous-time system.signal. Defaults to zero. scipy. X0. Step response of continuous-time system.13. optional The number of time points to compute (if T is not given). **kwords) lsim(system.0. **kwargs[. optional Initial state-vector. pole. Returns T : ndarray A 1-D array of time points. poles. **kwargs[. N]) Linear Time Invariant class which simpliﬁes representation. optional Initial state-vector (default is zero). X0 : array_like. (zero. T. gain) 4 (A. Methods impulse(system[. N : int.step(system. the system is described as (num.SciPy Reference Guide. T. X0.6 Linear Systems lti(*args. N]) output step(system[. continuous-time linear system. Release 0. X0. optional 488 Chapter 3. interp]) lsim2(system. B.signal. den) 3 (zeros. T : array_like. Step response of continuous-time system. scipy. C. 2 (num. X0=None. den). X0. Simulate output of a continuous-time linear system. D) X0 : array_like. X0]) impulse(system[. X0=None. N]) Impulse response of continuous-time system. **kwords) Linear Time Invariant class which simpliﬁes representation. U. Reference .

10. interp=1) Simulate output of a continuous-time linear system.signal.signal) 489 . T. yout : 1D ndarray System response. yout : 1D ndarray Step response of system.odeint.signal. U=None. T=None. then each column of the rank-2 array represents an input.dev6665 Time points (computed if not given).lsim(system. Parameters system : an instance of the LTI class or a tuple describing the system. scipy. B. 3.step2 scipy. gain) • 4: (A.signal.integrate. **kwargs) Simulate output of a continuous-time linear system. Parameters system : an instance of the LTI class or a tuple describing the system. Release 0.0. C. U. If there are multiple inputs. by using the ODE solver scipy. Returns T : 1D ndarray Output time points. X0=None.SciPy Reference Guide. The following gives the number of elements in the tuple and the interpretation: • 2: (num. Returns T : 1D ndarray Time values for the output. T : array_like The time steps at which the input is deﬁned and at which the output is desired. interp : {1. Signal processing (scipy. See Also: scipy.13. poles. D) U : array_like An input array describing the input at each time T (interpolation is assumed between given times).lsim2(system. 0} Whether to use linear (1) or zero-order hold (0) interpolation. X0=None. xout : ndarray Time-evolution of the state-vector. X0 : : The initial conditions on the state vector (zero by default). N : int Number of time points to compute if T is not given. den) • 3: (zeros.

X0 : array_like (1D). Notes This function uses scipy.0]. T=None. (zero. The default is 101 evenly spaced points on the interval [0. yout : ndarray The response of the system.odeint for the full list of arguments. Computed if not given. Release 0. See the notes below for more details. the system is described as (num.signal. Reference . xout : ndarray The time-evolution of the state-vector. C. then each column of the rank-2 array represents an input. D) U : array_like (1D or 2D). B. D). Returns T : 1D ndarray The time values for the output. If there are multiple inputs. pole. gain). If U is not given.integrate. C. optional Initial state-vector.10. N : int. optional The time steps at which the input is deﬁned and at which the output is desired. If X0 is not given. optional Time points.10. optional An input array describing the input at each time T.odeint to solve the system’s differential equations. Parameters system : LTI class or tuple If speciﬁed as a tuple. X0=None.SciPy Reference Guide. the initial conditions are assumed to be 0. Defaults to zero. T : array_like. T : array_like (1D or 2D). See the documentation for scipy. gain) • 4: (A. den).0. poles. scipy.dev6665 The following gives the number of elements in the tuple and the interpretation: • 2: (num. or (A. kwargs : dict Additional keyword arguments are passed on to the function odeint. N=None) Impulse response of continuous-time system. the input is assumed to be zero. B. optional The initial condition of the state vector.impulse(system. X0 : array_like. Linear interpolation is used between given times.integrate. Additional keywor